persisted_documents

The persisted_documents configuration controls how Hive Router reads persisted document IDs and maps them to GraphQL operation text.

This is the same concept some tools call persisted queries or trusted documents.

For usage patterns and migration guidance, see Persisted Documents guide.

Options

enabled

Enables persisted document extraction and resolution. Type is boolean and default is false.

require_id

If true, requests must contain a resolvable persisted document ID. If Router cannot extract an ID, it returns PERSISTED_DOCUMENT_ID_REQUIRED. Type is boolean and default is false.

log_missing_id

Logs requests that do not provide a resolvable persisted document ID. Type is boolean and default is false.

selectors

Ordered list of selectors. Router applies them top-to-bottom and uses the first successful match. Type is array. If omitted, router uses built-in defaults.

If omitted, defaults are:

1. json_path: documentId
2. json_path: extensions.persistedQuery.sha256Hash

When enabled: true, selectors cannot be an explicit empty list.

selectors[].type: json_path

selectors[].type: url_query_param

selectors[].type: url_path_param

Template rules:

• must start with /
• must contain exactly one :id
• supports * wildcard segments
• does not support **
• cannot contain query strings or fragments

storage

Selects where persisted document text is loaded from. Type is object and it is required when enabled: true.

storage.type: file

storage.type: hive

You can also configure Hive CDN connection using HIVE_CDN_ENDPOINT and HIVE_CDN_KEY environment variables.

HIVE_CDN_ENDPOINT="https://cdn.graphql-hive.com/..."
HIVE_CDN_KEY="your-cdn-key"

storage.hive.retry_policy

storage.hive.circuit_breaker

storage.hive.negative_cache

Supports three forms:

false disables negative cache, true enables it with defaults, and object form enables it with custom settings.

storage.type: storage

Loads the persisted documents manifest from a named backend declared in the top-level storages section (Amazon S3, Cloudflare R2, MinIO, LocalStack, or any other S3-compatible service).

Storage-loaded manifests use the same JSON format and parser as file-based manifests — the only difference is where the bytes come from.

When poll_interval is set, the router uses conditional requests (HTTP If-None-Match against the object's ETag) and only re-parses the manifest when storage reports the content has changed.

Endpoint compatibility note

If any extractor uses url_path_param, http.graphql_endpoint cannot be "/".

Use a non-root endpoint such as /graphql.

Examples

File storage with default selectors

persisted_documents:
  enabled: true
  require_id: true
  storage:
    type: file
    path: ./persisted-documents.json

Custom selectors order

persisted_documents:
  enabled: true
  require_id: true
  selectors:
    - type: url_path_param
      template: /docs/:id
    - type: url_query_param
      name: id
    - type: json_path
      path: doc_id
  storage:
    type: file
    path: ./persisted-documents.json

Hive storage with custom negative cache TTL

persisted_documents:
  enabled: true
  require_id: true
  storage:
    type: hive
    endpoint: ${HIVE_CDN_ENDPOINT}
    key: ${HIVE_CDN_KEY}
    negative_cache:
      ttl: 10s

Storage-backed manifest (S3 / S3-compatible)

Declare an S3-compatible storage backend once, then point the persisted documents loader at the manifest object inside it. The same backend can be reused by other features (such as supergraph.source: storage).

storages:
  artifacts:
    type: s3
    bucket: my-router-artifacts
    region: eu-west-1

persisted_documents:
  enabled: true
  require_id: true
  storage:
    type: storage
    storage_id: artifacts
    location: persisted/manifest.json
    poll_interval: 30s

Storage-backed manifest with credentials from environment variables

For deployments where the bucket name or credentials are not safe to commit, resolve them at startup with expressions and the env() function:

storages:
  artifacts:
    type: s3
    bucket:
      expression: env("S3_BUCKET")
    region:
      expression: env("AWS_REGION", "us-east-1")
    credentials:
      type: static
      access_key_id:
        expression: env("S3_ACCESS_KEY_ID")
      secret_access_key:
        expression: env("S3_SECRET_ACCESS_KEY")

persisted_documents:
  enabled: true
  require_id: true
  storage:
    type: storage
    storage_id: artifacts
    location: persisted/manifest.json
    poll_interval: 30s

See the storages reference for examples covering AWS S3, Cloudflare R2, MinIO, and LocalStack.