1
0
Fork 0

added documentation for AQL SHORTEST_PATH

This commit is contained in:
Jan Steemann 2014-02-26 13:42:56 +01:00
parent 90d6a337da
commit 785df6f016
1 changed files with 100 additions and 0 deletions

View File

@ -1537,6 +1537,106 @@ If no bounds are set, a traversal might run into an endless loop in a cyclic gra
and even in a non-cyclic graph, traversing far into the graph might consume a lot of processing
time and memory for the result set.
- @FN{SHORTEST_PATH(@FA{vertexcollection}, @FA{edgecollection}, @FA{startVertex}, @FA{endVertex}, @FA{direction}, @FA{options})}:
determines the first shortest path from the @FA{startVertex} to the @FA{endVertex}.
Both vertices must be present in the vertex collection specified in @FA{vertexcollection},
and any connecting edges must be present in the collection specified by @FA{edgecollection}.
Vertex connectivity is specified by the @FA{direction} parameter:
- `"outbound"`: vertices are connected in `_from` to `_to` order
- `"inbound"`: vertices are connected in `_to` to `_from` order
- `"any"`: vertices are connected in both `_to` to `_from` and in
`_from` to `_to` order
The search is aborted when a shortest path is found. Only the first shortest path will be
returned. Any vertex will be visited at most once by the search.
Additional options for the traversal can be provided via the @FA{options} document:
- `maxIterations`: Maximum number of iterations in the search. This number can be
set to bound long-running searches. When a search performs as many iterations as the
`maxIterations` value, the search will abort with an error. If `maxIterations` is not
set, a server-defined value may be used.
- `paths`: if `true`, the result will not only contain the vertices along the shortest
path, but also the connecting edges. If `false`, only the encountered vertices will
be returned.
- `distance`: an optional custom function to be used when calculating the distance
between a vertex and a neighboring vertex. The expected function signature is:
function (config, vertex1, vertex2, edge)
Both vertices and the connecting edge will be passed into the function. The function
is expected to return a numeric value that expresses the distance between the two
vertices. Higher values will mean higher distances, giving the connection a lower
priority in further analysis.
If no custom distance function is specified, all vertices are assumed to have the
same distance (1) to each other. If a function name is specified, it must have been
registered as a regular user-defined AQL function.
- `followEdges`: an optional list of example edge documents that the search will
expand into. If no examples are given, the search will follow all edges. If one
or many edge examples are given, the search will only follow an edge if it matches
at least one of the specified examples. `followEdges` can also be a string with the
name of an AQL user-defined function that should be responsible for checking if an
edge should be followed. In this case, the AQL function will is expected to have the
following signature:
function (config, vertex, edge, path)
The function is expected to return a boolean value. If ìt returns `true`, the edge
will be followed. If `false` is returned, the edge will be ignored.
- `filterVertices`: an optional list of example vertex documents that the search will
treat specially. If no examples are given, the search will handle all encountered
vertices equally. If one or many vertex examples are given, the search will exclude
the vertex from the result and/or not descend into it. Optionally, `filterVertices` can
contain the name of a user-defined AQL function that should be responsible for filtering.
If so, the AQL function is expected to have the following signature:
function (config, vertex, path)
If a custom AQL function is used, it is expected to return one of the following values:
- `[ ]`: include the vertex in the result and descend into its connected edges
- `[ "prune" ]`: will include the vertex in the result but not descend into its connected edges
- `[ "exclude" ]`: will not include the vertex in the result but descend into its connected edges
- `[ "prune", "exclude" ]`: will completely ignore the vertex and its connected edges
The result of the SHORTEST_PATH function is a list with the components of the shortest
path. Each component is a document consisting of the following attributes:
- `vertex`: the vertex at the traversal point
- `path`: The path history for the traversal point. The path is a document with the
attributes `vertices` and `edges`, which are both lists. Note that `path` is only present
in the result if the `paths` attribute is set in the @FA{options}.
Example calls:
SHORTEST_PATH(cities, motorways, "cities/CGN", "cities/MUC", "outbound", {
paths: true
})
// using a user-defined distance function
SHORTEST_PATH(cities, motorways, "cities/CGN", "cities/MUC", "outbound", {
paths: true,
distance: "myfunctions::citydistance"
})
// using a user-defined function to filter edges
SHORTEST_PATH(cities, motorways, "cities/CGN", "cities/MUC", "outbound", {
paths: true,
followEdges: "myfunctions::checkedge"
})
// to register a custom AQL distance function, execute something in the fashion of the
// following commands in arangosh once:
var aqlfunctions = require("org/arangodb/aql/functions");
// this is the actual distance function
aqlfunctions.register("myfunctions::distance", function (config, vertex1, vertex2, edge) {
return Math.sqrt(Math.pow(vertex1.x - vertex2.x) + Math.pow(vertex1.y - vertex2.y));
}, false);
// this is the filter function for the edges
aqlfunctions.register("myfunctions::checkedge", function (config, vertex, edge, path) {
return (edge.underConstruction === false); // don't follow these edges
}, false);
- @FN{EDGES(@FA{edgecollection}, @FA{startvertex}, @FA{direction}, @FA{edgeexamples})}:
return all edges connected to the vertex @FA{startvertex} as a list. The possible values for
@FA{direction} are: