Skip to content

Commit

Permalink
add initial versions of explanations for the algorithms in the "Execu…
Browse files Browse the repository at this point in the history
…ting an Execution Plan" section
  • Loading branch information
yaacovCR committed Aug 26, 2024
1 parent 0058d2a commit 09e89dd
Showing 1 changed file with 34 additions and 4 deletions.
38 changes: 34 additions & 4 deletions spec/Section 6 -- Execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -496,9 +496,12 @@ BatchIncrementalResults(incrementalResults):

## Executing an Execution Plan

To execute a execution plan, the object value being evaluated and the object
type need to be known, as well as whether the non-deferred grouped field set
must be executed serially, or may be executed in parallel.
Executing an execution plan consists of two tasks that may be performed in
parallel. The first task is simply the execution of the non-deferred grouped
field set. The second task is to use the partitioned grouped field sets within
the execution plan to generate Execution Groups, i.e. Incremental Data Records,
where each Incremental Data Records represents the deferred execution of one of
the partitioned grouped field sets.

ExecuteExecutionPlan(newDeferUsages, executionPlan, objectType, objectValue,
variableValues, serial, path, deferUsageSet, deferMap):
Expand All @@ -520,6 +523,15 @@ variableValues, serial, path, deferUsageSet, deferMap):
{incrementalDataRecords}.
- Return {data} and {incrementalDataRecords}.

Because `@defer` directives may be nested within list types, a map is required
to associate a Defer Usage record as recorded within Field Details Records and
an actual Deferred Fragment so that any additional Execution Groups may be
associated with the correct Deferred Fragment. The {GetNewDeferMap()} algorithm
creates that map. Given a list of new Defer Usages, the actual path at which the
fields they defer are spread, and an initial map, it returns a new map
containing all entries in the provided defer map, as well as new entries for
each new Defer Usage.

GetNewDeferMap(newDeferUsages, path, deferMap):

- If {newDeferUsages} is empty, return {deferMap}:
Expand All @@ -533,6 +545,11 @@ GetNewDeferMap(newDeferUsages, path, deferMap):
- Set the entry for {deferUsage} in {newDeferMap} to {newDeferredFragment}.
- Return {newDeferMap}.

The {CollectExecutionGroups()} algorithm is responsible for creating the
Execution Groups, i.e. Incremental Data Records, for each partitioned grouped
field set. It uses the map created by {GetNewDeferMap()} algorithm to associate
each Execution Group with the correct Deferred Fragment.

CollectExecutionGroups(objectType, objectValue, variableValues,
newGroupedFieldSets, path, deferMap):

Expand All @@ -554,14 +571,18 @@ newGroupedFieldSets, path, deferMap):
Note: {incrementalDataRecord} can be safely initiated without blocking
higher-priority data once any of {deferredFragments} are released as pending.

The {ExecuteExecutionGroup()} algorithm is responsible for actually executing
the deferred grouped field set and collecting the result and any raised errors.

ExecuteExecutionGroup(groupedFieldSet, objectType, objectValue, variableValues,
path, deferUsageSet, deferMap):

- Let {data} and {incrementalDataRecords} be the result of running
{ExecuteGroupedFieldSet(groupedFieldSet, objectType, objectValue,
variableValues, path, deferUsageSet, deferMap)} _normally_ (allowing
parallelization).
- Let {errors} be the list of all _field error_ raised while completing {data}.
- Let {errors} be the list of all _field error_ raised while executing
{ExecuteGroupedFieldSet()}.
- Return an unordered map containing {data}, {errors}, and
{incrementalDataRecords}.

Expand Down Expand Up @@ -884,6 +905,15 @@ choose to memoize their implementations of {CollectFields}.

### Execution Plan Generation

A grouped field set may contain fields that have been deferred by the use of the
`@defer` directive on their enclosing fragments. Given a grouped field set,
{BuildExecutionPlan()} generates an execution plan by partitioning the grouped
field as specified by the operation's use of `@defer` and the requirements of
the incremental response format. An execution plan consists of a single new
grouped field containing the fields that do not require deferral, and a map of
new grouped field set containing where the keys represent the set of Defer
Usages containing those fields.

BuildExecutionPlan(originalGroupedFieldSet, parentDeferUsages):

- If {parentDeferUsages} is not provided, initialize it to the empty set.
Expand Down

0 comments on commit 09e89dd

Please sign in to comment.