mirror of https://gitee.com/bigwinds/arangodb
245 lines
9.1 KiB
Plaintext
245 lines
9.1 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:
|
|
|
|
@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.
|