Skip to content

docs: Update @defer documentation #820

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

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

docs: Update @defer documentation #820

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f1745f5
Update copy
calvincestari Oct 23, 2025
9569948
Apply suggestion from AI Style Review
calvincestari Oct 23, 2025
be10729
Apply suggestion from AI Style Review
calvincestari Oct 23, 2025
76e98c4
Apply suggestion from @phryneas
calvincestari Oct 24, 2025
9e8fef0
Apply suggestion from AI Style Review
calvincestari Oct 24, 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: 6 additions & 2 deletions docs/source/fetching/defer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,13 @@
title: Using the @defer directive in Apollo iOS
---

> ⚠️ **The `@defer` directive is currently an [experimental feature](https://www.apollographql.com/docs/resources/release-stages/#experimental-features) in Apollo iOS and is available for use from version 1.14.0.** If you have feedback on the feature, please let us know via a new [GitHub issue](https://github.com/apollographql/apollo-ios/issues/new?assignees=&labels=bug%2Cneeds+investigation&projects=&template=bug_report.yaml) or search through any [existing `@defer`-related issues](https://github.com/apollographql/apollo-ios/issues?q=is%3Aissue+is%3Aopen+%22defer%22).
<Note>

The [`@defer` directive](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md) 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 incremental delivery format used by `@defer` isn't yet standardized. There have been multiple proposals and Apollo iOS only supports [the format implemented by Apollo Router](https://www.apollographql.com/docs/graphos/routing/operations/defer#specification-status), which is described in this [specification](https://specs.apollo.dev/incremental/v0.1/).

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

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/fetching/defer.mdx#L7 

Use code font for code symbols like directives. Link text should be descriptive and avoid vague terms like "this".

```suggestion
The incremental delivery format used by `@defer` isn't yet standardized. There have been multiple proposals and Apollo iOS only supports [the format implemented by Apollo Router](https://www.apollographql.com/docs/graphos/routing/operations/defer#specification-status), which is described in the [v0.1 incremental delivery specification](https://specs.apollo.dev/incremental/v0.1/).
```

</Note>

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 11 in docs/source/fetching/defer.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/fetching/defer.mdx#L11 

Use "when" instead of "whenever" for more direct language. "the others" can be shortened to "others" for conciseness.

```suggestion
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 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 basic profile information as soon as it's available instead of waiting for the `friends` field to resolve.

Expand Down
Loading