Batch HTTP Link

Overview

The BatchHttpLink is a terminating link that batches an array of individual GraphQL operations into a single HTTP request that's sent to a single GraphQL endpoint.

import { BatchHttpLink } from "@apollo/client/link/batch-http";

const link = new BatchHttpLink({ 
  uri: "http://localhost:4000/graphql",
  batchMax: 5, // No more than 5 operations per batch
  batchInterval: 20 // Wait no more than 20ms after first batched operation
});

If you use BatchHttpLink instead of HttpLink as your terminating link, Apollo Client automatically batches executed GraphQL operations and transmits them to your server according to the batching options you provide.

Options

The BatchHttpLink constructor accepts a configuration object that supports the following options:

Name /
Type Description

Name / Type	Description
Batching options
`batchMax` `number`	The maximum number of operations to include in a single batch. The default value is `10`.
`batchInterval` `number`	The maximum number of milliseconds to wait before sending each batched request. If `batchMax` operations are batched before `batchInterval` is reached, the request is sent immediately. The default value is `10`.
`batchDebounce` `boolean`	If `true`, the `batchInterval` timer is reset whenever an operation is added to the batch. In other words, the next batched request is not sent until either: No operation is added for `batchInterval` milliseconds, or `batchMax` is reached. The default value is `false`.
`batchKey` `string`	A function that accepts an operation and returns a string key, which uniquely names the batch the operation belongs to. See the default function
HTTP options
`uri` `String` or `Function`	The URL of the GraphQL endpoint to send requests to. Can also be a function that accepts an `Operation` object and returns the string URL to use for that operation. The default value is `/graphql`.
`includeExtensions` `Boolean`	If true, includes the `extensions` field in operations sent to your GraphQL endpoint. The default value is `false`.
`fetch` `Function`	A function to use instead of calling the Fetch API directly when sending HTTP requests to your GraphQL endpoint. The function must conform to the signature of `fetch`. By default, the Fetch API is used unless it isn't available in your runtime environment. See Customizing `fetch`.
`headers` `Object`	An object representing headers to include in every HTTP request, such as `{Authentication: 'Bearer abc123'}`.
`credentials` `String`	The credentials policy to use for each `fetch` call. Can be `omit`, `include`, or `same-origin`.
`fetchOptions` `Object`	An object containing options to use for each call to `fetch`. If a particular option is not included in this object, the default value of that option is used. Note that if you set `fetchOptions.method` to `GET`, `BatchHttpLink` follows standard GraphQL HTTP GET encoding. See available options

Batching options

`batchMax`

number

The maximum number of operations to include in a single batch.

The default value is 10.

`batchInterval`

number

The maximum number of milliseconds to wait before sending each batched request. If batchMax operations are batched before batchInterval is reached, the request is sent immediately.

The default value is 10.

`batchDebounce`

boolean

If true, the batchInterval timer is reset whenever an operation is added to the batch. In other words, the next batched request is not sent until either:

No operation is added for batchInterval milliseconds, or
batchMax is reached.

The default value is false.

`batchKey`

string

A function that accepts an operation and returns a string key, which uniquely names the batch the operation belongs to.

See the default function

HTTP options

`uri`

String or Function

The URL of the GraphQL endpoint to send requests to. Can also be a function that accepts an Operation object and returns the string URL to use for that operation.

The default value is /graphql.

`includeExtensions`

Boolean

If true, includes the extensions field in operations sent to your GraphQL endpoint.

The default value is false.

`fetch`

Function

A function to use instead of calling the Fetch API directly when sending HTTP requests to your GraphQL endpoint. The function must conform to the signature of fetch.

By default, the Fetch API is used unless it isn't available in your runtime environment.

See Customizing fetch.

`headers`

Object

An object representing headers to include in every HTTP request, such as {Authentication: 'Bearer abc123'}.

`credentials`

String

The credentials policy to use for each fetch call. Can be omit, include, or same-origin.

`fetchOptions`

Object

An object containing options to use for each call to fetch. If a particular option is not included in this object, the default value of that option is used.

Note that if you set fetchOptions.method to GET, BatchHttpLink follows standard GraphQL HTTP GET encoding.

See available options

Context

The batch HTTP link currently uses the context in two different ways, per batch and per query. The context fields below are used per batch and taken from the first operation in the batch.

Option	Description
`headers`	An object representing values to be sent as headers on the request
`credentials`	A string representing the credentials policy you want for the fetch call
`uri`	A string of the endpoint you want to fetch from
`fetchOptions`	Any overrides of the fetch options argument to pass to the fetch call
`response`	This is the raw response from the fetch request after it is made

For each query, the http field is used to modify each individual query in the batch, such as persisted queries (see below).

Persisted queries

The batch HTTP link supports an advanced GraphQL feature called persisted queries. This allows you to not send the stringified query over the wire, but instead send some kind of identifier for the query. To support this you need to attach the id somewhere in the extensions field, and pass the following options to the context:

operation.setContext({
  http: {
    includeExtensions: true,
    includeQuery: false,
  }
})

The context http object currently supports two keys:

includeExtensions: Send the extensions object for this request.
includeQuery: Don't send the query field for this request.

One way to use persisted queries is with apollo-link-persisted-queries and Apollo Server.

Custom fetching