Available on: Cloud Standard, Cloud Professional, Cloud Enterprise, Self-hosted Enterprise
@@ -22,24 +16,17 @@ import HeadingIcon from '@site/src/components/HeadingIcon';
## 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.
+Hasura Cloud and Enterprise Edition provide support for caching query responses. This will drastically improve
+performance for queries which are executed frequently. This includes any GraphQL query including Actions and 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.
+Cached responses are stored for a period of time in a LRU (least-recently used) cache, and removed from the cache as per
+a user-specified TTL (time-to-live) which defaults to 60 seconds.
-A query's response can be cached only if the following conditions hold:
+## Getting started
-- The query does **not** make use of `Remote Schemas` that has `forward_client_headers` (see
- [RemoteSchemaDef](/api-reference/syntax-defs.mdx#remoteschemadef)) set to `true`.
-- The query **isn't** an `Action` that has `forward_client_headers` (see
- [ActionDefinition](/api-reference/syntax-defs.mdx#actiondefinition)) set to `true`.
-- The response JSON is **under** 100KB in size
-
-## 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:
+In order to cache a query response, or to return an existing response from the cache (if one exists), simply add the
+`@cached` directive to your query:
```graphql
query MyCachedQuery @cached {
@@ -53,6 +40,15 @@ query MyCachedQuery @cached {
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.
+A query's response can be cached only if the following conditions hold:
+
+- For queries using `Actions` or `Remote Schemas`, the query does **not** make use of `forward_client_headers` (see
+ [RemoteSchemaDef](/api-reference/syntax-defs.mdx#remoteschemadef) and
+ [ActionDefinition](/api-reference/syntax-defs.mdx#actiondefinition)).
+- The response JSON is **under** 100KB in size
+
+For self-hosted Enterprise Edition, refer to the [enable caching](/enterprise/caching.mdx) documentation.
+
## Controlling cache lifetime
The maximum lifetime of an entry in the cache can be controlled using the `ttl` argument to the `@cached` query
@@ -88,17 +84,24 @@ query MyCachedQuery @cached(refresh: true) {
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".
+warning header:
+
+```plaintext
+ Warning: 199 - cache-store-capacity-exceeded
+```
+
+:::info SLIDING WINDOW POLICIES
+
+A sliding window policy maintains a queue of a specified size, into which entities flow. When the queue is full and a
+new entity arrives, the oldest entity in the queue is removed from the window (FIFO).
+
+:::
## 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
+A session variable will only influence the cache key for a query if it is 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 the [API permissions](/api-reference/metadata-api/permission.mdx) documentation for more information.
## Response headers
@@ -108,7 +111,7 @@ When you enable caching for a query, the following headers should be returned in
- `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.
+These can be used by your application as you see fit, as well as by the cache-clearing endpoints.
## Clearing items from the cache
diff --git a/docs/docs/caching/overview.mdx b/docs/docs/caching/overview.mdx
new file mode 100644
index 00000000000..ea3c784b782
--- /dev/null
+++ b/docs/docs/caching/overview.mdx
@@ -0,0 +1,78 @@
+---
+description: Caching in Hasura Cloud and EE
+sidebar_label: Overview
+title: 'Hasura Caching'
+keywords:
+ - hasura
+ - docs
+ - cloud
+ - response
+ - caching
+sidebar_position: 1
+hide_table_of_contents: true
+sidebar_class_name: cloud-and-enterprise-icon
+---
+
+import HeadingIcon from '@site/src/components/HeadingIcon';
+import VersionedLink from '@site/src/components/VersionedLink';
+import Caching from '@site/static/icons/features/caching.svg';
+
+# Hasura Caching
+
+
+ Available on: Cloud Standard, Cloud Professional, Cloud Enterprise, Self-hosted Enterprise
+
+
+
+
+ Hasura Cloud and Enterprise Editions provide a caching layer that can be used to cache the response of a GraphQL
+ query. This can help reduce the number of requests to your datasources and improve the performance of your
+ application.
+
+
+ You have full control over the cache lifetime and can choose to force the cache to refresh when you need to. With
+ Hasura Caching, your application is highly-optimized and performant, reducing the load on your servers.
+
+
Quick Links
+
+
+ Enable caching on a query in less than 30 seconds.
+
+
+
+
+
+
+## Using Hasura Caching
+
+
+
+
+
Control the cache lifetime
+
+ Learn how to control the cache lifetime of a GraphQL query using the ttl argument.
+
+
+
+
+
+
Force the cache to refresh
+
+ Learn how to force the cache to refresh when you need to using the refresh argument.
+
+
+
+
+
+
Clear items from the cache
+
+ Learn how to clear items from the cache when you need to using the pro endpoint on your project.
+
+
+
+
diff --git a/docs/docs/caching/quickstart.mdx b/docs/docs/caching/quickstart.mdx
new file mode 100644
index 00000000000..a1a1c9e9c5d
--- /dev/null
+++ b/docs/docs/caching/quickstart.mdx
@@ -0,0 +1,100 @@
+---
+description: Quickstart with Caching
+title: Quickstart
+keywords:
+ - caching
+ - queries
+ - query
+sidebar_position: 2
+---
+
+import SampleAppBlock from '@site/src/components/SampleAppBlock';
+import Thumbnail from '../../src/components/Thumbnail';
+import Player from '@site/src/components/Player';
+
+# Quickstart Caching
+
+By utilizing Hasura Engine's caching layer you will significantly improve the performance of queries while at the same
+time reduce the load on your data sources. This quickstart guide will walk you through the process of setting up caching
+for your GraphQL API.
+
+
+
+## Basic Caching
+
+To try out caching in the Console, simply click the "Cache" button in the GraphiQL panel in the API tab to add the
+`@cached` directive to your query in the editor. Of course, you can also write this out manually. For this example we
+are getting the `id` and `name` of all `products` in the database with:
+
+```graphql
+query MyProducts @cached {
+ products {
+ id
+ name
+ }
+}
+```
+
+You'll be able to see improvements in the response time of the query when the `@cached` directive is added.
+
+
+
+## Setting the time-to-live (TTL)
+
+The `@cached` directive has an optional argument `ttl` which can be used to set the time-to-live (TTL) for the cache.
+
+The TTL is the time for which the cache is valid. After the TTL expires, the cache is invalidated and the next request
+will be a cache miss. The TTL is defined in an integer of seconds.
+
+```graphql
+query MyProducts @cached(ttl: 120) {
+ products {
+ id
+ name
+ }
+}
+```
+
+
+
+:::tip DEFAULT TTL
+
+By default the TTL is set to 60 seconds.
+
+:::
+
+## Forcing a cache refresh
+
+The `@cached` directive has an optional boolean argument of `refresh` which can be used to force a cache refresh. This
+is useful when you want to ensure that the cache is refreshed after a mutation. When this argument is used the query
+will take the longer, non-cached time to execute.
+
+```graphql
+query MyProducts @cached(refresh: true) {
+ products {
+ id
+ name
+ }
+}
+```
+
+
+
+
+## Recap
+
+What just happened? Well, you just supercharged your query performance using Hasura caching.
+
+You can now use the `@cached` directive to add caching to your queries, set the length of time they should live for
+with the TTL directive and force a cache refresh if you need to. 🎉
+
+[See the caching config section](/caching/caching-config.mdx) for a full description of the caching configuration
+options.
\ No newline at end of file
diff --git a/docs/docs/deployment/graphql-engine-flags/reference.mdx b/docs/docs/deployment/graphql-engine-flags/reference.mdx
index 59a5cf2beee..dfd5fc29fbd 100644
--- a/docs/docs/deployment/graphql-engine-flags/reference.mdx
+++ b/docs/docs/deployment/graphql-engine-flags/reference.mdx
@@ -208,8 +208,8 @@ for JSON encoding-decoding.
### Connections per Read-Replica
-The maximum number of Postgres connections per [read-replica](databases/database-config/read-replicas.mdx) that can be opened
-per stripe. When the maximum is reached we will block until a new connection becomes available, even if there is
+The maximum number of Postgres connections per [read-replica](databases/database-config/read-replicas.mdx) that can be
+opened per stripe. When the maximum is reached we will block until a new connection becomes available, even if there is
capacity in other stripes.
| | |
@@ -584,7 +584,7 @@ This variable sets the level for [Hasura's logs](/deployment/logging.mdx#logging
### Max Cache Size
-The [maximum cache size](/queries/response-caching.mdx), measured in MB, for queries.
+The [maximum cache size](/enterprise/caching.mdx), measured in MB, for queries.
| | |
| ------------------- | --------------------------------------------------------------------------------- |
diff --git a/docs/docs/enterprise/caching.mdx b/docs/docs/enterprise/caching.mdx
index 3f9d0c719b5..5e3014ceef0 100644
--- a/docs/docs/enterprise/caching.mdx
+++ b/docs/docs/enterprise/caching.mdx
@@ -22,8 +22,8 @@ import HeadingIcon from '@site/src/components/HeadingIcon';
## Introduction
-To start using query response caching with your Hasura EE GraphQL Engine you will need a Redis instance that is
-co-located with the Hasura GraphQL containers.
+To start using [Hasura Caching](/caching/overview.mdx) with your Hasura EE GraphQL Engine you will need a Redis instance
+that is co-located with the Hasura GraphQL containers.
Once you provision a Redis instance, provide the URL to the Hasura GraphQL Engine docker configuration using the
following environment variable:
diff --git a/docs/docs/enterprise/overview.mdx b/docs/docs/enterprise/overview.mdx
index 69f88a64e0f..c88068cce64 100644
--- a/docs/docs/enterprise/overview.mdx
+++ b/docs/docs/enterprise/overview.mdx
@@ -87,7 +87,7 @@ import Enterprise from '@site/static/icons/features/enterprise.svg';
Performance
-
+
Caching
Learn how to configure caching in Hasura Enterprise Edition to improve the performance of your GraphQL API.
diff --git a/docs/static/img/caching/caching_force-refresh_2-21-0.png b/docs/static/img/caching/caching_force-refresh_2-21-0.png
new file mode 100644
index 00000000000..b4ee5544b1a
Binary files /dev/null and b/docs/static/img/caching/caching_force-refresh_2-21-0.png differ
diff --git a/docs/static/img/caching/caching_quickstart-demo_2-21-0.mp4 b/docs/static/img/caching/caching_quickstart-demo_2-21-0.mp4
new file mode 100644
index 00000000000..6c5c1a22c94
Binary files /dev/null and b/docs/static/img/caching/caching_quickstart-demo_2-21-0.mp4 differ
diff --git a/docs/static/img/caching/caching_ttl_2-21-0.png b/docs/static/img/caching/caching_ttl_2-21-0.png
new file mode 100644
index 00000000000..83e06c9d736
Binary files /dev/null and b/docs/static/img/caching/caching_ttl_2-21-0.png differ