PersistedQueryLink
Secure your graph while minimizing request latency
PersistedQueryLink is a non-terminating link that enables the use of
persisted queries, a technique that reduces bandwidth by sending query hashes
instead of full query strings.
1 import { PersistedQueryLink } from "@apollo/client/link/persisted-queries";
2 import { sha256 } from "crypto-hash";
3
4 const link = new PersistedQueryLink({
5 sha256: (queryString) => sha256(queryString),
6 });Read the Persisted queries guide to learn how to use persisted queries with Apollo Client.
Constructor signature
1constructor(
2 options: PersistedQueryLink.Options
3): PersistedQueryLinkPersistedQueryLink options
The PersistedQueryLink class takes a configuration object:
sha256: a SHA-256 hashing function. Can be sync or async. Providing a SHA-256 hashing function is required, unless you're defining a fully custom hashing approach viagenerateHash.generateHash: an optional function that takes the query document and returns the hash. If provided this custom function will override the default hashing approach that uses the suppliedsha256function. If not provided, the persisted queries link will use a fallback hashing approach leveraging thesha256function.useGETForHashedQueries: set totrueto use the HTTPGETmethod when sending the hashed version of queries (but not for mutations).GETrequests are not compatible with@apollo/client/link/batch-http.If you want to use
GETfor non-mutation queries whether or not they are hashed, passuseGETForQueries: trueoption toHttpLinkinstead. If you want to useGETfor all requests, passfetchOptions: {method: 'GET'}toHttpLink.disable: a function which takes aPersistedQueryLink.DisableFunctionOptionsobject and returns a boolean to disable any future persisted queries for that session. This defaults to disabling onPersistedQueryNotSupportederror.retry: a function which takes aPersistedQueryLink.RetryFunctionOptionsobject and returns a boolean to retry the request with the full query text included. This defaults totrueonPersistedQueryNotSupportedorPersistedQueryNotFounderrors.
Types
Options passed to the disable function when a persisted query request
fails.
ErrorLikeThe error that occurred during the request.
PersistedQueryLink.ErrorMetaMetadata about the persisted query error.
ApolloLink.OperationThe GraphQL operation that failed.
FormattedExecutionResultThe GraphQL result, if available.
Metadata about persisted query errors extracted from the response.
booleanWhether the server responded with a "PersistedQueryNotFound" error.
When true, indicates the server doesn't recognize the query hash
and needs the full query text.
booleanWhether the server responded with a "PersistedQueryNotSupported" error.
When true, indicates the server doesn't support persisted queries
or has disabled them for this client.
A function that generates a hash for a GraphQL document.
Example
1 import { print } from "graphql";
2 import { sha256 } from "crypto-hash";
3
4 const link = new PersistedQueryLink({
5 generateHash: async (document) => {
6 const query = print(document);
7 return sha256(query);
8 },
9 });Signature
1GenerateHashFunction(
2 document: DocumentNode
3): string | PromiseLike<string>Parameters
Options for using custom hash generation with persisted queries.
Use this configuration when you need custom control over how query hashes are generated (e.g., using pre-computed hashes).
(options: PersistedQueryLink.DisableFunctionOptions) => booleanA function to disable persisted queries for the current session.
This function is called when an error occurs and determines whether to disable persisted queries for all future requests in this session.
PersistedQueryLink.GenerateHashFunctionA custom function for generating query hashes. This function receives the GraphQL document and should return a hash. Useful for custom hashing strategies or when using build-time generated hashes.
(options: PersistedQueryLink.RetryFunctionOptions) => booleanA function to determine whether to retry a request with the full query.
When a persisted query fails, this function determines whether to retry the request with the full query text included.
neverWhether to use HTTP GET for hashed queries (excluding mutations).
GET for non-mutation queries whether or not they
are hashed, pass useGETForQueries: true option to HttpLink
instead. If you want to use GET for all requests, pass fetchOptions: {method: 'GET'}
to HttpLink.Options passed to the retry function when a persisted query request
fails.
ErrorLikeThe error that occurred during the request.
PersistedQueryLink.ErrorMetaMetadata about the persisted query error.
ApolloLink.OperationThe GraphQL operation that failed.
FormattedExecutionResultThe GraphQL result, if available.
Options for using SHA-256 hashing with persisted queries.
Use this configuration when you want the link to handle query printing and hashing using a SHA-256 function.
(options: PersistedQueryLink.DisableFunctionOptions) => booleanA function to disable persisted queries for the current session.
This function is called when an error occurs and determines whether to disable persisted queries for all future requests in this session.
(options: PersistedQueryLink.RetryFunctionOptions) => booleanA function to determine whether to retry a request with the full query.
When a persisted query fails, this function determines whether to retry the request with the full query text included.
PersistedQueryLink.SHA256FunctionThe SHA-256 hash function to use for hashing queries. This function receives the printed query string and should return a SHA-256 hash. Can be synchronous or asynchronous.
Whether to use HTTP GET for hashed queries (excluding mutations).
GET for non-mutation queries whether or not they
are hashed, pass useGETForQueries: true option to HttpLink
instead. If you want to use GET for all requests, pass fetchOptions: {method: 'GET'}
to HttpLink.