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:

    @startDocuBlockInline RestQueryValid
    @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
    @endDocuBlock RestQueryValid

Invalid query:

    @startDocuBlockInline RestQueryInValid
    @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
    @endDocuBlock RestQueryInValid

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

<!--arangod/RestHandler/RestQueryHandler.cpp -->
@startDocuBlock GetApiQueryProperties

<!--arangod/RestHandler/RestQueryHandler.cpp -->
@startDocuBlock PutApiQueryProperties

<!--arangod/RestHandler/RestQueryHandler.cpp -->
@startDocuBlock GetApiQueryCurrent

<!--arangod/RestHandler/RestQueryHandler.cpp -->
@startDocuBlock GetApiQuerySlow

<!--arangod/RestHandler/RestQueryHandler.cpp -->
@startDocuBlock DeleteApiQuerySlow

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

<!--arangod/RestHandler/RestQueryHandler.cpp -->
@startDocuBlock DeleteApiQueryKill