Same stream across deferred fragments

[robrichard]

Context

Currently we have validation in OverlappingFieldsCanMerge rule that prevents @stream from being placed on the same field with different arguments. If this is desired, the user can alias one of the fields which will produce two independent streams.

What happens if you have the same field with @stream, with the same arguments, both inside and out of a deferred fragment, or in two different deferred fragments?

Example 1:

query ExampleB {
  nestedObject {
    nestedFriendList @stream(initialCount: 1) {
      id
    }
  }
  nestedObject {
    ... @defer {
      nestedFriendList @stream(initialCount: 1) {
        id
        name
      }
    }
  }
}

This was discussed in the Jan 2025 defer-stream-wg meeting.

Thinking through the use case of a developer using a framework that associates UI components with fragments, we can rewrite the above to:

query ExampleB {
  ...ComponentA_query
  ...ComponentB_query
}

fragment ComponentA_query on Query {
  nestedObject {
    nestedFriendList @stream(initialCount: 1) {
      id
    }
  }
}

fragment ComponentB_query on Query {
  nestedObject {
    ...ComponentC_nestedObject @defer
  }
}

fragment ComponentC_nestedObject on NestedObject {
  nestedFriendList @stream(initialCount: 1) {
    id
    name
  }
}

The following options were ruled out:

1. Return a single stream, with all items coalesced. This is what graphql-js is currently doing.
   • This was ruled out, because a developer adding a field to ComponentC, may cause a performance impact to ComponentA, event though it appears that the fragments of ComponentC are deferred, and should be independent.
2. A validation algorithm that checks that the two streams have identical selection sets
   • This was ruled out both for complexity in determining the selection set with abstract types, as well as poor developer UX. A user adding a field to a deeply nested component could trigger this error, without knowledge of how @stream is used in adjacent components.
3. Treat each item in a streamed list as having an "invisible" defer wrapped around its selection set. For each stream item, the server may deliver a pending notice of additional deferred fields. This could allow the name field to be delivered separately from the id field, and could potentially allow us to relax the validation in OverlappingFieldsCanMerge.
   • Downside: clients have to understand this and look for additional pending and completed results in the response to account for new fields on a stream
   • This was ruled out as it felt like a complex solution to what might be a rare problem
4. Additional validation in OverlappingFieldsCanMerge to prevent stream usage on the same field in different defer contexts.
   • This would require large changes to this rule, as this rule currently visits each selection set, without way to preserve context while traversing down the operation's AST.

After further discussion, it may not be desirable to have stream on different instances of the same field at all even without wrapping @defer. Given the following query:

{
  myList @stream {
    id
  }
  myList @stream {
    id
    verySlowField
  }
}

A user adding verySlowField may be unintentionally be affecting the performance of a separate component relying on the first instance of the myList field.

Decision

The WG decided to propose expanding OverlappingFieldsCanMerge to prevent merging of any instances of @stream on the same field based on the following guiding principles:

• Simplicity and consistency over expressiveness and terseness - users blocked by this validation can use a field alias
• Preserve option value - If this use case is a major blocker we can work this this issue and the validation can be relaxed by a future spec proposal

Additionally

• We will run this proposal by the GraphQL TSC in an upcoming WG meeting to see if there is general agreement
• We will link to this issue in the validation error message to see if any community members are blocked by this rule.

[benjie]

See the YouTube recording to understand this...

query {
  nestedObject {
    nestedFriendList @stream(initialCount: 0) {
      Part1: __typename
      id
    }
  }
  nestedObject {
    ... @defer {
      Part2: __typename
      nestedFriendList @stream(initialCount: 0) {
        Part3: __typename
        id
        name
      }
    }
  }
}

[benjie]

{
  nestedObject {
    nestedFriendList {
      ...@defer {
        something {
          id
        }
      }
    }
  }
  nestedObject {
    ... @defer {
      nestedFriendList {
        ...@defer {
          something {
            id
            name
          }
        }
      }
    }
  }
}

should be equivalent to:

{
  nestedObject {
    nestedFriendList {
      ...@defer {
        something {
          id
        }
      }
    }
  }
  nestedObject {
    ...        { # no defer here
      nestedFriendList {
        ...@defer {
          something {
            id
            name
          }
        }
      }
    }
  }
}

which should be equivalent to:

should be equivalent to:

{
  nestedObject {
    nestedFriendList {
      ...@defer {
        something {
          id
        }
      }
      ...@defer {
        something {
          id
          name
        }
      }
    }
  }
}

I think the same should be true for @stream

[yaacovCR]

query {
  nestedObject {
    nestedFriendList @stream(initialCount: 0) {
      id
      slow1
    }
  }
  nestedObject {
    ... @defer {
      nestedFriendList @stream(initialCount: 0) {
        id
        slow2
      }
    }
  }
}

[
      {
        data: {
          nestedObject: {
            nestedFriendList: [],
          },
        },
        pending: [
          { id: '0', path: ['nestedObject', 'nestedFriendList'] },
          { id: '1', path: ['nestedObject', 'nestedFriendList'] },
        ],
        hasNext: true,
      },
      {
        incremental: [
          {
            items: [{ id: ' 1' }],
            id: '0',
          },
          {
            items: [{ slow1: 'slow1' }],
            id: '0',
          },
          {
            items: [{ slow2: 'slow2' }],
            id: '1',
          },
        ],
        hasNext: true,
      },
      {
        completed: [{ id: '0' }],
        hasNext: false,
      },
    ]

1. This would change stream to a merge from a simple append.
2. We might need to add an index entry.
3. The separate execution groups might differ for a list of abstract types, presumably we may have to separate stream items entries whenever the concrete runtime type changes.

[robrichard]

@Keweiqu @mjmahone We're considering adding validation to prevent @stream from being used on different instances of the same field. Are there any insights from Meta you can share about this type of usage?