@@ -2342,9 +2342,9 @@ directive @defer(
23422342
23432343The `@defer ` directive may be provided on a fragment spread or inline fragment
23442344to indicate that execution of the related selection set should be deferred . When
2345- a request includes the `@defer ` directive , the result may consist of multiple
2346- responses : the initial response containing all non -deferred data , while
2347- subsequent responses include deferred data .
2345+ a request includes the `@defer ` directive , it may return an _incremental stream_
2346+ consisting of an _initial response_ containing all non -deferred data , followed
2347+ by one or more _subsequent payloads_ including the deferred data .
23482348
23492349The `@include ` and `@skip ` directives take precedence over `@defer `.
23502350
@@ -2369,11 +2369,11 @@ fragment someFragment on User {
23692369 related note below ). When `false `, fragment must not be deferred . Defaults to
23702370 `true ` when omitted .
23712371- `label : String ` - An optional string literal (variables are disallowed ) used
2372- by GraphQL clients to identify data from responses and associate it with the
2373- corresponding defer directive . If provided , the GraphQL service must include
2374- this label in the corresponding pending object within the response . The
2375- `label ` argument must be unique across all `@defer ` and `@ stream ` directives
2376- in the document .
2372+ by GraphQL clients to identify data in the _incremental stream_ and associate
2373+ it with the corresponding defer directive . If provided , the GraphQL service
2374+ must include this label in the corresponding pending object within the
2375+ _incremental stream_ . The `label ` argument must be unique across all `@defer `
2376+ and `@ stream ` directives in the document .
23772377
23782378### @stream
23792379
@@ -2387,7 +2387,7 @@ directive @stream(
23872387
23882388The `@stream ` directive may be provided for a field whose type incorporates a
23892389`List ` type modifier . The directive enables returning a partial list initially ,
2390- followed by additional items in subsequent responses . Should the field type
2390+ followed by additional items in subsequent payloads . Should the field type
23912391incorporate multiple `List ` type modifiers , only the outermost list is streamed .
23922392
23932393Note : The mechanism through which items are streamed is implementation -defined
@@ -2408,37 +2408,37 @@ query myQuery($shouldStream: Boolean! = true) {
24082408
24092409#### @stream Arguments
24102410
2411- - `initialCount : Int ! = 0 ` - The number of list items to include initially . If
2412- omitted , defaults to `0 `. A field error will be raised if the value of this
2413- argument is less than ` 0 `. When the size of the list is greater than or equal
2414- to the value of `initialCount `, the GraphQL service _must_ initially include
2415- at least as many list items as the value of ` initialCount ` ( see related note
2416- below ).
2411+ - `initialCount : Int ! = 0 ` - The number of list items to include initially when
2412+ completing the parent selection set . If omitted , defaults to `0 `. A field
2413+ error will be raised if the value of this argument is less than ` 0 `. When the
2414+ size of the list is greater than or equal to the value of `initialCount `, the
2415+ GraphQL service _must_ initially include at least as many list items as the
2416+ value of ` initialCount ` ( see related note below ).
24172417- `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see related
24182418 note below ). When `false `, the field must behave as if the `@stream ` directive
24192419 is not present —it must not be streamed and all of the list items must be
24202420 included . Defaults to `true ` when omitted .
24212421- `label : String ` - An optional string literal (variables are disallowed ) used
2422- by GraphQL clients to identify data from responses and associate it with the
2423- corresponding stream directive . If provided , the GraphQL service must include
2424- this label in the corresponding pending object within the response . The
2425- `label ` argument must be unique across all `@defer ` and `@ stream ` directives
2426- in the document .
2422+ by GraphQL clients to identify data in the _incremental stream_ and associate
2423+ it with the corresponding stream directive . If provided , the GraphQL service
2424+ must include this label in the corresponding pending object within the
2425+ _incremental stream_ . The `label ` argument must be unique across all `@defer `
2426+ and `@ stream ` directives in the document .
24272427
24282428Note : The
24292429[Defer And Stream Directive Labels Are Unique ](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
24302430validation rule ensures uniqueness of the values passed to `label ` on both the
24312431`@defer ` and `@stream ` directives . Variables are disallowed in the `label `
24322432because their values may not be known during validation .
24332433
2434- Note : The ability to defer and /or stream parts of a response can have a
2435- potentially significant impact on application performance . Developers generally
2436- need clear , predictable control over their application 's performance . It is
2437- highly recommended that GraphQL services honor the `@defer ` and `@stream `
2438- directives on each execution . However , the specification allows advanced use
2439- cases where the service can determine that it is more performant to not defer
2440- and / or stream . Therefore , GraphQL clients _must_ be able to process a response
2434+ Note : The ability to defer and /or stream data can have a potentially significant
2435+ impact on application performance . Developers generally need clear , predictable
2436+ control over their application 's performance . It is highly recommended that
2437+ GraphQL services honor the `@defer ` and `@stream ` directives on each execution .
2438+ However , the specification allows advanced use cases where the service can
2439+ determine that it is more performant to not defer and / or stream . Therefore ,
2440+ GraphQL clients _must_ be able to process a _response_ or _incremental stream_
24412441that ignores individual `@defer ` and /or `@stream ` directives . This also applies
24422442to the `initialCount ` argument on the `@stream ` directive . Clients must be able
2443- to process a streamed response that contains more initial list items than what
2444- was specified in the `initialCount ` argument .
2443+ to process a streamed field result that contains more initial list items than
2444+ what was specified in the `initialCount ` argument .
0 commit comments