@@ -1978,8 +1978,9 @@ either or both of these directives are provided, they must conform to the
19781978requirements defined in this specification .
19791979
19801980Note : The [Directives Are Defined ](#sec-Directives-Are-Defined) validation rule
1981- ensures that GraphQL Operations containing the `@defer` or `@stream` directives
1982- cannot be executed by a GraphQL service that does not support them.
1981+ ensures that GraphQL operations can only include directives available on the
1982+ schema; thus operations including `@defer` or `@stream` directives can only be
1983+ executed by a GraphQL service that supports them.
19831984
19841985GraphQL implementations that support the type system definition language should
19851986provide the `@specifiedBy` directive if representing custom scalar definitions.
@@ -2254,39 +2255,50 @@ directive @stream(
22542255```
22552256
22562257The `@stream ` directive may be provided for a field whose type incorporates a
2257- `List ` type modifier ; the directive enables the backend to leverage technology
2258- such as asynchronous iterators to provide a partial list initially , and
2259- additional list items in subsequent responses .
2258+ `List ` type modifier . The directive enables returning a partial list initially ,
2259+ followed by additional items in subsequent responses . Should the field type
2260+ incorporate multiple `List ` type modifiers , only the outermost list is streamed .
2261+
2262+ Note : The mechanism through which items are streamed is implementation -defined
2263+ and may use technologies such as asynchronous iterators .
22602264
22612265The `@include ` and `@skip ` directives take precedence over `@stream `.
22622266
22632267```graphql example
22642268query myQuery ($shouldStream : Boolean ! = true ) {
22652269 user {
2266- friends (first : 10 ) {
2267- nodes
2268- @stream (label : " friendsStream" , initialCount : 5 , if : $shouldStream ) {
2269- name
2270- }
2270+ friends (first : 10 )
2271+ @stream (label : " friendsStream" , initialCount : 5 , if : $shouldStream ) {
2272+ name
22712273 }
22722274 }
22732275}
22742276```
22752277
22762278#### @stream Arguments
22772279
2278- - `initialCount : Int ! = 0` - The number of list items the service should return
2279- initially . If omitted , defaults to `0`. A field error will be raised if the
2280- value of this argument is less than `0`.
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).
22812286- `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see related
2282- note below). When `false `, the field must not be streamed and all list items
2283- must be initially included . Defaults to `true ` when omitted .
2287+ note below). When `false `, the field must behave as if the `@stream ` directive
2288+ is not present —it must not be streamed and all of the list items must be
2289+ included . Defaults to `true ` when omitted .
22842290- `label : String ` - An optional string literal (variables are disallowed) used
22852291 by GraphQL clients to identify data from responses and associate it with the
22862292 corresponding stream directive . If provided , the GraphQL service must include
2287- this label in the corresponding pending object within the result . The `label `
2288- argument must be unique across all `@defer ` and `@stream ` directives in the
2289- document .
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 .
2296+
2297+ Note : The
2298+ [Defer And Stream Directive Labels Are Unique ](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
2299+ validation rule ensures uniqueness of the values passed to `label` on both the
2300+ `@defer` and `@stream` directives. Variables are disallowed in the `label`
2301+ because their values may not be known during validation.
22902302
22912303Note : The ability to defer and /or stream parts of a response can have a
22922304potentially significant impact on application performance . Developers generally
@@ -2295,7 +2307,7 @@ highly recommended that GraphQL services honor the `@defer` and `@stream`
22952307directives on each execution. However, the specification allows advanced use
22962308cases where the service can determine that it is more performant to not defer
22972309and/or stream. Therefore, GraphQL clients _must_ be able to process a response
2298- that ignores the `@defer ` and /or `@stream ` directives . This also applies to the
2299- `initialCount ` argument on the `@stream ` directive . Clients _must_ be able to
2300- process a streamed response that contains a different number of initial list
2301- items than what was specified in the `initialCount ` argument .
2310+ that ignores individual `@defer` and/or `@stream` directives. This also applies
2311+ to 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.
0 commit comments