Persisted Operations

Persisted operations allow you to register queries / mutations / subscriptions within a federated graph, enabling the clients to send just an identifier in their request instead of sending the whole operation body. These operations need to be registered ahead of time, using the wgc operations push command. This not only saves bandwidth but can also help reduce the attack surface by allowing only safe-listed operations.

Architecture

Workflow of pushing WGC operations to CDN and pulling them back to routers — Workflow of `wgc` operations push and pull via CDN

Persisted operations are usually registered within Cosmo during your release pipeline, which pushes them to the control plane. This allows you to use GraphQL queries without previously registering them in development while allowing only trusted operations in production. The control plane replicates these operations in the Cosmo CDN, where the routers can fetch them. All operations in the CDN are protected and only readable by routers running the federated graph to which the operations were registered.

Using persisted operations

Persisted operations require some tooling on the client side. Consult the documentation for your GraphQL client library to find out how to generate a query manifest or query map.

Supported manifest formats

wgc operations push automatically detects the format of your manifest file. The following formats are supported:

Apollo
Relay
GraphQL

The Apollo persisted query manifest format:

manifest.json

{
  "format": "apollo-persisted-query-manifest",
  "version": 1,
  "operations": [
    {
      "id": "dc67510fb4289672bea757e862d6b00e83db5d3c",
      "name": "GetEmployees",
      "type": "query",
      "body": "query GetEmployees { employees { id } }"
    }
  ]
}

Relay query maps are supported in two formats — as an array of [id, query] pairs or as a {id: query} object:

relay-query-map.json

{
  "dc67510fb4289672bea757e862d6b00e83db5d3c": "query GetEmployees { employees { id } }",
  "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2": "mutation UpdateEmployee($id: ID!) { updateEmployee(id: $id) { id } }"
}

wgc operations push mygraph -n default -c web -f relay-query-map.json

Plain .graphql or .gql files containing a single operation. The SHA-256 hash is computed automatically:

operations.graphql

query GetEmployees {
  employees {
    id
  }
}

wgc operations push mygraph -n default -c web -f operations.graphql

Pushing operations

Once your manifest is generated, push it using wgc:

wgc operations push mygraph -n default -c web -f my-operations-manifest.json

This registers the operations for your federated graph named mygraph in the default namespace and your client named web (indicated by the graphql-client-name HTTP header). You can push multiple files at once using the -f flag multiple times. When pushing the operations, you will see a short summary indicating how many were created and how many were already registered. Use --format json for machine-readable output:

wgc operations push mygraph -n default -c my-client -f manifest.json --format json

To see all available options for wgc operations push, see Push. Additionally, check the Using Persisted Operation with Federated GraphQL tutorial for a step-by-step guide.

Operation IDs

With APQ disabled, extensions.persistedQuery.sha256Hash accepts published IDs containing 1–250 printable ASCII characters (space through tilde), excluding forward slash and backslash. IDs are case-sensitive and are not trimmed or normalized. Control characters, DEL, and non-ASCII characters are rejected. For custom IDs, the router executes the published operation, even when a query body is also supplied. Unknown IDs return PersistedQueryNotFound. Filesystem storage uses <id>.json filenames. The 250-character limit leaves room for the .json suffix within a 255-byte filename component. Some accepted IDs are incompatible with Windows filesystem storage, including reserved device names and characters such as :, *, and ?. An ID that looks like a SHA256 hash (64 lowercase hexadecimal characters) must be the SHA256 hash of its operation body. For a different ID of that length, use uppercase letters or other characters. A query sent with a SHA256 ID must hash to that ID, as with APQ.

The router rejects a manifest that contains an operation breaking this rule, and the error lists the offending IDs. The router fails to start with such a manifest. If a manifest update breaks the rule, the router logs the error and keeps using the previous revision.Without a manifest, a request for an operation that breaks this rule fails with an error, and the router doesn’t cache the operation.

With APQ enabled, IDs must be SHA256 hashes and must match the query body when both are supplied.

{
  "extensions": {
    "persistedQuery": { "version": 1, "sha256Hash": "get_employees_v1" }
  }
}

Update the manifest revision whenever you add, change, or remove an operation. The changes take effect once the router loads the new revision. Requests already running finish with the manifest they started with. Without a manifest, use a new ID when you change an operation. Otherwise, the router may keep serving the old body from its cache. Safelisting and log_unknown use the query’s SHA256 hash to find published operations when a request doesn’t include an ID. To support these requests, publish the operation with its SHA256 hash as the ID. With log_unknown and without safelisting, a request with an unpublished SHA256 ID and its query is logged and executed. An unknown custom ID is always rejected. Both persisted_operation_sha256 and operation_sha256 record the ID from the request. If you send get_employees_v1, both fields contain get_employees_v1.

Deleting persisted operations in Studio

You can delete persisted operations directly in Cosmo Studio after they have been uploaded via wgc operations push.

Open your federated graph in Studio.
Go to Clients.
Open a client and click View Operations.
Expand the operation and click the delete button.
Confirm in the delete dialog.

Only organization users with organization-admin or organization-developer roles can delete operations. Operations are currently deleted one at a time from the UI.

Studio always asks for confirmation before deleting operations. If traffic is detected for the selected operation, the dialog warns that the operation is receiving traffic. If analytics data is unavailable, Studio cannot guarantee that existing clients won’t break. You can always check the metrics using the link in the dialog.

PQL Manifest

By default, the router fetches persisted operations individually from the Cosmo CDN on each request. When the PQL manifest is enabled, the router instead loads all persisted operations from a single manifest file at startup and serves them entirely from memory, eliminating per-request network overhead.

persisted_operations:
  manifest:
    enabled: true

The manifest is automatically updated in the Cosmo CDN whenever operations are added or deleted via wgc operations push or Studio. The router polls for updates using poll_interval and poll_jitter, picking up changes without requiring a restart. You can also load the manifest from a custom storage provider.

When the manifest is enabled, it is authoritative — the router does not fall back to fetching individual operations from the CDN. Unknown operation hashes are rejected immediately.

Cache warmup

When the PQL manifest is enabled, the router automatically warms up its caches by pre-processing all operations from the manifest at startup and after each manifest update. Each operation goes through parsing, normalization, validation, and query planning — the same steps that happen on a regular request. Once warmed, every operation is served entirely from cache with zero processing overhead on the first request. Cache warmup is enabled by default and can be configured or disabled:

persisted_operations:
  manifest:
    enabled: true
    warmup:
      enabled: true        # default: true
      workers: 4            # number of concurrent workers (default: 4)
      items_per_second: 50  # rate limit, 0 = unlimited (default: 50)
      timeout: 30s          # maximum time for warmup to complete (default: 30s)

Option	Default	Description
`enabled`	`true`	Set to `false` to disable cache warmup for manifest operations.
`workers`	`4`	Number of concurrent workers used to pre-process operations. Increase for large manifests.
`items_per_second`	`50`	Maximum items processed per second across all workers. Actual throughput can be lower if processing is slow. Set to `0` for unlimited.
`timeout`	`30s`	Maximum time allowed for the warmup to complete. If the timeout is exceeded, the router logs an error but continues serving requests normally.

Using a custom storage provider

You can load persisted operations from your own S3-compatible storage instead of the Cosmo CDN. First, define a storage provider, then reference it in your persisted operations configuration.

Disallowing non-persisted Operations

If you’re going all in on Security, you’d want to only allow Persisted Operations in your Production Environment. By default, non-persisted (dynamic) GraphQL Operations are allowed, which you can disable using the Security Configuration of the Router. We expose 4 different types of persisted operation blocking in the configuration:

Allow all operations (Default) — Both persisted and dynamic operations are permitted.
Log unknown operations — Any operation that has not been persisted will be logged, but not blocked.
Safelist — Operations that have been explicitly persisted will be allowed, based on matching the query body against persisted queries.
Block non-persisted operations — Fully enforced blocking of non-persisted operations, clients are required to send a pre-computed SHA-256 hash instead of a query body.

Migration path to enforcing persisted operations

To migrate from allowing all operations to a more restrictive option incrementally, we recommend following these steps:

Enable log_unknown

This will log when clients use operations that have not been persisted, helping you identify which operations to persist.

persisted_operations:
  log_unknown: true

Enable safelist

This will allow users to send operations with any query body, but only execute if they match a persisted operation.

persisted_operations:
  log_unknown: true
  safelist:
    enabled: true

Enable block_non_persisted_operations

This will block all non-persisted operations, requiring clients to send a pre-computed SHA-256 hash instead of a query body.

security:
  block_non_persisted_operations:
    enabled: true

Important Considerations

Whitespace sensitivity Differences in whitespace can alter an operations hash, which will cause it to be rejected as an unknown operation. We recommend using log_unknown_operations before enabling full blocking.
Compatibility with Automatic Persisted Queries (APQ) The safelist option cannot be used alongside APQ, as their functions are opposite.

Getting Started

Concepts

Cosmo Connect

Cosmo ConnectRPC

Router

Studio

Control Plane

GraphQL / Federation

Deployments and Hosting

Architecture

Using persisted operations

Supported manifest formats

Pushing operations

Operation IDs

Deleting persisted operations in Studio

PQL Manifest

Cache warmup

Using a custom storage provider

Disallowing non-persisted Operations

Migration path to enforcing persisted operations

Important Considerations

​Architecture

​Using persisted operations

​Supported manifest formats

​Pushing operations

​Operation IDs

​Deleting persisted operations in Studio

​PQL Manifest

​Cache warmup

​Using a custom storage provider

​Disallowing non-persisted Operations

​Migration path to enforcing persisted operations

​Important Considerations

Architecture

Using persisted operations

Supported manifest formats

Pushing operations

Operation IDs

Deleting persisted operations in Studio

PQL Manifest

Cache warmup

Using a custom storage provider

Disallowing non-persisted Operations

Migration path to enforcing persisted operations

Important Considerations