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.

Automatic Persisted Queries is a protocol for reducing the overhead of sending the same GraphQL documents to the server over and over again. Thus reducing client to server upstream traffic.

Since the upload speed can be the bottleneck from client to server, reducing the payload size can improve the performance especially for huge GraphQL documents.

The Automatic Persisted Queries plugin follows the APQ Specification of Apollo.

Installation

Quick Start

Using Automatic Persisted Queries requires installing a separate package.e.

npm i @graphql-yoga/plugin-apq

yarn add @graphql-yoga/plugin-apq

pnpm add @graphql-yoga/plugin-apq

bun add @graphql-yoga/plugin-apq

Automatic Persisted Queries Gateway setup

import { defineConfig } from "@graphql-hive/gateway";
import { useAPQ } from "@graphql-yoga/plugin-apq";

export const gatewayConfig = defineConfig({
  plugins: (pluginCtx) => [useAPQ()],
});

Start your Hive Gateway and send a request for priming the cache (register the operation).

Execute GraphQL Operation to prime the cache

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

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

Execute GraphQL Operation without query payload

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.

Custom Store

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

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

Automatic Persisted Operations with a custom store

import { useAPQ, type APQStore } 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();

useAPQ({ store });

For external stores the set and get properties on the store can also return a Promise.

In production, it’s recommended to capture the errors from any store that could stop functioning. Instead of raising an error, returning undefined or null will allow the server to continue to respond to requests if the store goes down.

Automatic Persisted Operations with a redis store

import Keyv from "keyv";

const store = new Keyv("redis://user:pass@localhost:6379");

useAPQ({
  store: {
    async get(key) {
      try {
        return await store.get(key);
      } catch (e) {
        console.error(`Error while fetching the operation: ${key}`, e);
      }
    },
    async set(key, value) {
      try {
        return await store.set(key, value);
      } catch (e) {
        console.error(`Error while saving the operation: ${key}`, e);
      }
    },
  },
});

Configure Error responses

By default, responses for missing or mismatching query will include extensions property with HTTP status code.

For example:

{
  extensions: {
    http: {
      status: 404
    },
    code: 'PERSISTED_QUERY_NOT_FOUND'
  }
}

You can force the error responses to use 200 OK status code:

Automatic Persisted Operations with a custom store

useAPQ({
  responseConfig: {
    forceStatusCodeOk: true,
  },
});

APQ between subgraphs and the gateway

The examples above describe the usage of APQ between the gateway and the client, but you can also benefit from APQ between the gateway and the subgraphs. If you have configured APQ in your subgraphs, the gateway can handle it automatically with the following configuration;

Automatic Persisted Operations with a custom store

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  transportEntries: {
    MY_APQ_SUBGRAPH: {
      // The name of the subgraph
      options: {
        apq: true,
      },
    },
    // or you can use wildcard `*` to enable APQ for all subgraphs
    "*": {
      options: {
        apq: true,
      },
    },
  },
});

Using GET for hashed APQ requests

By default, APQ probes to subgraphs are sent via POST. You can opt in to sending the initial hash-only probe as a GET request using useGETForHashedQueries. Full-query fallbacks (when the subgraph does not recognize the hash) and mutations always continue to use POST.

APQ with GET for hashed queries

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  transportEntries: {
    "*": {
      options: {
        apq: true,
        useGETForHashedQueries: true,
      },
    },
  },
});

Some upstream servers require a content-type: application/json header even on GET requests. You can enable this with useContentTypeForGETRequests:

APQ with GET and content-type header

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  transportEntries: {
    "*": {
      options: {
        apq: true,
        useGETForHashedQueries: true,
        useContentTypeForGETRequests: true,
      },
    },
  },
});