Skip to content

Contact sales

By filling out this form and clicking submit, you acknowledge our privacy policy.

Persisted Queries Link with GraphQL

This guide will demonstrate how to use *Automatic Persisted Queries* to handle clients sending payloads of query text much larger than the REST equivalent.

Sep 29, 2020 • 4 Minute Read


GraphQL provides an expressive language to specify exactly what resources and data you want to fetch. However, this can lead to a problem where clients send large payloads of query text hundreds of times larger than the REST equivalent.

This guide will demonstrate how to use Automatic Persisted Queries to solve this issue. A previous guide, How to Set Up GraphQL in a React App, covered how to set up a new React Project with GraphQL using Apollo Client. This guide builds on what you learned there. Here you will learn how to improve network performance by sending smaller GraphQL requests.

How Persisted Queries Works

Normally, when you make a GraphQL request over HTTP, you POST a large amount of text specifying all the resources and fields you want. If there are a lot of users and resources, this can lead to network performance issues. The Apollo Client and Server implements a feature called Automatic Persisted Queries. This feature works by hashing the query, i.e., applying a function over the large query text to produce a much smaller mathematically linked value—the hash. This smaller hash is then sent to the server instead of the large query text.

The first time Apollo Server receives the hash, it responds by informing the client to send whole query text. The client sends the full query text, allowing the server to associate the hash with the query text. On all future queries of the same kind, even from different users, the client sends the small hash, and the server looks up the hash and knows which is being requested without it being sent explicitly over the network. In this way, a lot of network traffic is reduced.

Note: Persisted Queries is not part of the GraphQL Specification. In fact, the specification is not prescriptive about what transport method is used to send the request and deliver the response. The specification only describes the query language and the execution engine. This means that all server implementations may not support Automatic Persisted Queries. The Apollo Server provides this feature out of the box without any configuration. However, if you are using a graphql-dotnet as your server, you will need to add a third-party package like GraphQL.PersistedQueries to add support for Automatic Persisted Queries.

Enabling Automatic Persisted Queries in a Client

If you are using Apollo Server and Apollo Client, the only thing you need to update is your client. To do this, add link, which customizes the flow of data from your graphQL queries and mutations to your backend.

Run the following command to install Persisted Queries link:

      yarn add apollo-link-persisted-queries

Then update your src/ApolloClient/client.js file to:

      import { createPersistedQueryLink } from "apollo-link-persisted-queries";
import { ApolloClient, ApolloLink, InMemoryCache } from "@apollo/client";
import { HttpLink } from "apollo-link-http";

const httpLink = new HttpLink({
  uri: "",

export const client = new ApolloClient({
  cache: new InMemoryCache(),
  link: ApolloLink.from([createPersistedQueryLink(), httpLink]),

You have updated the link chain, placing createPersistedQueryLink() before the httpLink. The persisted link cannot be the last in your list. No other changes should be required. Finally, start React and make a query. If the server has seen your query before, the request payload will look something like this:

    "persistedQuery": {


Interacting with remote data is a large component of modern web apps. Using Apollo and GraphQL, querying data from REST and GraphQL endpoints becomes much easier. You have learned how to make your queries more efficient. As a next step, you may want to explore other Apollo features such as mutations and subscription.