Query response caching

Available on: Cloud, Enterprise Edition

Introduction

Hasura Cloud and Enterprise Edition provide support for caching query responses, in order to improve performance for queries which are executed frequently. This includes actions and queries against remote schemas.

Cached responses are stored in for a period of time in a LRU (least-recently used) cache, and removed from the cache as needed based on usage.

A query's response can be cached only if the following conditions hold:

• The query does not make use of remote schemas that has forward_client_headers (see RemoteSchemaDef) set to true.
• The query isn't an Action that has forward_client_headers (see ActionDefinition) set to true.
• The response JSON is under 100KB in size

Support

Query response caching is available for Hasura Cloud projects on the Free tier and above.

Enable caching

In order to enable caching for a query response, or to return an existing response from the cache (if one exists), simply add the @cached directive to your query:

query MyCachedQuery @cached {
  users {
    id
    name
  }
}

If the response was cached successfully, the HTTP response will include a Cache-Control header, whose value (max-age={SECONDS}) indicates the maximum number of seconds for the returned response to remain in the cache.

Controlling cache lifetime

The maximum lifetime of an entry in the cache can be controlled using the ttl argument to the @cached query directive. The value is an integer number of seconds:

query MyCachedQuery @cached(ttl: 120) {
  users {
    id
    name
  }
}

By default, a response will be cached with a maximum lifetime of 60 seconds. The maximum allowed value is 300 seconds (5 minutes).

Forcing the cache to refresh

The cache entry can be forced to refresh, regardless of the maximum lifetime using the refresh argument to @cached. The value is a boolean:

query MyCachedQuery @cached(refresh: true) {
  users {
    id
    name
  }
}

Rate Limiting

Cache writes are rate limited, with a rate depending on your plan. The rate limit is based on the total number of bytes written to the cache in a sliding window. If you exceed the rate limit, the HTTP response will indicate this with a warning header: "Warning: 199 - cache-store-capacity-exceeded".

Session variables

Queries using session variables are able to be cached.

Please note:

• A session variable will only influence the cache key for a query if it referenced by the execution plan. In practice this means that session variables are only factored into cache keys if they are referenced in the permissions for a query. See https://hasura.io/docs/latest/api-reference/schema-metadata-api/permission/

Response headers

When you enable caching for a query, the following headers should be returned in the HTTP response:

• X-Hasura-Query-Cache-Key - Key for cached query response, unique to this query
• X-Hasura-Query-Family-Cache-Key - Key for the family of queries (ignores variable values)
• Cache-Control - Value: max-age={SECONDS} - Seconds until cache expires for query

These can be used by your application as you see fit, as well as by the cache clearing endpoints.

Clearing items from the cache

A set of endpoints exist to clear items from the cache for the current project:

• POST /pro/cache/clear -- Clears all
• POST /pro/cache/clear?key={HASH} -- Clears key hash
• POST /pro/cache/clear?family={FAMILY} -- Clears items that match query family (ignoring variables)