arangodb/Documentation/Books/Users/HttpAqlQuery

!CHAPTER HTTP Interface for AQL Queries

!SUBSECTION 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.


<!-- js/actions/api-explain.js -->
@startDocuBlock JSF_post_api_explain

<!-- ----------------------------------------------------------------------------- -->
@RESTHEADER{POST /_api/query, Parse an AQL query}

@RESTBODYPARAM{query,json,required}
To validate a query string without executing it, the query string can be
passed to the server via an HTTP POST request.

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

@RESTRETURNCODES

@RESTRETURNCODE{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.

@RESTRETURNCODE{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

Valid query:

@EXAMPLE_ARANGOSH_RUN{RestQueryValid}
    var url = "/_api/query";
    var body = '{ "query" : "FOR p IN products FILTER p.name == @name LIMIT 2 RETURN p.n" }';

    var response = logCurlRequest('POST', url, body);

    assert(response.code === 200);

    logJsonResponse(response);
@END_EXAMPLE_ARANGOSH_RUN

Invalid query:

@EXAMPLE_ARANGOSH_RUN{RestQueryInvalid}
    var url = "/_api/query";
    var body = '{ "query" : "FOR p IN products FILTER p.name = @name LIMIT 2 RETURN p.n" }';

    var response = logCurlRequest('POST', url, body);

    assert(response.code === 400);

    logJsonResponse(response);
@END_EXAMPLE_ARANGOSH_RUN

!SUBSECTION 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.

<!-- ----------------------------------------------------------------------------- -->
@RESTHEADER{GET /_api/query/properties, Returns the properties for the AQL query tracking}

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*.

- *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.

@RESTRETURNCODES

@RESTRETURNCODE{200}
Is returned when the list of queries can be retrieved successfully.

@RESTRETURNCODE{400}
The server will respond with *HTTP 400* in case of a malformed request,

<!-- ----------------------------------------------------------------------------- -->
@RESTHEADER{PUT /_api/query/properties, Changes the properties for the AQL query tracking}

@RESTBODYPARAM{properties,json,required}
The properties for query tracking in the current database. 

The properties need to be passed in the attribute *properties* in the body
of the HTTP request. *properties* needs to be 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*.

- *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.

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

@RESTRETURNCODES

@RESTRETURNCODE{200}
Is returned if the properties were changed successfully.

@RESTRETURNCODE{400}
The server will respond with *HTTP 400* in case of a malformed request,

<!-- ----------------------------------------------------------------------------- -->
@RESTHEADER{GET /_api/query/current, Returns the currently running AQL queries}

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

- *query*: the query string (potentially truncated)

- *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

@RESTRETURNCODES

@RESTRETURNCODE{200}
Is returned when the list of queries can be retrieved successfully.

@RESTRETURNCODE{400}
The server will respond with *HTTP 400* in case of a malformed request,

<!-- ----------------------------------------------------------------------------- -->
@RESTHEADER{GET /_api/query/slow, Returns the list of slow AQL queries}

Returns an array containing the last AQL queries that 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

- *query*: the query string (potentially truncated)

- *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

@RESTRETURNCODES

@RESTRETURNCODE{200}
Is returned when the list of queries can be retrieved successfully.

@RESTRETURNCODE{400}
The server will respond with *HTTP 400* in case of a malformed request,

<!-- ----------------------------------------------------------------------------- -->
@RESTHEADER{DELETE /_api/query/slow, Clears the list of slow AQL queries}

@RESTRETURNCODES

@RESTRETURNCODE{204}
The server will respond with *HTTP 200* when the list of queries was
cleared successfully.

@RESTRETURNCODE{400}
The server will respond with *HTTP 400* in case of a malformed request.

!SUBSECTION 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 cancellation point.

<!-- ----------------------------------------------------------------------------- -->
@RESTHEADER{DELETE /_api/query/{query-id}, Kills a running AQL query}

@RESTRETURNCODES

@RESTRETURNCODE{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.

@RESTRETURNCODE{400}
The server will respond with *HTTP 400* in case of a malformed request.

@RESTRETURNCODE{404}
The server will respond with *HTTP 404* when no query with the specified
id was found.