mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 12:31:52 +03:00
da7c53b8dd
https://github.com/hasura/graphql-engine-mono/pull/2229 GitOrigin-RevId: 9e1bdf906cf88bed3ef16bb624d0a8d99d7571e7
127 lines
3.9 KiB
ReStructuredText
127 lines
3.9 KiB
ReStructuredText
.. meta::
|
|
:description: Query response caching in Hasura Cloud
|
|
:keywords: hasura, docs, cloud, response, caching
|
|
|
|
.. _response_caching:
|
|
|
|
Query response caching
|
|
======================
|
|
|
|
.. contents:: Table of contents
|
|
:backlinks: none
|
|
:depth: 1
|
|
:local:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Hasura Cloud provides support for caching query responses, in order to
|
|
improve performance for queries which are executed frequently.
|
|
|
|
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`` or ``remote joins``.
|
|
- The query **isn't** an ``Action`` that has ``forward_client_headers`` (see :ref:`ActionDefinition`) set to ``true``.
|
|
- The response JSON is **under** 100KB in size
|
|
|
|
.. admonition:: Support
|
|
|
|
Query response caching is available for Hasura Cloud projects on the ``Standard`` (pay-as-you-go) 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:
|
|
|
|
.. code-block:: graphql
|
|
|
|
query MyCachedQuery @cached {
|
|
users {
|
|
id
|
|
name
|
|
}
|
|
}
|
|
|
|
If the response was cached successfully, the HTTP response will include a
|
|
``X-Hasura-TTL`` header, whose value 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:
|
|
|
|
.. code-block:: graphql
|
|
|
|
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:
|
|
|
|
.. code-block:: graphql
|
|
|
|
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/graphql/core/api-reference/schema-metadata-api/permission.html
|
|
|
|
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)
|