Skip to content

Commit 00a6556

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 05d4a3b commit 00a6556

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
@@ -1752,7 +1753,7 @@ A GraphQL schema describes directives which are used to annotate various parts
17521753
of a GraphQL document as an indicator that they should be evaluated differently
17531754
by a validator, executor, or client tool such as a code generator.
17541755

1755-
GraphQL implementations should provide the `@skip` and `@include` directives.
1756+
GraphQL implementations should provide the `@skip`, `@include`, `@defer` and `@stream` directives.
17561757

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

0 commit comments

Comments
 (0)