@@ -2089,8 +2089,9 @@ either or both of these directives are provided, they must conform to the
20892089requirements defined in this specification .
20902090
20912091Note : The [Directives Are Defined ](#sec-Directives-Are-Defined) validation rule
2092- ensures that GraphQL Operations containing the `@defer ` or `@stream ` directives
2093- cannot be executed by a GraphQL service that does not support them .
2092+ ensures that GraphQL operations can only include directives available on the
2093+ schema ; thus operations including `@defer ` or `@stream ` directives can only be
2094+ executed by a GraphQL service that supports them .
20942095
20952096GraphQL implementations that support the type system definition language should
20962097provide the `@specifiedBy ` directive if representing custom scalar definitions .
@@ -2385,39 +2386,50 @@ directive @stream(
23852386```
23862387
23872388The `@stream ` directive may be provided for a field whose type incorporates a
2388- `List ` type modifier ; the directive enables the backend to leverage technology
2389- such as asynchronous iterators to provide a partial list initially , and
2390- additional list items in subsequent responses .
2389+ `List ` type modifier . The directive enables returning a partial list initially ,
2390+ followed by additional items in subsequent responses . Should the field type
2391+ incorporate multiple `List ` type modifiers , only the outermost list is streamed .
2392+
2393+ Note : The mechanism through which items are streamed is implementation -defined
2394+ and may use technologies such as asynchronous iterators .
23912395
23922396The `@include ` and `@skip ` directives take precedence over `@stream `.
23932397
23942398```graphql example
23952399query myQuery ($shouldStream : Boolean ! = true ) {
23962400 user {
2397- friends (first : 10 ) {
2398- nodes
2399- @stream (label : " friendsStream" , initialCount : 5 , if : $shouldStream ) {
2400- name
2401- }
2401+ friends (first : 10 )
2402+ @stream (label : " friendsStream" , initialCount : 5 , if : $shouldStream ) {
2403+ name
24022404 }
24032405 }
24042406}
24052407```
24062408
24072409#### @stream Arguments
24082410
2409- - `initialCount : Int ! = 0 ` - The number of list items the service should return
2410- initially . If omitted , defaults to `0 `. A field error will be raised if the
2411- value of this argument is less than `0 `.
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 ).
24122417- `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see related
2413- note below ). When `false `, the field must not be streamed and all list items
2414- must be initially included . Defaults to `true ` when omitted .
2418+ note below ). When `false `, the field must behave as if the `@stream ` directive
2419+ is not present —it must not be streamed and all of the list items must be
2420+ included . Defaults to `true ` when omitted .
24152421- `label : String ` - An optional string literal (variables are disallowed ) used
24162422 by GraphQL clients to identify data from responses and associate it with the
24172423 corresponding stream directive . If provided , the GraphQL service must include
2418- this label in the corresponding pending object within the result . The `label `
2419- argument must be unique across all `@defer ` and `@stream ` directives in the
2420- document .
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 .
2427+
2428+ Note : The
2429+ [Defer And Stream Directive Labels Are Unique ](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
2430+ validation rule ensures uniqueness of the values passed to `label ` on both the
2431+ `@defer ` and `@stream ` directives . Variables are disallowed in the `label `
2432+ because their values may not be known during validation .
24212433
24222434Note : The ability to defer and /or stream parts of a response can have a
24232435potentially significant impact on application performance . Developers generally
@@ -2426,7 +2438,7 @@ highly recommended that GraphQL services honor the `@defer` and `@stream`
24262438directives on each execution . However , the specification allows advanced use
24272439cases where the service can determine that it is more performant to not defer
24282440and /or stream . Therefore , GraphQL clients _must_ be able to process a response
2429- that ignores the `@defer ` and /or `@stream ` directives . This also applies to the
2430- `initialCount ` argument on the `@stream ` directive . Clients _must_ be able to
2431- process a streamed response that contains a different number of initial list
2432- items than what was specified in the `initialCount ` argument .
2441+ that ignores individual `@defer ` and /or `@stream ` directives . This also applies
2442+ to 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 .
0 commit comments