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

This documentation is not final and potentially incomplete.

AQL query results cache HTTP API

Control the caching of AQL query results with the HTTP interface

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 http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/query-cache/entries

Returns metadata about the AQL query results currently stored in the query results cache of the selected database. The cached result data itself isn’t included.

Path Parameters

database-name string
The name of the database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
The query results cache entries are returned successfully.
- array of objects
  A list of query results cache entries.
  Each entry describes a cached query result but doesn’t include the cached result data itself.
  bindVars object, optional
  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 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 cached query result.
  runTime number
  The total duration of the query in seconds.
  size integer
  The size of the cached 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.
401 Unauthorized
The user account you authenticate with lacks read access to the specified database.

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: 431
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.0000510610000219458, 
    "started" : "2025-01-15T09:40:57Z", 
    "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.00014617900001212547, 
    "started" : "2025-01-15T09:40:57Z", 
    "dataSources" : [ 
      "coll" 
    ] 
  } 
]

Clear the AQL query results cache

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

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

Path Parameters

database-name string
The name of the database whose query results cache to clear.
The user account you authenticate with needs at least read access to this database as well as to the _system database (the latter is required from v3.12.11 onward).
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
The results cache has been cleared.
- code integer
  The HTTP response status code.
  Example: 200
- error boolean
  A flag indicating that no error occurred.
  Example: false
400 Bad Request
The request is malformed.
401 Unauthorized
The user account you authenticate with lacks read access to the specified database.
403 Forbidden
The user account you authenticated with lacks read access to the _system database (introduced in v3.12.11). Up to v3.12.10, this endpoint didn’t perform this permission check.

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 http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_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.
Example: _system

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 integer
  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.
401 Unauthorized
The user account you authenticate with lacks read access to the specified database.

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 http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_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 as well as to the _system database (the latter is required from v3.12.11 onward).
Example: _system

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 integer
  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.
401 Unauthorized
The user account you authenticate with lacks read access to the specified database.
403 Forbidden
The user account you authenticated with lacks read access to the _system database (introduced in v3.12.11). Up to v3.12.10, this endpoint didn’t perform this permission check.

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 
}