From b576d0f4837e52d8eeadb70a4cce6e0502e18e8e Mon Sep 17 00:00:00 2001 From: Tirumarai Selvan Date: Thu, 29 Jun 2023 10:43:42 +0530 Subject: [PATCH] Docs: change flow in caching docs Minor changes to make it easier to grok "How it works" in Caching PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9692 Co-authored-by: Sean Park-Ross <94021366+seanparkross@users.noreply.github.com> GitOrigin-RevId: 5e9808d81706cb6ba2d68248e7fd5d80d035f609 --- docs/docs/caching/how-it-works.mdx | 36 ++++++++++++++++-------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/docs/caching/how-it-works.mdx b/docs/docs/caching/how-it-works.mdx index f331760c3d5..361a7888db3 100644 --- a/docs/docs/caching/how-it-works.mdx +++ b/docs/docs/caching/how-it-works.mdx @@ -11,16 +11,10 @@ sidebar_position: 3 ## What is cached exactly? -Hasura Caching is a type of response caching that helps you cache results of a given query. Hasura will cache the -response of a given "unique" query, and only if the same query is made again (i.e., has the same cache key) will it hit -the cache. We explain how the cache key is computed in the [next section](#how-is-the-cache-key-computed). - -This means that there is no sharing of the cache if: - -- the session variables differ, even if the GraphQL query, variables, operation name everything is the same -- the GraphQL variables differ, even if the GraphQL query is the same -- the operation name is different, even if the GraphQL query is the same -- the GraphQL query differs only in one or a few fields +Hasura Caching is a type of response caching that helps you store results of a given query in order to serve it more +quickly to your users. Hasura will cache the response of a given query under a cache key, and when another request +comes in which computes to the same cache key then it will deliver the cached result, without needing to query the +underlying data source. We explain how the cache key is computed in the [next section](#how-is-the-cache-key-computed). ## How is the cache key computed? @@ -32,12 +26,21 @@ The cache key is a hash of: - the GraphQL query - the GraphQL operation name - the GraphQL variables of the query -- the [role and session variables](/auth/authorization/roles-variables.mdx) used in permissions of the query +- the [role and session variables](/auth/authorization/roles-variables.mdx) used in the permissions of the query (not + necessarily all of the session variables) - request headers in case of [Remote Schemas](/remote-schemas/overview.mdx) or [Actions](/actions/overview.mdx) when `forward_client_headers` is `true` If the computed cache key is found in the cache, then there is a cache hit. +This means that a cached result will not be delivered if: + +- the session variables needed in the permissions of the query differ, even if the GraphQL query, variables, operation + name and everything else is the same +- the GraphQL variables differ, even if the GraphQL query is the same +- the operation name is different, even if the GraphQL query is the same +- the GraphQL query differs in one or more fields + :::info TTL matters Note that the cache hit also depends on the TTL and not just cache key. See [below](#cache-invalidation) to know more @@ -159,12 +162,11 @@ query getNewlyJoinedUsers($minDate: timestamptz!, $maxDate: timestamptz!) @cache ### Role and session variables Hasura resolves [session variables](/auth/authorization/roles-variables.mdx) via the -[authentication](/auth/authentication/index.mdx) process. The role and session variables are used to compute the cache -key. - -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. +[authentication](/auth/authentication/index.mdx) process. The role and (a subset of) session variables are used to +compute the cache key. A session variable will be part of the the cache key only if it is needed by the permission +rules for the query. Sessions variables which are not required in the execution plan for a query are not included in +the cache key. Therefore, the same cached result can be returned for requests where the session variables only +differ where they are not required in the query execution plan. For example, if a JWT resolves to say `x-hasura-user-id` and `x-hasura-org-id` session variables, but the query only uses the `x-hasura-user-id` in the permissions, then only the role and `x-hasura-user-id` would be used to compute the