DocumentationGatewayIncremental Delivery (Defer & Stream)

Defer and Stream

Stream and defer are directives that allow you to improve latency for clients by sending the most important data as soon as it’s ready.

As applications grow, the GraphQL operation documents can get bigger. The server will only send the response back once all the data requested in the query is ready. However, not all requested data is of equal importance, and the client may not need all of the data at once. To remedy this, GraphQL specification working group is working on introducing new @defer and @stream directives which allows applications to request a subset of data which is critical and get the rest of the data in subsequent responses from the server. This proposal is in Stage 2, meaning GraphQL libraries can start implementing this as experimental feature to provide feedback to the working group.

💡

Stream and Defer are experimental features and not yet stable. The implementation can and will change. Furthermore, there is no yet a stable specification for the incremental delivery protocol.

Enabling in the configuration

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  deferStream: true
})

Using Defer

The @defer directive allows you to post-pone the delivery of one or more (slow) fields grouped in an inlined or spread fragment.

GraphQL Operation using @defer
query SlowAndFastFieldWithDefer {
  ... on Query @defer {
    slowField
  }
  fastField
}

Using Stream

The @stream directive allows you to stream the individual items of a field of the list type as the items are available.

GraphQL Operation using @stream
query StreamAlphabet {
  alphabet @stream
}