Arango logo

ArangoDB v4.x is under development and not released yet.

This documentation is not final and potentially incomplete.

AQL query plan cache HTTP API

List the AQL execution plans that are in the cache as well as clear the cache with the HTTP interface

Introduced in: v3.12.4

To cache execution plans for AQL queries as well as to utilize cached plans, set the usePlanCache query option to true when issuing a query. See HTTP interfaces for AQL queries for details and The execution plan cache for AQL queries for general information about the feature.

List the entries of the AQL query plan cache

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/query-plan-cache

Returns metadata about the AQL execution plans currently stored in the query plan cache of the selected database. The execution plans themselves aren’t included.

This requires read privileges for the selected database. In addition, only those query plans are returned for which the current user has at least read permissions on all collections and Views included in the query.

Path Parameters

  • The name of the database.

    Example: _system

Query Parameters
    HTTP Headers
      Responses

      • The query plan cache entries are returned successfully.

          Response Body application/json

        • A list of query plan cache entries.

          Each entry describes a cached query plan but doesn’t include the execution plan itself.

          • A subset of the original bind parameters with only the collection bind parameters (e.g. @@coll). They need to have the same names and values for utilizing a cached plan.

          • The date and time at which the query plan has been added to the cache (in ISO 8601 format).

          • The collections and Views involved in the query.

          • The value of the fullCount query option in the original query. This option generally leads to different execution plans.

          • The plan cache key.

          • How many times the cached plan has been utilized so far.

          • How much memory the plan cache entry takes up for the execution plan, query string, and so on (in bytes).

          • The query string.

          • The hash value of the query string.

      Retrieve the entries stored in the AQL query plan cache of the current database:

      curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/query-plan-cache'
      Show output
      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 450
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ 
  { 
    "hash" : "3789565983385787052", 
    "query" : "RETURN 42", 
    "queryHash" : 9621679463990086000, 
    "bindVars" : { 
    }, 
    "fullCount" : false, 
    "dataSources" : [ ], 
    "created" : "2025-01-15T09:40:57Z", 
    "hits" : 0, 
    "memoryUsage" : 1972 
  }, 
  { 
    "hash" : "8890964066160157016", 
    "query" : "FOR doc IN @@coll FILTER doc.attr == @val RETURN doc", 
    "queryHash" : 5130438352381113000, 
    "bindVars" : { 
      "@coll" : "coll" 
    }, 
    "fullCount" : false, 
    "dataSources" : [ 
      "coll" 
    ], 
    "created" : "2025-01-15T09:40:57Z", 
    "hits" : 2, 
    "memoryUsage" : 3097 
  } 
]

      Clear the AQL query plan cache

      DELETE http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/query-plan-cache

      Clears all AQL execution plans stored in the query plan cache for the selected database.

      This requires write privileges for the selected database.

      Path Parameters

      • The name of the database.

        Example: _system

      Query Parameters
        HTTP Headers
          Responses

          • The query plan cache has been cleared for the selected database.

              Response Body application/json object

            • The HTTP response status code.

              Example: 200

            • A flag indicating that no error occurred.

              Example: false

          Clear the AQL query plan cache of the current database:

          curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/query-plan-cache'
          Show output
          HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 26
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200 
}

          On this page