Cache State

Cache entries transition through various states during their lifespan. The cache key is computed using the GraphQL query, variables, request authentication, and request domain.

The total time of a cache entry (TTL) is: maxAge + staleWhileRevalidate . After this TTL elapses, entries are evicted and deleted from cache.

The list below outlines the expected states visible in x-grafbase-cache response header:

x-grafbase-cache: MISS

No cache key found. Forwarding request to upstream for response retrieval and asynchronous cache put to minimize latency.

x-grafbase-cache: HIT

The cache contains a key that matches the incoming request. Clients will receive the response from the cache.

x-grafbase-cache: UPDATING

A matching key was found in the cache for the incoming request, but it has exceeded the maxAge limit. Clients will receive the cached response while we asynchronously refresh the entry.

x-grafbase-cache: STALE

The cache contains a key that matches the incoming request, but it has exceeded the maxAge limit and previous attempts to refresh it have failed.

x-grafbase-cache: BYPASS

The request was handled without any cache operation involved. This can occur in the following scenarios:

• Caching is not used
• The incoming request leverages Cache-Control directives to opt-out of caching
  • Cache-Control: no-cache skips getting from cache and fetches from source
  • Cache-Control: no-store skips caching the response from the remote source

You can also cache introspection queries by using the the following global configuration:

import { config } from '@grafbase/sdk'

export default config({
  cache: {
    rules: [
      {
        maxAge: 60
        staleWhileRevalidate: 60
        types: [{ name: "Query", fields: ["__schema"] }]
      }
    ]
  }
})