title: Persistence & Uploads order: 1#

Persisted Queries and Uploads#

urql supports (Automatic) Persisted Queries, and File Uploads via GraphQL Multipart requests. For persisted queries to work, some setup work is needed, while File Upload support is built into @urql/core@4.

Automatic Persisted Queries#

Persisted Queries allow us to send requests to the GraphQL API that can easily be cached on the fly, both by the GraphQL API itself and potential CDN caching layers. This is based on the unofficial GraphQL Persisted Queries Spec.

With Automatic Persisted Queries the client hashes the GraphQL query and turns it into an SHA256 hash and sends this hash instead of the full query. If the server has seen this GraphQL query before it will recognise it by its hash and process the GraphQL API request as usual, otherwise it may respond using a PersistedQueryNotFound error. In that case the client is supposed to instead send the full GraphQL query, and the hash together, which will cause the query to be "registered" with the server.

Additionally, we could also decide to send these hashed queries as GET requests instead of POST requests. If we only send the persisted queries with hashes as GET requests then they become a lot easier for a CDN to cache, as by default most caches would not cache POST requests automatically.

In urql, we may use the @urql/exchange-persisted package's persistedExchange to enable support for Automatic Persisted Queries. This exchange works alongside other fetch or subscription exchanges by adding metadata for persisted queries to each GraphQL request by modifying the extensions object of operations.

Note: You can find a code example for @urql/exchange-persisted in an example in the urql repository.

Installation & Setup#

First install @urql/exchange-persisted alongside urql:

yarn add @urql/exchange-persisted
# or
npm install --save @urql/exchange-persisted

You'll then need to add the persistedExchange function, that this package exposes, to your exchanges, in front of exchanges that communicate with the API:

import { Client, fetchExchange, cacheExchange } from 'urql';
import { persistedExchange } from '@urql/exchange-persisted';

const client = new Client({
  url: 'http://localhost:1234/graphql',
  exchanges: [
    cacheExchange,
    persistedExchange({
      preferGetForPersistedQueries: true,
    }),
    fetchExchange,
  ],
});

As we can see, typically it's recommended to set preferGetForPersistedQueries to true to encourage persisted queries to use GET requests instead of POST so that CDNs can do their job. When set to true or 'within-url-limit', persisted queries will use GET requests if the resulting URL doesn't exceed the 2048 character limit.

The fetchExchange can see the modifications that the persistedExchange is making to operations, and understands to leave out the query from any request as needed. The same should be happening to the subscriptionExchange, if you're using it for queries.

Customizing Hashing#

The persistedExchange also accepts a generateHash option. This may be used to swap out the exchange's default method of generating SHA256 hashes. By default, the exchange will use the built-in Web Crypto API when it's available, and in Node.js it'll use the Node Crypto Module instead.

If you're using the graphql-persisted-document-loader for Webpack, for instance, then you will already have a loader generating SHA256 hashes for you at compile time. In that case we could swap out the generateHash function with a much simpler one that uses the generateHash function's second argument, a GraphQL DocumentNode object.

persistedExchange({
  generateHash: (_, document) => document.documentId,
});

If you're using React Native then you may not have access to the Web Crypto API, which means that you have to provide your own SHA256 function to the persistedExchange. Luckily, we can do so easily by using the first argument generateHash receives, a GraphQL query as a string.

import sha256 from 'hash.js/lib/hash/sha/256';

persistedExchange({
  async generateHash(query) {
    return sha256().update(query).digest('hex');
  },
});

Additionally, if the API only expects persisted queries and not arbitrary ones and all queries are pre-registered against the API then the persistedExchange may be put into a non-automatic persisted queries mode by giving it the enforcePersistedQueries: true option. This disables any retry logic and assumes that persisted queries will be handled like regular GraphQL requests.

File Uploads#

GraphQL server APIs commonly support the GraphQL Multipart Request spec to allow for File Uploads directly with a GraphQL API.

If a GraphQL API supports this, we can pass a File or a Blob directly into our variables and define the corresponding scalar for our variable, which is often called File or Upload.

In a browser, the File object may often be retrieved via a file input, for example.

Note: If you are using your own version of File and Blob ensure you are properly extending the so it can be properly identified as a file.

The @urql/core@4 package supports File Uploads natively, so we won't have to do any installation or setup work. When urql sees a File or a Blob anywhere in your variables, it switches to a multipart/form-data request, converts the request to a FormData object, according to the GraphQL Multipart Request specification, and sends it off to the API.

Note: Previously, this worked by installing the @urql/multipart-fetch-exchange package. however, this package has been deprecated and file uploads are now built into @urql/core@4.

You can find a code example for file uploads in an example in the urql repository.