directive @sequence

Specifies a field in Query or Mutation is comprised of a sequence of executions of fields in Query and/or Mutation.

Each step is called in order and its non-null field value is used to set the arguments for the next step.

If a step returns a list type then following step is executed multiple times ("list explosion"), extracting the arguments from each non-null element in the list.

For example with a sequence of [authors, books, covers] if authors returns three values then books is called three times with the arguments set for each individual author. Then books may return 3, 6, 10 books respectively for each author resulting in a total of 19 calls to covers.

If a step's field return null then the following steps are not executed. If the step's field returned a list with null elements then the following steps are executed for non-null elements, but not for null elements.

If executing any step's field results in an error then the sequence is stopped and results in an error.

The result of the sequence is the combination of output from the last step. The sequence field's type must be compatible with the type of the last field.

  • T -> [T] - Sequence returns a list containing all values from the last step.

  • [T] -> [T] - Sequence returns a list containing the merge of lists from the last step

  • T -> T - Sequence returns a single value, with list explosion in the sequence a single arbitrary value from the last step is selected.

  • [T] -> T - Sequence returns a single arbitrary value is selected from the last step's values is selected.

T -> [T] means the last step's field has type T (any type) and the sequence field has type [T], list of T.

With "list explosion" there is no guaranteed ordering of the resulting list value.

In addition if the last step's type T is an object type or wrapper of an object type, then the sequence field's type can use an interface type the object implements, e.g. T -> [I] where type T implements I { ... }.

An exception to "list explosion" is if a step's field type is a list of leaf values (scalar or enum) and the following step's field has zero arguments or its argument is a list of the same type. In this case the following step is called once.

Arguments

steps: [StepZen_Step!]!

Sequence of root operation type fields to invoke for the sequence.

Locations

Type System: FIELD_DEFINITION