HTTP Interface for AQL Queries

Explaining and parsing queries

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.

Explain an AQL query

explain an AQL query and return information about it

POST /_api/explain

A JSON object describing the query and query parameters.

Request Body

  • query (string, required): the query which you want explained; If the query references any bind variables, these must also be passed in the attribute bindVars. Additional options for the query can be passed in the options attribute.

  • bindVars (array of objects, optional): key/value pairs representing the bind parameters.

  • options (object, optional): Options for the query

    • allPlans (boolean, optional): if set to true, all possible execution plans will be returned. The default is false, meaning only the optimal plan will be returned.

    • maxNumberOfPlans (integer, optional): an optional maximum number of plans that the optimizer is allowed to generate. Setting this attribute to a low value allows to put a cap on the amount of work the optimizer does.

    • optimizer (object, optional): Options related to the query optimizer.

      • rules (array of strings, optional): A list of to-be-included or to-be-excluded optimizer rules can be put into this attribute, telling the optimizer to include or exclude specific rules. To disable a rule, prefix its name with a -, to enable a rule, prefix it with a +. There is also a pseudo-rule all, which matches all optimizer rules. -all disables all rules.

To explain how an AQL query would be executed on the server, the query string can be sent to the server via an HTTP POST request. The server will then validate the query and create an execution plan for it. The execution plan will be returned, but the query will not be executed.

The execution plan that is returned by the server can be used to estimate the probable performance of the query. Though the actual performance will depend on many different factors, the execution plan normally can provide some rough estimates on the amount of work the server needs to do in order to actually run the query.

By default, the explain operation will return the optimal plan as chosen by the query optimizer The optimal plan is the plan with the lowest total estimated cost. The plan will be returned in the attribute plan of the response object. If the option allPlans is specified in the request, the result will contain all plans created by the optimizer. The plans will then be returned in the attribute plans.

The result will also contain an attribute warnings, which is an array of warnings that occurred during optimization or execution plan creation. Additionally, a stats attribute is contained in the result with some optimizer statistics. If allPlans is set to false, the result will contain an attribute cacheable that states whether the query results can be cached on the server if the query result cache were used. The cacheable attribute is not present when allPlans is set to true.

Each plan in the result is a JSON object with the following attributes:

  • nodes: the array of execution nodes of the plan.

  • estimatedCost: the total estimated cost for the plan. If there are multiple plans, the optimizer will choose the plan with the lowest total cost.

  • collections: an array of collections used in the query

  • rules: an array of rules the optimizer applied.

  • variables: array of variables used in the query (note: this may contain internal variables created by the optimizer)

Responses

HTTP 200: If the query is valid, the server will respond with HTTP 200 and return the optimal execution plan in the plan attribute of the response. If option allPlans was set in the request, an array of plans will be returned in the allPlans attribute instead.

HTTP 400: 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 also result in an HTTP 400 error.

HTTP 404: The server will respond with HTTP 404 in case a non-existing collection is accessed in the query.

Examples

Valid query

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{ 
  "query" : "FOR p IN products RETURN p" 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 1003
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

A plan with some optimizer rules applied

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{ 
  "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name" 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 2627
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Using some options

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{ 
  "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name", 
  "options" : { 
    "maxNumberOfPlans" : 2, 
    "allPlans" : true, 
    "optimizer" : { 
      "rules" : [ 
        "-all", 
        "+use-index-for-sort", 
        "+use-index-range" 
      ] 
    } 
  } 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 3148
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Returning all plans

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{ 
  "query" : "FOR p IN products FILTER p.id == 25 RETURN p", 
  "options" : { 
    "allPlans" : true 
  } 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 1709
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

A query that produces a warning

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{ 
  "query" : "FOR i IN 1..10 RETURN 1 / 0" 
}
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 1686
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Invalid query (missing bind parameter)

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{ 
  "query" : "FOR p IN products FILTER p.id == @id LIMIT 2 RETURN p.n" 
}
EOF

HTTP/1.1 400 Bad Request
content-type: application/json
connection: Keep-Alive
content-length: 126
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

The data returned in the plan attribute of the result contains one element per AQL top-level statement (i.e. FOR, RETURN, FILTER etc.). If the query optimizer removed some unnecessary statements, the result might also contain less elements than there were top-level statements in the AQL query.

The following example shows a query with a non-sensible filter condition that the optimizer has removed so that there are less top-level statements.

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{ "query" : "FOR i IN [ 1, 2, 3 ] FILTER 1 == 2 RETURN i" }
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 1430
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Parse an AQL query

parse an AQL query and return information about it

POST /_api/query

Request Body

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

This endpoint is for query validation only. To actually query the database, see /api/cursor.

Responses

HTTP 200: 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. It will also return an array of the collections used in the query in the collections attribute. If a query can be parsed successfully, the ast attribute of the returned JSON will contain the abstract syntax tree representation of the query. The format of the ast is subject to change in future versions of ArangoDB, but it can be used to inspect how ArangoDB interprets a given query. Note that the abstract syntax tree will be returned without any optimizations applied to it.

HTTP 400: 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

a valid query

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/query <<EOF
{ "query" : "FOR i IN 1..100 FILTER i > 10 LIMIT 2 RETURN i * 3" }
EOF

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 620
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

an invalid query

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/query <<EOF
{ "query" : "FOR i IN 1..100 FILTER i = 1 LIMIT 2 RETURN i * 3" }
EOF

HTTP/1.1 400 Bad Request
content-type: application/json
connection: Keep-Alive
content-length: 143
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Query tracking

ArangoDB has an HTTP interface for retrieving the lists of currently executing AQL queries and the list of slow AQL queries. In order to make meaningful use of these APIs, query tracking needs to be enabled in the database the HTTP request is executed for.

Returns the properties for the AQL query tracking

returns the configuration for the AQL query tracking

GET /_api/query/properties

Returns the current query tracking configuration. The configuration is a JSON object with the following properties:

  • enabled: if set to true, then queries will be tracked. If set to false, neither queries nor slow queries will be tracked.

  • trackSlowQueries: if set to true, then slow queries will be tracked in the list of slow queries if their runtime exceeds the value set in slowQueryThreshold. In order for slow queries to be tracked, the enabled property must also be set to true.

  • trackBindVars: if set to true, then bind variables used in queries will be tracked.

  • maxSlowQueries: the maximum number of slow queries to keep in the list of slow queries. If the list of slow queries is full, the oldest entry in it will be discarded when additional slow queries occur.

  • slowQueryThreshold: the threshold value for treating a query as slow. A query with a runtime greater or equal to this threshold value will be put into the list of slow queries when slow query tracking is enabled. The value for slowQueryThreshold is specified in seconds.

  • maxQueryStringLength: the maximum query string length to keep in the list of queries. Query strings can have arbitrary lengths, and this property can be used to save memory in case very long query strings are used. The value is specified in bytes.

Responses

HTTP 200: Is returned if properties were retrieved successfully.

HTTP 400: The server will respond with HTTP 400 in case of a malformed request,

Changes the properties for the AQL query tracking

changes the configuration for the AQL query tracking

PUT /_api/query/properties

Request Body

  • enabled (boolean, required): If set to true, then queries will be tracked. If set to false, neither queries nor slow queries will be tracked.

  • trackSlowQueries (boolean, required): If set to true, then slow queries will be tracked in the list of slow queries if their runtime exceeds the value set in slowQueryThreshold. In order for slow queries to be tracked, the enabled property must also be set to true.

  • trackBindVars (boolean, required): If set to true, then the bind variables used in queries will be tracked along with queries.

  • maxSlowQueries (integer, required): The maximum number of slow queries to keep in the list of slow queries. If the list of slow queries is full, the oldest entry in it will be discarded when additional slow queries occur.

  • slowQueryThreshold (integer, required): The threshold value for treating a query as slow. A query with a runtime greater or equal to this threshold value will be put into the list of slow queries when slow query tracking is enabled. The value for slowQueryThreshold is specified in seconds.

  • maxQueryStringLength (integer, required): The maximum query string length to keep in the list of queries. Query strings can have arbitrary lengths, and this property can be used to save memory in case very long query strings are used. The value is specified in bytes.

The properties need to be passed in the attribute properties in the body of the HTTP request. properties needs to be a JSON object.

After the properties have been changed, the current set of properties will be returned in the HTTP response.

Responses

HTTP 200: Is returned if the properties were changed successfully.

HTTP 400: The server will respond with HTTP 400 in case of a malformed request,

Returns the currently running AQL queries

returns a list of currently running AQL queries

GET /_api/query/current

Query Parameters

  • all (boolean, optional): If set to true, will return the currently running queries in all databases, not just the selected one. Using the parameter is only allowed in the system database and with superuser privileges.

Returns an array containing the AQL queries currently running in the selected database. Each query is a JSON object with the following attributes:

  • id: the query’s id

  • database: the name of the database the query runs in

  • user: the name of the user that started the query

  • query: the query string (potentially truncated)

  • bindVars: the bind parameter values used by the query

  • started: the date and time when the query was started

  • runTime: the query’s run time up to the point the list of queries was queried

  • state: the query’s current execution state (as a string). One of:
    • "initializing"
    • "parsing"
    • "optimizing ast"
    • "loading collections"
    • "instantiating plan"
    • "optimizing plan"
    • "executing"
    • "finalizing"
    • "finished"
    • "killed"
    • "invalid"
  • stream: whether or not the query uses a streaming cursor

Responses

HTTP 200: Is returned when the list of queries can be retrieved successfully.

HTTP 400: The server will respond with HTTP 400 in case of a malformed request,

HTTP 403: HTTP 403 is returned in case the all parameter was used, but the request was made in a different database than _system, or by an non-privileged user.

Returns the list of slow AQL queries

returns a list of slow running AQL queries

GET /_api/query/slow

Query Parameters

  • all (boolean, optional): If set to true, will return the slow queries from all databases, not just the selected one. Using the parameter is only allowed in the system database and with superuser privileges.

Returns an array containing the last AQL queries that are finished and have exceeded the slow query threshold in the selected database. The maximum amount of queries in the list can be controlled by setting the query tracking property maxSlowQueries. The threshold for treating a query as slow can be adjusted by setting the query tracking property slowQueryThreshold.

Each query is a JSON object with the following attributes:

  • id: the query’s id

  • database: the name of the database the query runs in

  • user: the name of the user that started the query

  • query: the query string (potentially truncated)

  • bindVars: the bind parameter values used by the query

  • started: the date and time when the query was started

  • runTime: the query’s total run time

  • state: the query’s current execution state (will always be “finished” for the list of slow queries)

  • stream: whether or not the query uses a streaming cursor

Responses

HTTP 200: Is returned when the list of queries can be retrieved successfully.

HTTP 400: The server will respond with HTTP 400 in case of a malformed request,

HTTP 403: HTTP 403 is returned in case the all parameter was used, but the request was made in a different database than _system, or by an non-privileged user.

Clears the list of slow AQL queries

clears the list of slow AQL queries

DELETE /_api/query/slow

Query Parameters

  • all (boolean, optional): If set to true, will clear the slow query history in all databases, not just the selected one. Using the parameter is only allowed in the system database and with superuser privileges.

Clears the list of slow AQL queries in the currently selected database

Responses

HTTP 200: The server will respond with HTTP 200 when the list of queries was cleared successfully.

HTTP 400: The server will respond with HTTP 400 in case of a malformed request.

Killing queries

Running AQL queries can also be killed on the server. ArangoDB provides a kill facility via an HTTP interface. To kill a running query, its id (as returned for the query in the list of currently running queries) must be specified. The kill flag of the query will then be set, and the query will be aborted as soon as it reaches a cancelation point.

Kills a running AQL query

kills an AQL query

DELETE /_api/query/{query-id}

Path Parameters

  • query-id (string, required): The id of the query.

Query Parameters

  • all (boolean, optional): If set to true, will attempt to kill the specified query in all databases, not just the selected one. Using the parameter is only allowed in the system database and with superuser privileges.

Kills a running query in the currently selected database. The query will be terminated at the next cancelation point.

Responses

HTTP 200: The server will respond with HTTP 200 when the query was still running when the kill request was executed and the query’s kill flag was set.

HTTP 400: The server will respond with HTTP 400 in case of a malformed request.

HTTP 403: HTTP 403 is returned in case the all parameter was used, but the request was made in a different database than _system, or by an non-privileged user.

HTTP 404: The server will respond with HTTP 404 when no query with the specified id was found.

❮  Accessing Cursors

© ArangoDB - the native multi-model NoSQL database