@@ -2366,8 +2366,8 @@ fragment someFragment on User {
23662366#### @defer Arguments
23672367
23682368- `if : Boolean ! = true ` - When `true `, fragment _should_ be deferred (see
2369- related note below ). When ` false `, fragment must not be deferred . Defaults to
2370- `true ` when omitted .
2369+ [ Client handling of `@ defer `/`@ stream `]( #sec-Client-handling-of-defer-stream-)).
2370+ When ` false `, fragment must not be deferred . Defaults to `true ` when omitted .
23712371- `label : String ` - An optional string literal (variables are disallowed ) used
23722372 by GraphQL clients to identify data in the _incremental stream_ and associate
23732373 it with the corresponding defer directive . If provided , the GraphQL service
@@ -2409,10 +2409,11 @@ query myQuery($shouldStream: Boolean! = true) {
24092409
24102410#### @stream Arguments
24112411
2412- - `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see related
2413- note below ). When `false `, the field must behave as if the `@stream ` directive
2414- is not present —it must not be streamed and all of the list items must be
2415- included . Defaults to `true ` when omitted .
2412+ - `if : Boolean ! = true ` - When `true `, field _should_ be streamed (see
2413+ [Client handling of `@defer `/`@stream `](#sec-Client-handling-of-defer-stream-)).
2414+ When `false `, the field must behave as if the `@stream ` directive is not
2415+ present —it must not be streamed and all of the list items must be included .
2416+ Defaults to `true ` when omitted .
24162417- `label : String ` - An optional string literal (variables are disallowed ) used
24172418 by GraphQL clients to identify data in the _incremental stream_ and associate
24182419 it with the corresponding stream directive . If provided , the GraphQL service
@@ -2424,22 +2425,27 @@ query myQuery($shouldStream: Boolean! = true) {
24242425 error will be raised if the value of this argument is less than `0 `. When the
24252426 size of the list is greater than or equal to the value of `initialCount `, the
24262427 GraphQL service _must_ initially include at least as many list items as the
2427- value of `initialCount ` (see related note below ).
2428+ value of `initialCount ` (see
2429+ [Client handling of `@defer `/`@stream `](#sec-Client-handling-of-defer-stream-)).
24282430
24292431Note : The
24302432[Defer And Stream Directive Labels Are Unique ](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
24312433validation rule ensures uniqueness of the values passed to `label ` on both the
24322434`@defer ` and `@stream ` directives . Variables are disallowed in the `label `
24332435because their values may not be known during validation .
24342436
2435- Note : The ability to defer and /or stream data can have a potentially significant
2437+ ### Client handling of `@defer`/`@stream`
2438+
2439+ The ability to defer and /or stream data can have a potentially significant
24362440impact on application performance . Developers generally need clear , predictable
24372441control over their application 's performance . It is highly recommended that
24382442GraphQL services honor the `@defer ` and `@stream ` directives on each execution .
24392443However , the specification allows advanced use cases where the service can
2440- determine that it is more performant to not defer and /or stream . Therefore ,
2441- GraphQL clients _must_ be able to process a _response_ that ignores individual
2442- `@defer ` and /or `@stream ` directives . This also applies to the `initialCount `
2443- argument on the `@stream ` directive . Clients must be able to process a streamed
2444- field result that contains more initial list items than what was specified in
2445- the `initialCount ` argument .
2444+ determine that it is more performant to not defer and /or stream . Services can
2445+ make this determination on case by case basis ; e .g . in a single operation , one
2446+ or more `@defer ` and /or `@stream ` may be acted upon while others are ignored .
2447+ Therefore , GraphQL clients _must_ be able to process a _response_ that ignores
2448+ individual `@defer ` and /or `@stream ` directives . This also applies to the
2449+ `initialCount ` argument on the `@stream ` directive . Clients must be able to
2450+ process a streamed field result that contains more initial list items than what
2451+ was specified in the `initialCount ` argument .
0 commit comments