@@ -1978,8 +1978,9 @@ either or both of these directives are provided, they must conform to the
1978
1978
requirements defined in this specification .
1979
1979
1980
1980
Note : 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.
1983
1984
1984
1985
GraphQL implementations that support the type system definition language should
1985
1986
provide the `@specifiedBy` directive if representing custom scalar definitions.
@@ -2254,39 +2255,50 @@ directive @stream(
2254
2255
```
2255
2256
2256
2257
The `@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 .
2260
2264
2261
2265
The `@include ` and `@skip ` directives take precedence over `@stream `.
2262
2266
2263
2267
```graphql example
2264
2268
query myQuery ($shouldStream : Boolean ! = true ) {
2265
2269
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
2271
2273
}
2272
2274
}
2273
2275
}
2274
2276
```
2275
2277
2276
2278
#### @stream Arguments
2277
2279
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).
2281
2286
- `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 .
2284
2290
- `label : String ` - An optional string literal (variables are disallowed) used
2285
2291
by GraphQL clients to identify data from responses and associate it with the
2286
2292
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.
2290
2302
2291
2303
Note : The ability to defer and /or stream parts of a response can have a
2292
2304
potentially significant impact on application performance . Developers generally
@@ -2295,7 +2307,7 @@ highly recommended that GraphQL services honor the `@defer` and `@stream`
2295
2307
directives on each execution. However, the specification allows advanced use
2296
2308
cases where the service can determine that it is more performant to not defer
2297
2309
and/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