Using GraphQL Persisted Queries for Faster CDN Caching

Your content API works fine in development but under real traffic you notice every page load hits ContentGrid's origin server. GraphQL queries sent as POST requests bypass CDN caches entirely. Persisted queries convert those requests to GET requests with a stable URL, so Vercel Edge Cache or Cloudflare can serve them without touching origin for repeat requests.

How Persisted Queries Work

Instead of sending the full GraphQL query string in every request body, you register the query once with ContentGrid and get back a hash. Future requests send only the hash as a GET parameter. ContentGrid looks up the hash, runs the query, and returns the result. Because the URL is stable and the method is GET, CDNs cache the response like any static asset.

• Query registration is done once, usually at build time or in a setup script.
• The hash is deterministic: the same query always produces the same hash.
• Variables (like an entry slug) are still passed as GET parameters.
• The CDN cache key is the hash plus the variables.

Registering Queries in ContentGrid

Use the ContentGrid Management API or CLI to register your queries before deployment:

• Write your queries in .graphql files in a queries/ directory.
• Run contentgrid queries push --dir queries/ to register all queries.
• The CLI prints the hash for each query. Store these in a query-hashes.json file.
• Add the push command to your CI pipeline before the build step.

Include query-hashes.json in your repository so front-end code can import hashes without hitting the API at runtime.

Calling Persisted Queries From Next.js

In your data-fetching code, replace standard GraphQL POST calls with GET calls using the hash:

• Import the hash from query-hashes.json.
• Build the URL: https://cdn.contentgrid.io/graphql?queryHash=HASH&variables=JSON.
• Use fetch with next: { revalidate: 60 } for ISR, or cache: 'force-cache' for fully static content.
• Vercel's CDN caches the GET response at the edge automatically.

Setting Cache TTLs

Different content types need different cache durations. A homepage hero should update within minutes of a content change. A blog archive can be stale for an hour. Set cache headers per query:

• ContentGrid lets you annotate queries with a default TTL when you register them.
• Override the TTL per request using the Cache-Control header your fetch returns.
• Use ContentGrid webhooks to trigger Vercel revalidation on content publish. This keeps TTLs long while ensuring fast updates on change.

Persisted queries plus webhook-driven revalidation give you the performance of a static site with the flexibility of live content. Most teams see a 60–80% reduction in origin requests after setting this up, which also reduces ContentGrid API usage costs at higher traffic volumes.