POST /_api/explain
-To explain how a query would be executed (without actually executing it), the query string can be passed to the server via an HTTP POST request.
-These query string needs to be passed in the attribute query of a JSON object as the body of the POST request. If the query references any bind variables, these must also be passed in the attribute bindVars.
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, but will not execute it.
+The execution plan that is returned by the server can be used to estimate the probable performance of an AQL query. Though the actual performance will depend on many different factors, the execution plan normally can give some good hint on the amount of work the server needs to do in order to actually run the query.
+The query string needs to be passed in the attribute query of a JSON object as the body of the POST request. If the query references any bind variables, these must also be passed in the attribute bindVars.
If the query is valid, the server will respond with HTTP 200 and return a list of the individual query execution steps in the "plan" attribute of the response.
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 result also result in an HTTP 400 error.
Examples
@@ -27,54 +28,50 @@ content-type: application/json
{
"plan": [
- { "id": 1,
- "level": 1,
- "type": "for",
- "resultVariable": "u",
- "expression": {
- "type": "collection",
- "value": "users",
- "extra": {
- "accessType": "index",
- "index": {
- "id": "1392880787389/1425650910275",
- "type": "hash",
- "attributes": "id"
- }
- }
- }
+ {
+ "id" : 1,
+ "loopLevel" : 1,
+ "type" : "for",
+ "resultVariable" : "u",
+ "expression" : {
+ "type" : "collection",
+ "value" : "users",
+ "extra" : {
+ "accessType" : "all"
+ }
+ }
},
- {
- "id": 2,
- "level": 1,
- "type": "filter",
- "expression": {
- "type": "expression",
- "value": "u.id == 3"
- }
+ {
+ "id" : 2,
+ "loopLevel" : 1,
+ "type" : "filter",
+ "expression" : {
+ "type" : "expression",
+ "value" : "u.id == 3"
+ }
},
- {
- "id": 3,
- "level": 1,
- "type": "limit",
- "offset": 0,
- "count": 2
+ {
+ "id" : 3,
+ "loopLevel" : 1,
+ "type" : "limit",
+ "offset" : 0,
+ "count" : 2
},
- {
- "id": 4,
- "level": 1,
- "type": "limit",
- "offset": 0,
- "count": 2
+ {
+ "id" : 4,
+ "loopLevel" : 1,
+ "type" : "limit",
+ "offset" : 0,
+ "count" : 2
},
- {
- "id": 5,
- "level": 1,
- "type": "return",
- "expression": {
- "type": "expression",
- "value": "u.name"
- }
+ {
+ "id" : 5,
+ "loopLevel" : 1,
+ "type" : "return",
+ "expression" : {
+ "type" : "expression",
+ "value" : "u.name"
+ }
}
],
"error": false,
@@ -93,7 +90,21 @@ content-type: application/json
"error": true,
"code": 400
}
-
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 optimiser removed some unnecessary statements, the result might also contain less elements than there were top-level statements in the AQL query.
The top-level statements will appear in the result in the same order in which they have been used in the original query. Each result element has at most the following attributes:
+id: the row number of the top-level statement, starting at 1type: the type of the top-level statement (e.g. for, return ...)loopLevel: the nesting level of the top-level statement, starting at 1 Depending on the type of top-level statement, there might be other attributes providing additional information, for example, if and which indexed will be used. Many top-level statements will provide an expression attribute that contains data about the expression they operate on. This is true for FOR, FILTER, SORT, COLLECT, and RETURN. The expression attribute has the following sub-attributes:type: the type of the expression. Some possible values are:collection: an iteration over documents from a collection. The value attribute will then contain the collection name. The extra attribute will contain information about if and which index is used when accessing the documents from the collection. If no index is used, the accessType sub-attribute of the extra attribute will have the value all, otherwise it will be index.list: a list of values. The value attribute will contain the list elements.reference: a reference to another variable. The value attribute will contain the name of the variable that is referenced.Please note that the structure of the explain result data might change in future versions of ArangoDB without further notice and without maintaining backwards compatibility.
+POST /_api/query
diff --git a/js/actions/system/api-explain.js b/js/actions/system/api-explain.js
index 4ede688802..736777169b 100644
--- a/js/actions/system/api-explain.js
+++ b/js/actions/system/api-explain.js
@@ -43,10 +43,16 @@ var actions = require("org/arangodb/actions");
///
/// @REST{POST /_api/explain}
///
-/// To explain how a query would be executed (without actually executing it),
-/// the query string can be passed to the server via an HTTP POST request.
+/// 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, but will not execute it.
///
-/// These query string needs to be passed in the attribute @LIT{query} of a JSON
+/// The execution plan that is returned by the server can be used to estimate the
+/// probable performance of an AQL query. Though the actual performance will depend
+/// on many different factors, the execution plan normally can give some good hint
+/// on the amount of work the server needs to do in order to actually run the query.
+///
+/// The query string needs to be passed in the attribute @LIT{query} of a JSON
/// object as the body of the POST request. If the query references any bind
/// variables, these must also be passed in the attribute @LIT{bindVars}.
///
@@ -69,6 +75,41 @@ var actions = require("org/arangodb/actions");
/// Invalid query:
///
/// @verbinclude api-explain-invalid
+///
+/// The data returned in the @LIT{plan} attribute of the result contains one
+/// element per AQL top-level statement (i.e. @LIT{FOR}, @LIT{RETURN},
+/// @LIT{FILTER} etc.). If the query optimiser removed some unnecessary statements,
+/// the result might also contain less elements than there were top-level
+/// statements in the AQL query.
+///
+/// The top-level statements will appear in the result in the same order in which
+/// they have been used in the original query. Each result element has at most the
+/// following attributes:
+/// - @LIT{id}: the row number of the top-level statement, starting at 1
+/// - @LIT{type}: the type of the top-level statement (e.g. @LIT{for}, @LIT{return} ...)
+/// - @LIT{loopLevel}: the nesting level of the top-level statement, starting at 1
+/// Depending on the type of top-level statement, there might be other attributes
+/// providing additional information, for example, if and which indexed will be
+/// used.
+/// Many top-level statements will provide an @LIT{expression} attribute that
+/// contains data about the expression they operate on. This is true for @LIT{FOR},
+/// @LIT{FILTER}, @LIT{SORT}, @LIT{COLLECT}, and @LIT{RETURN}. The @LIT{expression}
+/// attribute has the following sub-attributes:
+/// - @LIT{type}: the type of the expression. Some possible values are:
+/// - @LIT{collection}: an iteration over documents from a collection. The
+/// @LIT{value} attribute will then contain the collection name. The @LIT{extra}
+/// attribute will contain information about if and which index is used when
+/// accessing the documents from the collection. If no index is used, the
+/// @LIT{accessType} sub-attribute of the @LIT{extra} attribute will have the
+/// value @LIT{all}, otherwise it will be @LIT{index}.
+/// - @LIT{list}: a list of values. The @LIT{value} attribute will contain the
+/// list elements.
+/// - @LIT{reference}: a reference to another variable. The @LIT{value} attribute
+/// will contain the name of the variable that is referenced.
+///
+/// Please note that the structure of the explain result data might change in future
+/// versions of ArangoDB without further notice and without maintaining backwards
+/// compatibility.
////////////////////////////////////////////////////////////////////////////////
function POST_api_explain (req, res) {