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

Merged
merged 6 commits into from
Oct 27, 2025
Merged

docs: Update @defer documentation #820

Changes from all commits
Commits
Show all changes
6 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
fce9c2b
Apply suggestion from @calvincestari
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: 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](https://github.com/graphql/defer-stream-wg). Apollo iOS 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 

Avoid using vague phrases like 'this' for link text. The link text should describe the content of the link's destination.

```suggestion
The incremental delivery format used by `@defer` [isn't yet standardized](https://github.com/graphql/defer-stream-wg). Apollo iOS supports [the format implemented by Apollo Router](https://www.apollographql.com/docs/graphos/routing/operations/defer#specification-status), which is described in the [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 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