@@ -1953,8 +1953,9 @@ either or both of these directives are provided, they must conform to the
19531953requirements defined in this specification .
19541954
19551955Note : The [Directives Are Defined ](#sec-Directives-Are-Defined) validation rule
1956- ensures that GraphQL Operations containing the `@defer` or `@stream` directives
1957- cannot be executed by a GraphQL service that does not support them.
1956+ ensures that GraphQL operations can only include directives available on the
1957+ schema; thus operations including `@defer` or `@stream` directives can only be
1958+ executed by a GraphQL service that supports them.
19581959
19591960GraphQL implementations that support the type system definition language should
19601961provide the `@specifiedBy` directive if representing custom scalar definitions.
@@ -2228,39 +2229,50 @@ directive @stream(
22282229```
22292230
22302231The `@stream ` directive may be provided for a field whose type incorporates a
2231- `List ` type modifier ; the directive enables the backend to leverage technology
2232- such as asynchronous iterators to provide a partial list initially , and
2233- additional list items in subsequent responses .
2232+ `List ` type modifier . The directive enables returning a partial list initially ,
2233+ followed by additional items in subsequent responses . Should the field type
2234+ incorporate multiple `List ` type modifiers , only the outermost list is streamed .
2235+
2236+ Note : The mechanism through which items are streamed is implementation -defined
2237+ and may use technologies such as asynchronous iterators .
22342238
22352239The `@include ` and `@skip ` directives take precedence over `@stream `.
22362240
22372241```graphql example
22382242query myQuery ($shouldStream : Boolean ! = true ) {
22392243 user {
2240- friends (first : 10 ) {
2241- nodes
2242- @stream (label : " friendsStream" , initialCount : 5 , if : $shouldStream ) {
2243- name
2244- }
2244+ friends (first : 10 )
2245+ @stream (label : " friendsStream" , initialCount : 5 , if : $shouldStream ) {
2246+ name
22452247 }
22462248 }
22472249}
22482250```
22492251
22502252#### @stream Arguments
22512253
2252- - `initialCount : Int ! = 0` - The number of list items the service should return
2253- initially . If omitted , defaults to `0`. A field error will be raised if the
2254- value of this argument is less than `0`.
2254+ - `initialCount : Int ! = 0` - The number of list items to include initially . If
2255+ omitted , defaults to `0`. A field error will be raised if the value of this
2256+ argument is less than `0`. When the size of the list is greater than or equal
2257+ to the value of `initialCount `, the GraphQL service _must_ initially include
2258+ at least as many list items as the value of `initialCount ` (see related note
2259+ below).
22552260- `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see related
2256- note below). When `false `, the field must not be streamed and all list items
2257- must be initially included . Defaults to `true ` when omitted .
2261+ note below). When `false `, the field must behave as if the `@stream ` directive
2262+ is not present —it must not be streamed and all of the list items must be
2263+ included . Defaults to `true ` when omitted .
22582264- `label : String ` - An optional string literal (variables are disallowed) used
22592265 by GraphQL clients to identify data from responses and associate it with the
22602266 corresponding stream directive . If provided , the GraphQL service must include
2261- this label in the corresponding pending object within the result . The `label `
2262- argument must be unique across all `@defer ` and `@stream ` directives in the
2263- document .
2267+ this label in the corresponding pending object within the response . The
2268+ `label ` argument must be unique across all `@defer ` and `@stream ` directives
2269+ in the document .
2270+
2271+ Note : The
2272+ [Defer And Stream Directive Labels Are Unique ](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
2273+ validation rule ensures uniqueness of the values passed to `label` on both the
2274+ `@defer` and `@stream` directives. Variables are disallowed in the `label`
2275+ because their values may not be known during validation.
22642276
22652277Note : The ability to defer and /or stream parts of a response can have a
22662278potentially significant impact on application performance . Developers generally
@@ -2269,7 +2281,7 @@ highly recommended that GraphQL services honor the `@defer` and `@stream`
22692281directives on each execution. However, the specification allows advanced use
22702282cases where the service can determine that it is more performant to not defer
22712283and/or stream. Therefore, GraphQL clients _must_ be able to process a response
2272- that ignores the `@defer ` and /or `@stream ` directives . This also applies to the
2273- `initialCount ` argument on the `@stream ` directive . Clients _must_ be able to
2274- process a streamed response that contains a different number of initial list
2275- items than what was specified in the `initialCount ` argument .
2284+ that ignores individual `@defer` and/or `@stream` directives. This also applies
2285+ to the `initialCount` argument on the `@stream` directive. Clients must be able
2286+ to process a streamed response that contains more initial list items than what
2287+ was specified in the `initialCount` argument.
0 commit comments