HTTP interface for the query results cache

The query results cache HTTP API lets you control the cache for AQL query results

See The AQL query results cache for a description of the feature and the configuration options.

The AQL query results cache is only available for single servers, i.e. servers that are not part of a cluster setup.

List the entries of the AQL query results cache

GET /_db/{database-name}/_api/query-cache/entries

Returns an array containing the AQL query results currently stored in the query results cache of the selected database.

Path Parameters

database-name* string
The name of the database.

Query Parameters

HTTP Headers

Responses

200 OK
The list of cached query results.
- array of objects
  The entries of the query results cache.
  bindVars object
  The bind parameters. This attribute is omitted if the --query.tracking-with-bindvars startup option is set to false.
  dataSources* array of strings
  The collections and Views involved in the query.
  hash* string
  The hash value calculated from the the query string, certain query options, and the bind variables.
  hits* integer
  How many times the result has been served from the cache so far.
  query* string
  The query string.
  results* integer
  The number of documents/rows in the query result.
  runTime* number
  The total duration of the query in seconds.
  size* integer
  The size of the query result and bind parameters (in bytes).
  started* string
  The date and time at which the query result has been added to the cache (in ISO 8601 format).
400 Bad Request
The request is malformed.

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

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/query-cache/entries'

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: 432
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" : "17341318864108046370", 
    "query" : "RETURN 42", 
    "bindVars" : { 
    }, 
    "size" : 15, 
    "results" : 1, 
    "hits" : 0, 
    "runTime" : 0.00008241399999064924, 
    "started" : "2025-06-24T17:00:02Z", 
    "dataSources" : [ ] 
  }, 
  { 
    "hash" : "3942495485286482732", 
    "query" : "FOR doc IN @@coll FILTER doc.attr == @val RETURN doc", 
    "bindVars" : { 
      "@coll" : "coll", 
      "val" : "foo" 
    }, 
    "size" : 75, 
    "results" : 0, 
    "hits" : 2, 
    "runTime" : 0.00021265099999823178, 
    "started" : "2025-06-24T17:00:02Z", 
    "dataSources" : [ 
      "coll" 
    ] 
  } 
]

Clear the AQL query results cache

DELETE /_db/{database-name}/_api/query-cache

Clears all results stored in the AQL query results cache for the current database.

Path Parameters

database-name* string
The name of the database.

Query Parameters

HTTP Headers

Responses

200 OK
The results cache has been cleared.
- code* integer
  The HTTP response status code.
- error* boolean
  A flag indicating that no error occurred.
400 Bad Request
The request is malformed.

Clear the AQL query results cache of the current database:

curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/query-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 
}

Get the AQL query results cache configuration

GET /_db/{database-name}/_api/query-cache/properties

Returns the global AQL query results cache configuration.

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.

Query Parameters

HTTP Headers

Responses

200 OK
The result cache configuration is returned successfully.
- includeSystem boolean
  Whether results of queries that involve system collections are stored in the query results cache.
- maxEntrySize
  The maximum individual result size of queries that are stored per database-specific cache (in bytes).
- maxResults integer
  The maximum number of query results that are stored per database-specific cache.
- maxResultsSize integer
  The maximum cumulated size of query results that are stored per database-specific cache (in bytes).
- mode string
  Possible values: "off", "on", "demand"
  The mode the AQL query results cache operates in.
400 Bad Request
The request is malformed.

Retrieve the global configuration of the AQL query results cache:

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/query-cache/properties'

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: 107
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

{ 
  "mode" : "demand", 
  "maxResults" : 128, 
  "maxResultsSize" : 268435456, 
  "maxEntrySize" : 16777216, 
  "includeSystem" : false 
}

Set the AQL query results cache configuration

PUT /_db/{database-name}/_api/query-cache/properties

Adjusts the global properties for the AQL query results cache.

Changing the properties may invalidate all results currently in the cache.

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.

Query Parameters

HTTP Headers

Request Body application/json object

includeSystem boolean
Whether to store results of queries that involve system collections in the cache.
Default: Controlled by the --query.cache-include-system-collections startup option
maxEntrySize integer
The maximum individual size of query results that are stored per database-specific cache (in bytes).
Default: Controlled by the --query.cache-entry-max-size startup option.
maxResults integer
The maximum number of query results that are stored per database-specific cache.
Default: Controlled by the --query.cache-entries startup option.
maxResultsSize integer
The maximum cumulated size of query results that are stored per database-specific cache (in bytes).
Default: Controlled by the --query.cache-entries-max-size startup option.
mode string
Possible values: "off", "on", "demand"
The mode the AQL query cache shall operate in.
Default: Controlled by the --query.cache-mode startup option.

Responses

200 OK
The result cache configuration has been changed successfully.
- includeSystem boolean
  Whether results of queries that involve system collections are stored in the query results cache.
- maxEntrySize
  The maximum individual result size of queries that are stored per database-specific cache (in bytes).
- maxResults integer
  The maximum number of query results that are stored per database-specific cache.
- maxResultsSize integer
  The maximum cumulated size of query results that are stored per database-specific cache (in bytes).
- mode string
  Possible values: "off", "on", "demand"
  The mode the AQL query results cache operates in.
400 Bad Request
The request is malformed.

Change some properties of the global configuration of the AQL query results cache:

curl -X PUT --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/query-cache/properties' <<'EOF'
{
  "mode": "demand",
  "maxResults": 32
}
EOF

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: 106
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

{ 
  "mode" : "demand", 
  "maxResults" : 32, 
  "maxResultsSize" : 268435456, 
  "maxEntrySize" : 16777216, 
  "includeSystem" : false 
}