ArangoDB Manual

ArangoDB has an Http interface to syntactically validate AQL queries. Furthermore, it offers an Http interface to retrieve the execution plan for any valid AQL query.

Both functionalities do not actually execute the supplied AQL query, but only inspect it and return meta information about it.

POST /_api/explain (explains a query)

POST /_api/explain

To explain how a query would be executed (without actually executing it), the query string can be passed to the server via an HTTP POST request.

These query string needs to be passed in the attribute query of a JSON object as the body of the POST request. If the query references any bind variables, these must also be passed in the attribute bindVars.

If the query is valid, the server will respond with HTTP 200 and return a list of the individual query execution steps in the "plan" attribute of the response.

The server will respond with HTTP 400 in case of a malformed request, or if the query contains a parse error. The body of the response will contain the error details embedded in a JSON object. Omitting bind variables if the query references any will result also result in an HTTP 400 error.

Examples

Valid query:

> curl --data @- -X POST --dump - http://localhost:8529/_api/explain
{ "query" : "FOR u IN users FILTER u.id == @id LIMIT 2 RETURN u.name", "bindVars": { "id" : 3 } }

HTTP/1.1 200 OK
content-type: application/json

{
  "plan": [
    { "id": 1,
      "level": 1,
      "type": "for",
      "resultVariable": "u",
      "expression": {
        "type": "collection",
        "value": "users",
        "extra": {
          "accessType": "index",
          "index": {
            "id": "1392880787389/1425650910275",
            "type": "hash",
            "attributes": "id"
          }
        }
      }
    },
    {
      "id": 2,
      "level": 1,
      "type": "filter",
      "expression": {
        "type": "expression",
        "value": "u.id == 3"
      }
    },
    {
      "id": 3,
      "level": 1,
      "type": "limit",
      "offset": 0,
      "count": 2
    },
    {
      "id": 4,
      "level": 1,
      "type": "limit",
      "offset": 0,
      "count": 2
    },
    {
      "id": 5,
      "level": 1,
      "type": "return",
      "expression": {
        "type": "expression",
        "value": "u.name"
      }
    }
  ],
  "error": false,
  "code": 200
}

Invalid query:

> curl --data @- -X POST --dump - http://localhost:8529/_api/explain
{ "query" : "FOR u IN users FILTER u.name == @name LIMIT 2 RETURN u.n" }

HTTP/1.1 400 Bad Request
content-type: application/json

{
  "errorNum": 1551,
  "errorMessage": "no value specified for declared bind parameter 'name'",
  "error": true,
  "code": 400
}

POST /_api/query (parses a query)

POST /_api/query

To validate a query string without executing it, the query string can be passed to the server via an HTTP POST request.

These query string needs to be passed in the attribute query of a JSON object as the body of the POST request.

If the query is valid, the server will respond with HTTP 200 and return the names of the bind parameters it found in the query (if any) in the "bindVars" attribute of the response.

The server will respond with HTTP 400 in case of a malformed request, or if the query contains a parse error. The body of the response will contain the error details embedded in a JSON object.

Examples

Valid query:

> curl --data @- -X POST --dump - http://localhost:8529/_api/query
{ "query" : "FOR u IN users FILTER u.name == @name LIMIT 2 RETURN u.n" }

HTTP/1.1 200 OK
content-type: application/json

{
  "error": false,
  "bindVars": [
    "name"
  ],
  "code": 200
}

Invalid query:

> curl --data @- -X POST --dump - http://localhost:8529/_api/query
{ "query" : "FOR u IN users FILTER u.name = @name LIMIT 2 RETURN u.n" }

HTTP/1.1 400 Bad Request
content-type: application/json

{
  "errorNum": 1501,
  "errorMessage": "parse error: %s: parse error: 1:29 syntax error, unexpected assignment near ' = @name LIMIT 2 RETURN u.n'",
  "error": true,
  "code": 400
}

HTTP Interface for AQL Queries