Serial Execution and Write Ordering

The One Ordering Guarantee the Spec Hands You

Query root fields may execute in whatever order the server finds efficient, because reads are independent of each other. Mutations get the opposite rule: the spec requires the top-level fields of a mutation operation to execute serially, in the order the client wrote them — each field's work completes before the next begins.

mutation {
  a: bumpCounter      # 1. runs to completion
  b: bumpCounter      # 2. starts only after 1 finishes
  c: sendWelcomeEmail # 3. starts only after 2 finishes
}

document order:  a ────────► b ────────► c ────────►
wall clock:     [== a ==]  [== b ==]  [== c ==]
                 never a, b, c overlapping

Why the asymmetry? Writes are observable. If three root fields each read a balance, add 10, and write it back, parallel execution produces lost updates. Serial root execution gives a sequence where later fields observe earlier effects — provided each resolver awaits its own write before returning.

Two properties of the guarantee matter:

• Aliases expose the order. The client (or you, in testing) can read the intended sequence straight from the document, since root field order in the document is execution order.
• It applies to mutation operations only. The same fields declared on Query get no such promise; readability and side effects are the entire distinction between the two roots.

Contrast that with everything inside a root field: subfield selection follows ordinary query execution and may fan out concurrently, which is covered in async resolver patterns.

Where the Guarantee Stops

Serial execution has three edges, and each has caused a production incident.

Only root fields are covered. Subfields under one mutation root field are not required to run one at a time. If checkout { order { id } payment { receipt } } reaches two downstream services, those two reads may execute concurrently even though checkout itself ran in sequence with its siblings.

Only within one document. Two clients posting separate operations interleave freely:

client A:  [ createOrder A1 ][ charge A2 ]
client B:          [ createOrder B1 ][ charge B2 ]

Nothing orders A1 against B1. Cross-request ordering is the job of database transactions, row locks, or a queue — never field order.

Only as strong as the promises the resolvers return. The executor waits for what a resolver hands back. A root-field resolver that starts a write and returns without awaiting releases the next root field before the first write lands:

Mutation: {
  // WRONG: returns before the insert commits
  createOrder: (_p, args, ctx) => { ctx.orders.insert(args); return {}; },
  chargeCard: (_p, args, ctx) => ctx.payments.charge(args),  // may start too early
}

Every root-field resolver must await its side effects, or the guarantee becomes a lie the schema appears to tell.

Dependent writes should not rely on field order at all. Even with correct awaiting, a client may split the work across documents, or a proxy may replay one of them. Pass values forward through the payload instead of re-reading shared state:

mutation {
  transfer(from: "acct-a", to: "acct-b", amount: 4000) {
    fromBalance
    toBalance
    transferId
  }
}

The next step consumes what the transfer returned. That works regardless of which server handles which document, and it survives retries — the pattern in mutation return payloads is what makes it expressible.

Idempotency: The Order Problem You Actually Have

Serial execution protects writes inside one document. The failure that pages you comes from outside: a client times out after the server committed, retries, and a second order exists. Ordering worked perfectly; intent was not preserved.

The standard fix is a client-generated idempotency key with a uniqueness constraint behind it:

async createOrder(_p, args, ctx) {
  const seen = await ctx.dataSources.orders.byIdempotencyKey(args.key);
  if (seen) return seen.toPayload(args.key);   // replay: same answer, no second write

  try {
    return await ctx.dataSources.orders.transaction(async (tx) => {
      const order = await tx.insertOrder(args);   // UNIQUE(idempotency_key) closes the race
      await tx.reserveStock(order.id);
      return order.toPayload(args.key);
    });
  } catch (err) {
    if (err.code === 'unique_violation') {         // two attempts raced each other
      return (await ctx.dataSources.orders.byIdempotencyKey(args.key)).toPayload(args.key);
    }
    throw err;
  }
}

Timeline under retries:

attempt 1:  key=k7 → no record → insert + reserve → 200 { order }
attempt 2:  key=k7 → record found → return stored order (no insert, no charge)
attempt 3:  key=k7 → races attempt 2 → unique violation → re-read → return stored order

Design notes:

• Generate the key per logical action, not per HTTP attempt — a retry must reuse it, or nothing dedupes.
• Persist the key with enough state to rebuild the response, so replays answer identically.
• Rely on the unique constraint rather than a read-then-insert sequence; the latter has a race window exactly when traffic spikes.
• Carry the key in an input field or a header; clientMutationId works for this role only if the server stores it.

Interview angle: when asked "what happens if the same mutation arrives twice?", cover three layers — root fields are ordered within a request, transactions isolate between requests, and idempotency keys make retries harmless. Candidates who answer only "mutations run serially" have described an ordering property, not duplicate protection.