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.

Enabling in the configuration

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.

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.

query StreamAlphabet {
  alphabet @stream
}