mirror of https://gitee.com/bigwinds/arangodb
108 lines
3.7 KiB
Plaintext
108 lines
3.7 KiB
Plaintext
!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
|