Layer 2 Cache for Persisted Documents

You can now configure a Layer 2 (L2) cache for persisted documents, reducing CDN calls and improving performance in serverless and multi-instance deployments.

The Problem

The in-memory LRU cache (L1) for persisted documents has limitations:

Cache lost on restart: Serverless cold starts, instance restarts, and scaling events clear the cache
No shared state: Each instance maintains its own cache, leading to redundant CDN calls
Scale constraints: Large supergraphs with many queries can hit LRU cache limits quickly
No CDN resilience: If the CDN is unavailable, there’s no fallback layer

Teams with high-scale requirements often needed to build custom persisted document implementations to use Redis or other distributed caches.

The Solution

Add a distributed cache (Redis, Memcached, etc.) as an L2 layer between the in-memory cache and CDN:

L1 (memory) → L2 (Redis) → CDN

import { createYoga } from "graphql-yoga";
import { createClient } from "redis";
import { useHive } from "@graphql-hive/yoga";

const redis = createClient({ url: "redis://localhost:6379" });
await redis.connect();

const yoga = createYoga({
  plugins: [
    useHive({
      experimental__persistedDocuments: {
        cdn: {
          endpoint: "https://cdn.graphql-hive.com/artifacts/v1/<target_id>",
          accessToken: "<cdn_access_token>",
        },
        layer2Cache: {
          cache: {
            get: (key) => redis.get(`hive:pd:${key}`),
            set: (key, value, opts) =>
              redis.set(
                `hive:pd:${key}`,
                value,
                opts?.ttl ? { EX: opts.ttl } : {},
              ),
          },
          ttlSeconds: 3600,
          notFoundTtlSeconds: 60,
        },
      },
    }),
  ],
});

Hive Gateway

For Hive Gateway, enable caching with just TTL options:

persistedDocuments: {
  type: 'hive',
  endpoint: 'https://cdn.graphql-hive.com/artifacts/v1/<target_id>',
  token: '<cdn_access_token>',
  cacheTtlSeconds: 3600,
  cacheNotFoundTtlSeconds: 60
}

Learn more about cache configuration

Or via CLI:

hive-gateway supergraph \
  --hive-persisted-documents-cache-ttl 3600 \
  --hive-persisted-documents-cache-not-found-ttl 60

Features

Option	Description
`ttlSeconds` / `cacheTtlSeconds`	TTL for found documents
`notFoundTtlSeconds` / `cacheNotFoundTtlSeconds`	TTL for not-found documents (negative caching). Default: 60s
`waitUntil`	Register cache writes in serverless environments

Apollo Server automatically uses server’s cache backend as the L2 cache when available.
Hive Gateway automatically uses the gateway cache when TTL options are provided.

Learn more about App Deployments