@@ -2211,9 +2211,9 @@ directive @defer(
22112211
22122212The `@defer ` directive may be provided on a fragment spread or inline fragment
22132213to indicate that execution of the related selection set should be deferred . When
2214- a request includes the `@defer ` directive , the result may consist of multiple
2215- responses : the initial response containing all non -deferred data , while
2216- subsequent responses include deferred data .
2214+ a request includes the `@defer ` directive , it may return an _incremental stream_
2215+ consisting of an _initial response_ containing all non -deferred data , followed
2216+ by one or more _subsequent payloads_ including the deferred data .
22172217
22182218The `@include ` and `@skip ` directives take precedence over `@defer `.
22192219
@@ -2238,11 +2238,11 @@ fragment someFragment on User {
22382238 related note below). When `false `, fragment must not be deferred . Defaults to
22392239 `true ` when omitted .
22402240- `label : String ` - An optional string literal (variables are disallowed) used
2241- by GraphQL clients to identify data from responses and associate it with the
2242- corresponding defer directive . If provided , the GraphQL service must include
2243- this label in the corresponding pending object within the response . The
2244- `label ` argument must be unique across all `@defer ` and ` @stream ` directives
2245- in the document .
2241+ by GraphQL clients to identify data in the _incremental stream_ and associate
2242+ it with the corresponding defer directive . If provided , the GraphQL service
2243+ must include this label in the corresponding pending object within the
2244+ _incremental stream_ . The `label ` argument must be unique across all `@defer `
2245+ and ` @stream ` directives in the document .
22462246
22472247### @stream
22482248
@@ -2256,7 +2256,7 @@ directive @stream(
22562256
22572257The `@stream ` directive may be provided for a field whose type incorporates a
22582258`List ` type modifier . The directive enables returning a partial list initially ,
2259- followed by additional items in subsequent responses . Should the field type
2259+ followed by additional items in subsequent payloads . Should the field type
22602260incorporate multiple `List ` type modifiers , only the outermost list is streamed .
22612261
22622262Note : The mechanism through which items are streamed is implementation -defined
@@ -2277,37 +2277,37 @@ query myQuery($shouldStream: Boolean! = true) {
22772277
22782278#### @stream Arguments
22792279
2280- - `initialCount : Int ! = 0` - The number of list items to include initially . If
2281- omitted , defaults to `0`. A field error will be raised if the value of this
2282- argument is less than `0`. When the size of the list is greater than or equal
2283- to the value of `initialCount `, the GraphQL service _must_ initially include
2284- at least as many list items as the value of ` initialCount ` (see related note
2285- below).
2280+ - `initialCount : Int ! = 0` - The number of list items to include initially when
2281+ completing the parent selection set . If omitted , defaults to `0`. A field
2282+ error will be raised if the value of this argument is less than `0`. When the
2283+ size of the list is greater than or equal to the value of `initialCount `, the
2284+ GraphQL service _must_ initially include at least as many list items as the
2285+ value of ` initialCount ` (see related note below).
22862286- `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see related
22872287 note below). When `false `, the field must behave as if the `@stream ` directive
22882288 is not present —it must not be streamed and all of the list items must be
22892289 included . Defaults to `true ` when omitted .
22902290- `label : String ` - An optional string literal (variables are disallowed) used
2291- by GraphQL clients to identify data from responses and associate it with the
2292- corresponding stream directive . If provided , the GraphQL service must include
2293- this label in the corresponding pending object within the response . The
2294- `label ` argument must be unique across all `@defer ` and ` @stream ` directives
2295- in the document .
2291+ by GraphQL clients to identify data in the _incremental stream_ and associate
2292+ it with the corresponding stream directive . If provided , the GraphQL service
2293+ must include this label in the corresponding pending object within the
2294+ _incremental stream_ . The `label ` argument must be unique across all `@defer `
2295+ and ` @stream ` directives in the document .
22962296
22972297Note : The
22982298[Defer And Stream Directive Labels Are Unique ](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
22992299validation rule ensures uniqueness of the values passed to `label` on both the
23002300`@defer` and `@stream` directives. Variables are disallowed in the `label`
23012301because their values may not be known during validation.
23022302
2303- Note : The ability to defer and /or stream parts of a response can have a
2304- potentially significant impact on application performance . Developers generally
2305- need clear , predictable control over their application's performance. It is
2306- highly recommended that GraphQL services honor the `@defer` and `@stream`
2307- directives on each execution. However, the specification allows advanced use
2308- cases where the service can determine that it is more performant to not defer
2309- and/or stream. Therefore, GraphQL clients _must_ be able to process a response
2303+ Note : The ability to defer and /or stream data can have a potentially significant
2304+ impact on application performance . Developers generally need clear , predictable
2305+ control over their application's performance. It is highly recommended that
2306+ GraphQL services honor the `@defer` and `@stream` directives on each execution.
2307+ However, the specification allows advanced use cases where the service can
2308+ determine that it is more performant to not defer and/or stream. Therefore,
2309+ GraphQL clients _must_ be able to process a _response_ or _incremental stream_
23102310that ignores individual `@defer` and/or `@stream` directives. This also applies
23112311to the `initialCount` argument on the `@stream` directive. Clients must be able
2312- to process a streamed response that contains more initial list items than what
2313- was specified in the `initialCount` argument.
2312+ to process a streamed field result that contains more initial list items than
2313+ what was specified in the `initialCount` argument.
0 commit comments