diff --git a/Documentation/Scripts/generateSwaggerApi.py b/Documentation/Scripts/generateSwaggerApi.py index 4c76310713..f2e1e3ac4b 100755 --- a/Documentation/Scripts/generateSwaggerApi.py +++ b/Documentation/Scripts/generateSwaggerApi.py @@ -45,8 +45,8 @@ files = { "js/actions/api-aqlfunction.js" : "aqlfunction", "arangod/RestHandler/RestBatchHandler.cpp" : "batch", "js/actions/_api/collection/app.js" : "collection", - "js/actions/_admin/database/app.js" : "database", "arangod/RestHandler/RestCursorHandler.cpp" : "cursor", + "js/actions/api-database.js" : "database", "arangod/RestHandler/RestDocumentHandler.cpp" : "document", "arangod/RestHandler/RestEdgeHandler.cpp" : "edge", "arangod/RestHandler/RestExportHandler.cpp" : "export", diff --git a/arangod/RestHandler/RestQueryHandler.cpp b/arangod/RestHandler/RestQueryHandler.cpp index 1d6ee7696f..3a0f26a5fb 100644 --- a/arangod/RestHandler/RestQueryHandler.cpp +++ b/arangod/RestHandler/RestQueryHandler.cpp @@ -109,7 +109,45 @@ HttpHandler::status_t RestQueryHandler::execute () { // ----------------------------------------------------------------------------- //////////////////////////////////////////////////////////////////////////////// -/// @brief returns the list of properties +/// @startDocuBlock GetApiQueryProperties +/// @brief returns the configuration for the AQL query tracking +/// +/// @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, +/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestQueryHandler::readQueryProperties () { @@ -145,7 +183,67 @@ bool RestQueryHandler::readQueryProperties () { } //////////////////////////////////////////////////////////////////////////////// -/// @brief returns the list of slow queries +/// @startDocuBlock GetApiQueryCurrent +/// @brief returns a list of currently running AQL queries +/// +/// @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, +/// +/// @endDocuBlock +//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock GetApiQuerySlow +/// @brief returns a list of slow running AQL queries +/// +/// @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, +/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestQueryHandler::readQuery (bool slow) { @@ -219,7 +317,20 @@ bool RestQueryHandler::readQuery () { } //////////////////////////////////////////////////////////////////////////////// -/// @brief removes the slow log +/// @startDocuBlock DeleteApiQuerySlow +/// @brief clears the list of slow AQL queries +/// +/// @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. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestQueryHandler::deleteQuerySlow () { @@ -239,7 +350,32 @@ bool RestQueryHandler::deleteQuerySlow () { } //////////////////////////////////////////////////////////////////////////////// -/// @brief interrupts a named query +/// @startDocuBlock DeleteApiQueryKill +/// @brief kills an AQL query +/// +/// @RESTHEADER{DELETE /_api/query/{query-id}, Kills a running AQL query} +/// +/// @RESTURLPARAMETERS +/// +/// @RESTURLPARAM{query-id,string,required} +/// The id of the query. +/// +/// Kills a running query. The query will be terminated at the next cancellation +/// point. +/// +/// @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. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestQueryHandler::deleteQuery (const string& name) { @@ -290,7 +426,52 @@ bool RestQueryHandler::deleteQuery () { } //////////////////////////////////////////////////////////////////////////////// -/// @brief changes the settings +/// @startDocuBlock PutApiQueryProperties +/// @brief changes the configuration for the AQL query tracking +/// +/// @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, +/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestQueryHandler::replaceProperties () { @@ -365,7 +546,65 @@ bool RestQueryHandler::replaceProperties () { } //////////////////////////////////////////////////////////////////////////////// -/// @brief parses a query +/// @startDocuBlock JSF_post_api_query +/// @brief parse an AQL query and return information about it +/// +/// @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 +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestQueryHandler::parseQuery () {