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.

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"] }]
      }
    ]
  }
})