docs: move caching to top-level

Things done:

1. Moved Query Response Caching inside Queries to its own top-level position.
2. Change name of Query Response Caching to Caching (or Hasura Caching as appropriate)
3. Minor content changes
4. Connected Caching docs to Enable Caching docs for Enterprise

TODO:

1. Setup redirect from old page to new page if necessary

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/8433
Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com>
Co-authored-by: Sean Park-Ross <94021366+seanparkross@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
GitOrigin-RevId: bd58e180b49a934f721172a18ff2cf5798a45515

docs/docs/caching/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Caching ☁️🏢",
+  "position": 70
+}

docs/docs/caching/caching-config.mdx

@@ -1,20 +1,14 @@
 ---
-description: Query response caching in Hasura Cloud
-sidebar_label: Response Caching ☁️🏢
-title: 'Cloud: Query response caching'
+title: Caching Config
 keywords:
-  - hasura
-  - docs
-  - cloud
-  - response
   - caching
-sidebar_position: 6
-sidebar_class_name: cloud-and-enterprise-icon
+  - queries
+  - query
+  - config
+sidebar_position: 3
 ---
 
-import HeadingIcon from '@site/src/components/HeadingIcon';
-
-# Query Response Caching
+# Caching Config
 
 <div className="badge badge--primary heading-badge">
   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 <https://hasura.io/docs/latest/api-reference/schema-metadata-api/permission/>
+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
 

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';
+
+# <Caching /> Hasura Caching
+
+<div className="badge badge--primary heading-badge" style={{ marginBottom: `1rem` }}>
+  Available on: Cloud Standard, Cloud Professional, Cloud Enterprise, Self-hosted Enterprise
+</div>
+<div className="overview-header">
+  <div className="overview-text">
+    <p>
+      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.
+    </p>
+    <p>
+      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.
+    </p>
+    <h4>Quick Links</h4>
+    <ul>
+      <li>
+        <VersionedLink to="/caching/quickstart/">Enable caching on a query in less than 30 seconds.</VersionedLink>
+      </li>
+    </ul>
+  </div>
+  <iframe
+    src="https://www.youtube.com/embed/QLaXWQmMF-8"
+    frameborder="0"
+    allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
+    allowFullScreen
+  />
+</div>
+
+## Using Hasura Caching
+
+<div className="overview-gallery">
+  <VersionedLink to="/caching/caching-config/#controlling-cache-lifetime/">
+    <div className="card">
+      <h3>Control the cache lifetime</h3>
+      <p>
+        Learn how to control the cache lifetime of a GraphQL query using the <code>ttl</code> argument.
+      </p>
+    </div>
+  </VersionedLink>
+  <VersionedLink to="/caching/caching-config/#forcing-the-cache-to-refresh/">
+    <div className="card">
+      <h3>Force the cache to refresh</h3>
+      <p>
+        Learn how to force the cache to refresh when you need to using the <code>refresh</code> argument.
+      </p>
+    </div>
+  </VersionedLink>
+  <VersionedLink to="/caching/caching-config/#clearing-items-from-the-cache/">
+    <div className="card">
+      <h3>Clear items from the cache</h3>
+      <p>
+        Learn how to clear items from the cache when you need to using the <code>pro</code> endpoint on your project.
+      </p>
+    </div>
+  </VersionedLink>
+</div>

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.
+
+<SampleAppBlock />
+
+## 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.
+
+<Player src="/img/caching/caching_quickstart-demo_2-21-0.mp4" />
+
+## 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
+  }
+}
+```
+
+<Thumbnail
+  src="/img/caching/caching_ttl_2-21-0.png"
+  alt="Setting the time-to-live integer argument for
+the cached directive"
+/>
+
+:::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
+  }
+}
+```
+
+<Thumbnail
+  src="/img/caching/caching_force-refresh_2-21-0.png"
+  alt="Setting the refresh argument for the cached
+directive"
+/>
+
+
+## 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.

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.
 
 |                     |                                                                                   |
 | ------------------- | --------------------------------------------------------------------------------- |

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:

docs/docs/enterprise/overview.mdx

@@ -87,7 +87,7 @@ import Enterprise from '@site/static/icons/features/enterprise.svg';
     </div>
   </VersionedLink>
   <h2 style={{ gridColumn: `1 / -1`, marginTop: `1.2rem`, marginBottom: `.3rem`, justifySelf: `start`, fontSize: `1.8rem` }}>Performance</h2>
-  <VersionedLink to="/queries/response-caching/">
+  <VersionedLink to="/enterprise/caching/">
     <div className="card">
       <h3>Caching</h3>
       <p>Learn how to configure caching in Hasura Enterprise Edition to improve the performance of your GraphQL API.</p>