diff --git a/docs/source/fetching/defer.mdx b/docs/source/fetching/defer.mdx index 9023c7bddbb..950d04d1987 100644 --- a/docs/source/fetching/defer.mdx +++ b/docs/source/fetching/defer.mdx @@ -3,13 +3,13 @@ title: 'Using the @defer directive in Apollo Kotlin' description: 'Fetch slower schema fields asynchronously' --- - + -**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](https://github.com/graphql/defer-stream-wg). Apollo Kotlin 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/). - + -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 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.