Skip to content

Commit d0fb75c

Browse files
committed
Lee editorial + manual merge #1161
1 parent 70de903 commit d0fb75c

File tree

3 files changed

+41
-43
lines changed

3 files changed

+41
-43
lines changed

spec/Section 3 -- Type System.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -757,7 +757,7 @@ type Person {
757757
}
758758
```
759759

760-
Valid operations must supply a selection of fields for any field that returns an
760+
Valid operations must supply a _selection set_ for any field which returns an
761761
object, so this operation is not valid:
762762

763763
```graphql counter-example

spec/Section 5 -- Validation.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -468,7 +468,7 @@ should be unambiguous. Therefore any two field selections which might both be
468468
encountered for the same object are only valid if they are equivalent.
469469

470470
During execution, the simultaneous execution of fields with the same response
471-
name is accomplished by {CollectSubfields()}.
471+
name is accomplished by {CollectSubfields()} before execution.
472472

473473
For simple hand-written GraphQL, this rule is obviously a clear developer error,
474474
however nested fragments can make this difficult to detect manually.

spec/Section 6 -- Execution.md

Lines changed: 39 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -348,21 +348,20 @@ Unsubscribe(responseStream):
348348

349349
## Executing Selection Sets
350350

351-
The process of executing a GraphQL operation is to recursively execute every
352-
selected field in the operation. To do this, first all initially selected fields
353-
from the operation's top most _root selection set_ are collected, then each
354-
executed. As each field completes, all its subfields are collected, then each
355-
executed. This process continues until there are no more subfields to collect
356-
and execute.
351+
Executing a GraphQL operation recursively collects and executes every selected
352+
field in the operation. First all initially selected fields from the operation's
353+
top most _root selection set_ are collected, then each executed. As each field
354+
completes, all its subfields are collected, then each executed. This process
355+
continues until there are no more subfields to collect and execute.
357356

358357
### Executing the Root Selection Set
359358

360359
:: A _root selection set_ is the top level _selection set_ provided by a GraphQL
361360
operation. A root selection set always selects from a _root operation type_.
362361

363362
To execute the root selection set, the initial value being evaluated and the
364-
root type must be known, as well as whether it must be executed serially, or may
365-
be executed in parallel (see
363+
root type must be known, as well as whether each field must be executed
364+
serially, or normally by executing all fields in parallel (see
366365
[Normal and Serial Execution](#sec-Normal-and-Serial-Execution).
367366

368367
Executing the root selection set works similarly for queries (parallel),
@@ -386,22 +385,23 @@ executionMode):
386385

387386
### Field Collection
388387

389-
Before execution, the _root selection set_ is converted to a _grouped field set_
390-
by calling {CollectFields()}. This ensures all fields with the same response
391-
name, including those in referenced fragments, are executed at the same time.
388+
Before execution, each _selection set_ is converted to a _grouped field set_ by
389+
calling {CollectFields()}. This ensures all fields with the same response name,
390+
including those in referenced fragments, are executed at the same time.
392391

393392
:: A _grouped field set_ is a map where each entry is a _response name_ and its
394393
associated _field set_. A _grouped field set_ may be produced from a selection
395394
set via {CollectFields()} or from the selection sets of a _field set_ via
396395
{CollectSubfields()}.
397396

398-
:: A _field set_ is a list of selected fields that share the same _response
399-
name_ (the field alias if defined, otherwise the field's name).
397+
:: A _field set_ is an ordered set of selected fields that share the same
398+
_response name_ (the field alias if defined, otherwise the field's name).
399+
Validation ensures each field in the set has the same name and arguments,
400+
however each may have different subfields (see:
401+
[Field Selection Merging](#sec-Field-Selection-Merging)).
400402

401403
Note: The order of field selections in a _field set_ is significant, hence the
402-
algorithms in this specification model it as a list. Any later duplicated field
403-
selections in a field set will not impact its interpretation, so using an
404-
ordered set would yield equivalent results.
404+
algorithms in this specification model it as an ordered set.
405405

406406
As an example, collecting the fields of this query's selection set would result
407407
in a grouped field set with two entries, `"a"` and `"b"`, with two instances of
@@ -430,7 +430,7 @@ response in a stable and predictable order.
430430
CollectFields(objectType, selectionSet, variableValues, visitedFragments):
431431

432432
- If {visitedFragments} is not provided, initialize it to the empty set.
433-
- Initialize {groupedFields} to an empty ordered map of lists.
433+
- Initialize {groupedFieldSet} to an empty ordered map of ordered sets.
434434
- For each {selection} in {selectionSet}:
435435
- If {selection} provides the directive `@skip`, let {skipDirective} be that
436436
directive.
@@ -445,9 +445,9 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
445445
- If {selection} is a {Field}:
446446
- Let {responseName} be the _response name_ of {selection} (the alias if
447447
defined, otherwise the field name).
448-
- Let {groupForResponseName} be the list in {groupedFields} for
449-
{responseName}; if no such list exists, create it as an empty list.
450-
- Append {selection} to the {groupForResponseName}.
448+
- Let {fieldsForResponseName} be the _field set_ in {groupedFieldSet} for
449+
{responseName}; if no such set exists, create it as an empty set.
450+
- Append {selection} to the {fieldsForResponseName}.
451451
- If {selection} is a {FragmentSpread}:
452452
- Let {fragmentSpreadName} be the name of {selection}.
453453
- If {fragmentSpreadName} is in {visitedFragments}, continue with the next
@@ -467,9 +467,9 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
467467
- For each {fragmentGroup} in {fragmentGroupedFieldSet}:
468468
- Let {responseName} be the response name shared by all fields in
469469
{fragmentGroup}.
470-
- Let {groupForResponseName} be the list in {groupedFields} for
471-
{responseName}; if no such list exists, create it as an empty list.
472-
- Append all items in {fragmentGroup} to {groupForResponseName}.
470+
- Let {fieldsForResponseName} be the _field set_ in {groupedFieldSet} for
471+
{responseName}; if no such set exists, create it as an empty set.
472+
- Append all items in {fragmentGroup} to {fieldsForResponseName}.
473473
- If {selection} is an {InlineFragment}:
474474
- Let {fragmentType} be the type condition on {selection}.
475475
- If {fragmentType} is not {null} and {DoesFragmentTypeApply(objectType,
@@ -482,32 +482,32 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
482482
- For each {fragmentGroup} in {fragmentGroupedFieldSet}:
483483
- Let {responseName} be the response name shared by all fields in
484484
{fragmentGroup}.
485-
- Let {groupForResponseName} be the list in {groupedFields} for
486-
{responseName}; if no such list exists, create it as an empty list.
487-
- Append all items in {fragmentGroup} to {groupForResponseName}.
488-
- Return {groupedFields}.
485+
- Let {fieldsForResponseName} be the _field set_ in {groupedFieldSet} for
486+
{responseName}; if no such set exists, create it as an empty set.
487+
- Append all items in {fragmentGroup} to {fieldsForResponseName}.
488+
- Return {groupedFieldSet}.
489489

490490
DoesFragmentTypeApply(objectType, fragmentType):
491491

492492
- If {fragmentType} is an Object Type:
493493
- If {objectType} and {fragmentType} are the same type, return {true},
494494
otherwise return {false}.
495495
- If {fragmentType} is an Interface Type:
496-
- If {objectType} is an implementation of {fragmentType}, return {true}
496+
- If {objectType} is an implementation of {fragmentType}, return {true},
497497
otherwise return {false}.
498498
- If {fragmentType} is a Union:
499-
- If {objectType} is a possible type of {fragmentType}, return {true}
499+
- If {objectType} is a possible type of {fragmentType}, return {true},
500500
otherwise return {false}.
501501

502502
Note: The steps in {CollectFields()} evaluating the `@skip` and `@include`
503503
directives may be applied in either order since they apply commutatively.
504504

505505
**Merging Selection Sets**
506506

507-
When a field is executed, during value completion the _selection set_ of each of
508-
the related field selections with the same response name are collected together
509-
to produce a single _grouped field set_ in order to continue execution of the
510-
sub-selection sets.
507+
In order to execute the sub-selections of a object typed field, all _selection
508+
sets_ of each field with the same response name of the parent _field set_ are
509+
merged together into a single _grouped field set_ representing the subfields to
510+
be executed next.
511511

512512
An example operation illustrating parallel fields with the same name with
513513
sub-selections.
@@ -536,16 +536,16 @@ phase with the same value.
536536

537537
CollectSubfields(objectType, fields, variableValues):
538538

539-
- Let {groupedFieldSet} be an empty map.
539+
- Let {groupedFieldSet} be an empty ordered map of ordered sets.
540540
- For each {field} in {fields}:
541541
- Let {fieldSelectionSet} be the selection set of {field}.
542542
- If {fieldSelectionSet} is null or empty, continue to the next field.
543543
- Let {fieldGroupedFieldSet} be the result of {CollectFields(objectType,
544544
fieldSelectionSet, variableValues)}.
545545
- For each {fieldGroupedFieldSet} as {responseName} and {subfields}:
546-
- Let {groupForResponseName} be the list in {groupedFieldSet} for
547-
{responseName}; if no such list exists, create it as an empty list.
548-
- Append all fields in {subfields} to {groupForResponseName}.
546+
- Let {fieldsForResponseName} be the _field set_ in {groupedFieldSet} for
547+
{responseName}; if no such set exists, create it as an empty set.
548+
- Add each fields in {subfields} to {fieldsForResponseName}.
549549
- Return {groupedFieldSet}.
550550

551551
Note: All the {fields} passed to {CollectSubfields()} share the same _response
@@ -558,10 +558,8 @@ the field selections from a _selection set_ or the associated selection sets of
558558
a _field set_ respectively, and split them into groups by their _response name_
559559
to produce a _grouped field set_.
560560

561-
To execute a _grouped field set_, the object value being evaluated and the
562-
object type need to be known, as well as whether it must be executed serially,
563-
or may be executed in parallel (see
564-
[Normal and Serial Execution](#sec-Normal-and-Serial-Execution).
561+
To execute a _grouped field set_, the object type being evaluated and the
562+
runtime value need to be known, as well as the runtime values for any variables.
565563

566564
Each entry in the grouped field set represents a _response name_ which produces
567565
an entry into a result map.

0 commit comments

Comments
 (0)