Arango logo

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/_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

  • The name of the database.

    Example: _system

Query Parameters
    HTTP Headers
      Responses

      • The query results cache entries are returned successfully.

          Response Body application/json

        • A list of query results cache entries.

          Each entry describes a cached query result but doesn’t include the cached result data itself.

          • The bind parameters. This attribute is omitted if the --query.tracking-with-bindvars startup option is set to false.

          • The collections and Views involved in the query.

          • The hash value calculated from the query string, certain query options, and the bind variables.

          • How many times the result has been served from the cache so far.

          • The query string.

          • The number of documents/rows in the cached query result.

          • The total duration of the query in seconds.

          • The size of the cached query result and bind parameters (in bytes).

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

      • The request is malformed.

      • 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: 433
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.00010986699999193661, 
    "started" : "2026-09-24T16:35:40Z", 
    "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.00040549999999939246, 
    "started" : "2026-09-24T16:35:40Z", 
    "dataSources" : [ 
      "coll" 
    ] 
  } 
]

      Clear the AQL query results cache

      DELETE http://<EXTERNAL_ENDPOINT>:8529/_db/:database-name/_api/query-cache
      Clears all results stored in the AQL query results cache for the selected database.
      Path Parameters

      • 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

          • The results cache has been cleared.

              Response Body application/json object

            • The HTTP response status code.

              Example: 200

            • A flag indicating that no error occurred.

              Example: false

          • The request is malformed.

          • The user account you authenticate with lacks read access to the specified database.

          • 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/_db/:database-name/_api/query-cache/properties
          Returns the global AQL query results cache configuration.
          Path Parameters

          • 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

              • The result cache configuration is returned successfully.

                  Response Body application/json object
                  The result cache configuration.

                • Whether results of queries that involve system collections are stored in the query results cache.

                • The maximum individual result size of queries that are stored per database-specific cache (in bytes).

                • The maximum number of query results that are stored per database-specific cache.

                • The maximum cumulated size of query results that are stored per database-specific cache (in bytes).

                • Possible values: "off", "on", "demand"

                  The mode the AQL query results cache operates in.

              • The request is malformed.

              • 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/_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

              • 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
                  Responses

                  • The result cache configuration has been changed successfully.

                      Response Body application/json object
                      The result cache configuration.

                    • Whether results of queries that involve system collections are stored in the query results cache.

                    • The maximum individual result size of queries that are stored per database-specific cache (in bytes).

                    • The maximum number of query results that are stored per database-specific cache.

                    • The maximum cumulated size of query results that are stored per database-specific cache (in bytes).

                    • Possible values: "off", "on", "demand"

                      The mode the AQL query results cache operates in.

                  • The request is malformed.

                  • The user account you authenticate with lacks read access to the specified database.

                  • 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 
}

                  On this page