---
description:
  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.
---

import { Callout } from '@theguild/components'

# 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](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md)
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](https://github.com/graphql/graphql-spec/pull/742) is in
[Stage 2](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md#stage-2-draft), meaning
GraphQL libraries can start implementing this as experimental feature to provide feedback to the
working group.

<Callout>
  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.
</Callout>

## Enabling in the configuration

```ts filename="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 filename="GraphQL Operation using @defer" {2}
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 filename="GraphQL Operation using @stream" {2}
query StreamAlphabet {
  alphabet @stream
}
```
