Headless Server Developer Manual / Version 2506.0
Table Of ContentsPersisted Queries allow clients to issue GraphQL queries without transferring the whole (potentially long) query string at each request. Instead, clients pass a short ID or hash of the query string. The actual query string is stored on the server side, either by loading it at server startup, or by a client upload as part of an Automatic Persisted Query.
Note
Note that the hash of the Persisted Query may change if the query string changes, even if the change is only a whitespace or comment change. Therefore, clients must use the new correct hash after a change. Also, when changing an existing Persisted Query in CoreMedia Blueprint, you may need to adjust associated CoreMedia Blueprint tests that rely on the Persisted Query hash. Always consider to use Project Extensions or Plugins instead of changing CoreMedia Blueprint code. See Section 4.1.5, “Project Extensions” in Blueprint Developer Manual and Section 4.1.6, “Application Plugins” in Blueprint Developer Manual for details.
See last section in Section 9.2, “Query Allow Listing” on how to retrieve updated Persisted Query hashes.
Persisted Queries have the following advantages:
Reduced bandwidth
The payload of the request is generally reduced.
Better CDN cacheability
Clients can use HTTP GET requests even for large queries.
Reduced latency
Using HTTP GET makes it easy to avoid CORS preflight requests issued by a browser client (HTTP OPTIONS requests).
Query allow list
Client queries may be restricted to the queries already known to the server, blocking potentially malicious queries.
Several GraphQL client frameworks support persisted queries, including Apollo Client and Relay. The CoreMedia Headless Server allows you to leverage this advanced GraphQL feature.
Section 9.1, “Loading Persisted Queries at Server Startup” describes how to set up the Headless Server to load persisted queries at startup time. This allows for the query allow list if the set of queries issued by clients is known in advance.
Section 9.2, “Query Allow Listing” describes the query allow list. That is, only queries loaded in the server during startup can be executed.
Section 9.3, “Apollo Automatic Persisted Queries” describes a more flexible approach called Automatic Persisted Queries. Automatic Persisted Queries allow clients to upload persisted queries to the server at runtime.
