@@ -2235,8 +2235,8 @@ fragment someFragment on User {
22352235#### @defer Arguments
22362236
22372237- `if : Boolean ! = true ` - When `true `, fragment _should_ be deferred (see
2238- related note below). When ` false `, fragment must not be deferred . Defaults to
2239- `true ` when omitted .
2238+ [Client handling of `@defer`/`@stream`]( #sec-Client-handling-of-defer-stream-)).
2239+ When `false`, fragment must not be deferred. Defaults to `true` when omitted.
22402240- `label : String ` - An optional string literal (variables are disallowed ) used
22412241 by GraphQL clients to identify data in the _incremental stream_ and associate
22422242 it with the corresponding defer directive . If provided , the GraphQL service
@@ -2278,10 +2278,11 @@ query myQuery($shouldStream: Boolean! = true) {
22782278
22792279#### @stream Arguments
22802280
2281- - `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see related
2282- note below). When `false `, the field must behave as if the `@stream ` directive
2283- is not present —it must not be streamed and all of the list items must be
2284- included . Defaults to `true ` when omitted .
2281+ - `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see
2282+ [Client handling of `@defer`/`@stream`](#sec-Client-handling-of-defer-stream-)).
2283+ When `false`, the field must behave as if the `@stream` directive is not
2284+ present—it must not be streamed and all of the list items must be included.
2285+ Defaults to `true` when omitted.
22852286- `label : String ` - An optional string literal (variables are disallowed ) used
22862287 by GraphQL clients to identify data in the _incremental stream_ and associate
22872288 it with the corresponding stream directive . If provided , the GraphQL service
@@ -2293,22 +2294,27 @@ query myQuery($shouldStream: Boolean! = true) {
22932294 error will be raised if the value of this argument is less than `0`. When the
22942295 size of the list is greater than or equal to the value of `initialCount `, the
22952296 GraphQL service _must_ initially include at least as many list items as the
2296- value of `initialCount ` (see related note below).
2297+ value of `initialCount ` (see
2298+ [Client handling of `@defer`/`@stream`](#sec-Client-handling-of-defer-stream-)).
22972299
22982300Note : The
22992301[Defer And Stream Directive Labels Are Unique ](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
23002302validation rule ensures uniqueness of the values passed to `label ` on both the
23012303`@defer ` and `@stream ` directives . Variables are disallowed in the `label `
23022304because their values may not be known during validation .
23032305
2304- Note : The ability to defer and /or stream data can have a potentially significant
2306+ ### Client handling of `@defer`/`@stream`
2307+
2308+ The ability to defer and /or stream data can have a potentially significant
23052309impact on application performance . Developers generally need clear , predictable
23062310control over their application's performance. It is highly recommended that
23072311GraphQL services honor the `@defer` and `@stream` directives on each execution.
23082312However, the specification allows advanced use cases where the service can
2309- determine that it is more performant to not defer and/or stream. Therefore,
2310- GraphQL clients _must_ be able to process a _response_ that ignores individual
2311- `@defer` and/or `@stream` directives. This also applies to the `initialCount`
2312- argument on the `@stream` directive. Clients must be able to process a streamed
2313- field result that contains more initial list items than what was specified in
2314- the `initialCount` argument.
2313+ determine that it is more performant to not defer and/or stream. Services can
2314+ make this determination on case by case basis; e.g. in a single operation, one
2315+ or more `@defer` and/or `@stream` may be acted upon while others are ignored.
2316+ Therefore, GraphQL clients _must_ be able to process a _response_ that ignores
2317+ individual `@defer` and/or `@stream` directives. This also applies to the
2318+ `initialCount` argument on the `@stream` directive. Clients must be able to
2319+ process a streamed field result that contains more initial list items than what
2320+ was specified in the `initialCount` argument.
0 commit comments