Skip to content

Commit 5292a49

Browse files
Keweiqurobrichard
authored andcommitted
Introduce @defer and @stream.
Update Section 3 -- Type System.md Update Section 3 -- Type System.md Update Section 3 -- Type System.md Update Section 6 -- Execution.md Update Section 6 -- Execution.md Update Section 6 -- Execution.md Update Section 6 -- Execution.md Update Section 6 -- Execution.md Update Section 6 -- Execution.md Update Section 6 -- Execution.md Update Section 6 -- Execution.md Update Section 6 -- Execution.md Amend changes
1 parent d3ea511 commit 5292a49

File tree

2 files changed

+206
-28
lines changed

2 files changed

+206
-28
lines changed

spec/Section 3 -- Type System.md

Lines changed: 49 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -697,8 +697,9 @@ And will yield the subset of each object type queried:
697697
When querying an Object, the resulting mapping of fields are conceptually
698698
ordered in the same order in which they were encountered during query execution,
699699
excluding fragments for which the type does not apply and fields or
700-
fragments that are skipped via `@skip` or `@include` directives. This ordering
701-
is correctly produced when using the {CollectFields()} algorithm.
700+
fragments that are skipped via `@skip` or `@include` directives or temporarily
701+
skipped via `@defer`. This ordering is correctly produced when using the
702+
{CollectFields()} algorithm.
702703

703704
Response serialization formats capable of representing ordered maps should
704705
maintain this ordering. Serialization formats which can only represent unordered
@@ -1755,7 +1756,7 @@ A GraphQL schema describes directives which are used to annotate various parts
17551756
of a GraphQL document as an indicator that they should be evaluated differently
17561757
by a validator, executor, or client tool such as a code generator.
17571758

1758-
GraphQL implementations should provide the `@skip` and `@include` directives.
1759+
GraphQL implementations should provide the `@skip`, `@include`, `@defer` and `@stream` directives.
17591760

17601761
GraphQL implementations that support the type system definition language must
17611762
provide the `@deprecated` directive if representing deprecated portions of
@@ -1923,3 +1924,48 @@ type ExampleType {
19231924
oldField: String @deprecated(reason: "Use `newField`.")
19241925
}
19251926
```
1927+
1928+
### @defer
1929+
```graphql
1930+
directive @defer(label: String!, if: Boolean) on FRAGMENT_SPREAD | INLINE_FRAGMENT
1931+
```
1932+
The `@defer` directive may be provided for fragment spreads and inline fragments to
1933+
inform the executor to delay the execution of the current fragment to indicate
1934+
deprioritization of the current fragment. A query with `@defer` directive will cause
1935+
the request to potentially return multiple responses, where non-deferred data is
1936+
delivered in the initial response and data deferred delivered in a subsequent response.
1937+
`@include` and `@skip` take presedence over `@defer`.
1938+
1939+
```graphql example
1940+
query myQuery($shouldDefer: Boolean) {
1941+
user {
1942+
name
1943+
...someFragment @defer(label: 'someLabel', if: $shouldDefer)
1944+
}
1945+
}
1946+
fragment someFragment on User {
1947+
id
1948+
profile_picture {
1949+
uri
1950+
}
1951+
}
1952+
```
1953+
1954+
### @stream
1955+
```graphql
1956+
directive @stream(label: String!, initial_count: Int!, if: Boolean) on FIELD
1957+
```
1958+
The `@stream` directive may be provided for a field of `List` type so that the
1959+
backend can leverage technology such asynchronous iterators to provide a partial
1960+
list in the initial response, and additional list items in subsequent responses.
1961+
`@include` and `@skip` take presedence over `@stream`.
1962+
```graphql example
1963+
query myQuery($shouldDefer: Boolean) {
1964+
user {
1965+
friends(first: 10) {
1966+
nodes @stream(label: "friendsStream", initial_count: 5)
1967+
}
1968+
}
1969+
}
1970+
1971+
```

0 commit comments

Comments
 (0)