Mutation serial execution with defer & stream

[robrichard]

Context

The GraphQL spec states that the selection set of mutations must be executed serially. How should @defer and @stream interact with GraphQL operations that contain multiple GraphQL mutations?

Example

mutation {
    mutationA {
        ... @defer {
            resultA
        }
    }
    mutationB {
        resultB
    }
}

Without @defer, the GraphQL spec currently guarantees that resultA will be resolved before mutationB is executed.

The two options being considered are

Option 1. All asynchronous payloads from each mutation must be sent before the next mutation is executed. This means @defer and @stream directives are ignored on all but the last mutation in the operation, or are buffered until after the subsequent mutations are completed and the initial payload is sent
Option 2. The next mutation begins executing after all synchronous fields are executed. Deferred and streamed fields from early mutations could potentially be executed after later mutations are executed.

Consequences

• Option 1 more closely follows the current spec behavior.
• Option 2 gives users more control over how mutations are executed. For the first time, users could opt into executing later mutations earlier, if deferred fields are not dependent on prior mutations. Potentially makes defer and stream more useful at the expense of possibly being more surprising behavior.

Decisions

• Discussed privately with jafar and Keweiqu in early 2020 and decided to go with option 2.
• Discussed briefly in 2021-06-03 WG meeting and the group seemed more amenable to option 1.
• Discussed briefly in the 2021-12-02 WG meeting. @leebyron's opinion was that option 2 is the right option.
• Discussed again in the 2022-01-06 WG meeting. No objection to moving forward with option 2. Adding @defer/@stream in a mutation sends a signal that consumers are opting into the possibility that subsequent mutations may be executed before the deferred/streamed field from prior mutations are executed.

Status

Currently option 2 is implemented in graphql-js and spec. Additional explanatory text has been added to Execution - Normal and Serial Execution spec.

Related

• Prevent `@defer` & `@stream` on root mutation or subscription fields #19
• Should @defer & @stream be supported on mutations and subscriptions? #2

[robrichard]

Discussed in the 2021-12-02 WG meeting:

• @leebyron's opinion was that option 2 is the right option. Adding @defer in a mutation sends strong signal that consumers want the option 2 behaviour.
• There was larger concern around deferring the top level mutation fields, which is addressed by the validation rule that will be added in Prevent `@defer` & `@stream` on root mutation or subscription fields #19

[robrichard]

Discussed again in the 2022-01-06 WG meeting and decided to move forward with option 2.