• v3 (beta)
• Features
• Automatic Persisted Queries

Automatic Persisted Queries

Automatic Persisted Queries is a protocol for reducing the overhead of sending the same GraphQL documents to the server over and over again. Since the upload speed can be the bottleneck from client to server, reducing the payload size can improve the performance.

GraphQL Yoga's Automatic Persisted Queries plugin follows the APQ Specification of Apollo

NOTE: Automatic Persisted Queries do not provide any security features, the benefit of using them is to reduce network overhead. If you want to avoid executing arbitrary GraphQL operations please use the Persisted Documents plugin.

Installation

yarn add @graphql-yoga/plugin-apq

Quick Start

import { createYoga } from 'graphql-yoga'
import { createServer } from 'node:http'
import { useAPQ } from '@graphql-yoga/plugin-apq'
 
const yoga = createYoga({
  plugins: [useAPQ()]
})
 
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Start your yoga server and send a request for priming the cache.

curl -X POST -H 'Content-Type: application/json' http://localhost:4000/graphql \
-d '{"query":"{__typename}","extensions":{"persistedQuery":{"version":1,"sha256Hash":"ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38"}}}'

Then afterwards we can send the same payload again, but this time omit the query field.

curl -X POST -H 'Content-Type: application/json' http://localhost:4000/graphql \
-d '{"extensions":{"persistedQuery":{"version":1,"sha256Hash":"ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38"}}}'

Especially for big GraphQL document strings, the subsequent payload can be much smaller.

Client Usage

GraphQL clients such Apollo Client and Urql support Automatic Persisted Queries out of the box. Check the corresponding documentation for more information.

• Apollo Client
• Urql

Custom Store

By default all the documents strings are stored in memory with an LRU cache that holds up to 1000 unique entries (tiny-lru).

A custom store implementation can be provided via the store option.

import { createYoga } from 'graphql-yoga'
import { createServer } from 'node:http'
import { useAPQ } from '@graphql-yoga/plugin-apq'
 
// Note: this store grows infinitely, so it is not a good idea to use it in production.
const store: APQStore = new Map()
 
const yoga = createYoga({
  plugins: [useAPQ({ store })]
})
 
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

The set and get properties on the store can also return a Promise.