ArangoDB v3.4 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent version here: Latest Docs

HTTP Interface for Traversals

The API endpoint /_api/traversal is deprecated from version 3.4.0 on. The preferred way to traverse graphs is with AQL.

ArangoDB’s graph traversals are executed on the server. Traversals can be initiated by clients by sending the traversal description for execution to the server.

Traversals in ArangoDB are used to walk over a graph stored in one edge collection. It can easily be described which edges of the graph should be followed and which actions should be performed on each visited vertex. Furthermore the ordering of visiting the nodes can be specified, for instance depth-first or breadth-first search are offered.

Executing Traversals via HTTP

executes a traversal

execute a server-side traversal

POST /_api/traversal

This route should no longer be used. It is considered as deprecated from version 3.4.0 on. It is superseded by AQL graph traversal.

A JSON object with these properties is required:

  • startVertex: id of the startVertex, e.g. “users/foo”.

  • edgeCollection: name of the collection that contains the edges.

  • graphName: name of the graph that contains the edges. Either edgeCollection or graphName has to be given. In case both values are set the graphName is preferred.

  • filter: default is to include all nodes: body (JavaScript code) of custom filter function function signature: (config, vertex, path) -> mixed can return four different string values:
  • “exclude” -> this vertex will not be visited.
  • “prune” -> the edges of this vertex will not be followed.
  • ”” or undefined -> visit the vertex and follow its edges.

  • Array -> containing any combination of the above. If there is at least one “exclude” or “prune” respectively is contained, it’s effect will occur.

    • minDepth: ANDed with any existing filters): visits only nodes in at least the given depth

    • maxDepth: ANDed with any existing filters visits only nodes in at most the given depth

    • visitor: body (JavaScript) code of custom visitor function function signature: (config, result, vertex, path, connected) -> void The visitor function can do anything, but its return value is ignored. To populate a result, use the result variable by reference. Note that the connected argument is only populated when the order attribute is set to “preorder-expander”.

    • direction: direction for traversal

  • if set, must be either “outbound”, “inbound”, or “any”

  • if not set, the expander attribute must be specified

    • init: body (JavaScript) code of custom result initialization function function signature: (config, result) -> void initialize any values in result with what is required

    • expander: body (JavaScript) code of custom expander function must be set if direction attribute is not set function signature: (config, vertex, path) -> array expander must return an array of the connections for vertex each connection is an object with the attributes edge and vertex

    • sort: body (JavaScript) code of a custom comparison function for the edges. The signature of this function is (l, r) -> integer (where l and r are edges) and must return -1 if l is smaller than, +1 if l is greater than, and 0 if l and r are equal. The reason for this is the following: The order of edges returned for a certain vertex is undefined. This is because there is no natural order of edges for a vertex with multiple connected edges. To explicitly define the order in which edges on the vertex are followed, you can specify an edge comparator function with this attribute. Note that the value here has to be a string to conform to the JSON standard, which in turn is parsed as function body on the server side. Furthermore note that this attribute is only used for the standard expanders. If you use your custom expander you have to do the sorting yourself within the expander code.

    • strategy: traversal strategy can be “depthfirst” or “breadthfirst”

    • order: traversal order can be “preorder”, “postorder” or “preorder-expander”

    • itemOrder: item iteration order can be “forward” or “backward”

    • uniqueness: specifies uniqueness for vertices and edges visited. If set, must be an object like this:

"uniqueness": {"vertices": "none"|"global"|"path", "edges": "none"|"global"|"path"}

  • maxIterations: Maximum number of iterations in each traversal. This number can be set to prevent endless loops in traversal of cyclic graphs. When a traversal performs as many iterations as the maxIterations value, the traversal will abort with an error. If maxIterations is not set, a server-defined value may be used.

Starts a traversal starting from a given vertex and following. edges contained in a given edgeCollection. The request must contain the following attributes.

If the Traversal is successfully executed HTTP 200 will be returned. Additionally the result object will be returned by the traversal.

For successful traversals, the returned JSON object has the following properties:

  • error: boolean flag to indicate if an error occurred (false in this case)

  • code: the HTTP status code

  • result: the return value of the traversal

If the traversal specification is either missing or malformed, the server will respond with HTTP 400.

The body of the response will then contain a JSON object with additional error details. The object has the following attributes:

  • error: boolean flag to indicate that an error occurred (true in this case)

  • code: the HTTP status code

  • errorNum: the server error number

  • errorMessage: a descriptive error message

Return codes

  • 200: If the traversal is fully executed HTTP 200 will be returned.

  • 400: If the traversal specification is either missing or malformed, the server will respond with HTTP 400.

  • 404: The server will responded with HTTP 404 if the specified edge collection does not exist, or the specified start vertex cannot be found.

  • 500: The server will responded with HTTP 500 when an error occurs inside the traversal or if a traversal performs more than maxIterations iterations.

Examples

In the following examples the underlying graph will contain five persons Alice, Bob, Charlie, Dave and Eve. We will have the following directed relations:

  • Alice knows Bob
  • Bob knows Charlie
  • Bob knows Dave
  • Eve knows Alice
  • Eve knows Bob

The starting vertex will always be Alice.

Follow only outbound edges

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "outbound" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Follow only inbound edges

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "inbound" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Follow any direction of edges

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "any", 
  "uniqueness" : { 
    "vertices" : "none", 
    "edges" : "global" 
  } 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Excluding Charlie and Bob

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "outbound", 
  "filter" : "if (vertex.name === \"Bob\" ||     vertex.name === \"Charlie\") {  return \"exclude\";}return;" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Do not follow edges from Bob

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "outbound", 
  "filter" : "if (vertex.name === \"Bob\") {return \"prune\";}return;" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Visit only nodes in a depth of at least 2

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "outbound", 
  "minDepth" : 2 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Visit only nodes in a depth of at most 1

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "outbound", 
  "maxDepth" : 1 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Using a visitor function to return vertex ids only

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "outbound", 
  "visitor" : "result.visited.vertices.push(vertex._id);" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Count all visited nodes and return a list of nodes only

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "outbound", 
  "init" : "result.visited = 0; result.myVertices = [ ];", 
  "visitor" : "result.visited++; result.myVertices.push(vertex);" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Expand only inbound edges of Alice and outbound edges of Eve

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "expander" : "var connections = [ ];if (vertex.name === \"Alice\") {config.datasource.getInEdges(vertex).forEach(function (e) {connections.push({ vertex: require(\"internal\").db._document(e._from), edge: e});});}if (vertex.name === \"Eve\") {config.datasource.getOutEdges(vertex).forEach(function (e) {connections.push({vertex: require(\"internal\").db._document(e._to), edge: e});});}return connections;" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Follow the depthfirst strategy

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "any", 
  "strategy" : "depthfirst" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Using postorder ordering

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "any", 
  "order" : "postorder" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Using backward item-ordering:

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "any", 
  "itemOrder" : "backward" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Edges should only be included once globally, but nodes are included every time they are visited

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "any", 
  "uniqueness" : { 
    "vertices" : "none", 
    "edges" : "global" 
  } 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

If the underlying graph is cyclic, maxIterations should be set

The underlying graph has two vertices Alice and Bob. With the directed edges:

  • Alice knows Bob
  • Bob knows Alice
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/traversal <<EOF
{ 
  "startVertex" : "persons/alice", 
  "graphName" : "knows_graph", 
  "direction" : "any", 
  "uniqueness" : { 
    "vertices" : "none", 
    "edges" : "none" 
  }, 
  "maxIterations" : 5 
}
EOF

HTTP/1.1 Internal Server Error
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

All examples were using this graph:

Persons relation Example Graph

❮  Edges

© ArangoDB - the native multi-model NoSQL database