Skip to content

docs: Update @defer documentation #6751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 27, 2025
Merged

docs: Update @defer documentation #6751

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9ffc684
Update copy
calvincestari Oct 23, 2025
22182d3
Apply changes from AI Style Review
calvincestari Oct 23, 2025
a319ab3
Apply suggestion from AI Style Review
calvincestari Oct 24, 2025
63c9908
Apply suggestion from @phryneas
calvincestari Oct 24, 2025
4fcd0e6
Add suggestion from Martin
calvincestari Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/source/fetching/defer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
description: 'Fetch slower schema fields asynchronously'
---

<ExperimentalFeature>
<Note>

**The `@defer` directive is currently [experimental](https://www.apollographql.com/docs/resources/product-launch-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on it, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
The incremental delivery format used by `@defer` isn't yet standardized. There have been multiple proposals and Apollo Kotlin only supports [the format implemented by Apollo Router](https://www.apollographql.com/docs/graphos/routing/operations/defer#specification-status).

Check warning on line 8 in docs/source/fetching/defer.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/fetching/defer.mdx#L8 

Mentioning 'multiple proposals' is unopinionated and not actionable for the user. State the supported path directly to maintain an authoritative voice.

```suggestion
The incremental delivery format used by <code>@defer</code> isn't yet standardized. Apollo Kotlin only supports [the format implemented by Apollo Router](https://www.apollographql.com/docs/graphos/routing/operations/defer#specification-status).
```

</ExperimentalFeature>
</Note>

Apollo Kotlin provides experimental support of [the `@defer` directive](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md), which enables your queries to receive data for specific fields asynchronously. This is helpful whenever some fields in a query take much longer to resolve than the others.
The [`@defer` directive](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md) enables your queries to receive data for specific fields incrementally, instead of receiving all field data at the same time. This is helpful whenever some fields in a query take much longer to resolve than the others.

Check notice on line 12 in docs/source/fetching/defer.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/fetching/defer.mdx#L12 

Use 'when' instead of 'whenever' and 'than others' instead of 'than the others' for simpler, more concise language.

```suggestion
The [<code>@defer</code> directive](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md) enables your queries to receive data for specific fields incrementally, instead of receiving all field data at the same time. This is helpful when some fields in a query take much longer to resolve than others.
```

For example, let's say we're building a social media application that can quickly fetch a user's basic profile information, but retrieving that user's friends takes longer. If we include _all_ of those fields in a single query, we want to be able to display the profile information as soon as it's available, instead of waiting for the friend fields to resolve.

Expand Down