[Sketch] Hoisted Query Selections

[captbaritone]

As discussed with folks (@mjmahone, @PascalSenn and @michaelstaib I think?) at GraphQL Conf 2026

---

This sketch explores a feature which allows access to the Query root from within any selection set.

fragment UserProfile on User {
  name
   # Relay can hoist this to the root of every query that includes this fragment
  __query {
    viewer {
      canDeleteUsers
    }
  }
}

Motivation

A common pain point in developing applications while using fragment co-location is that you need access to some global value in a deeply nested component. For example, you may want to check whether the current viewer has some specific permission or query for the set of options that are valid for a specific drop-down menu.

Today, this requires threading a separate fragment on Query all the way through to this potentially deeply nested component in parallel with the component's existing fragment, which is likely related to the data that component is actively rendering. Today, when this is impractical, we recommend updating the schema and re-exposing the root field(s) on whatever arbitrary type you already have a fragment on.

Hoisted Query Selections allows you to define the root data you need as a __query selection on any type and the Relay compiler/ can "hoist" the selections up to the root of all queries which include the fragment with the __query. Relay Runtime can then ensure the data is materialized out of the normalized store.

Example

Let's look at an example of how this works. Note that the real benefit here is not felt locally in the component that uses the data as much as its felt in the potentially long chain (potentially multiple long chains) of components between the query roots and the component that needs the data.

Before

 function UserProfile({ userRef, queryRef }) {
  const user = useFragment(
    graphql`
      fragment UserProfile_user on User {
        name
      }
    `,
    userRef,
  );
  const query = useFragment(
    graphql`
      fragment UserProfile_query on Query {
        viewer { canDeleteUsers }
      }
    `,
    queryRef,
  );

  return (
    <div>
      <h1>{user.name}</h1>
      {query.viewer.canDeleteUsers && <button>Delete</button>}
    </div>
  );
}

After

function UserProfile({ userRef }) {
  const data = useFragment(
    graphql`
      fragment UserProfile on User {
        name
        __query {
          viewer {
            canDeleteUsers
          }
        }
      }
    `,
    userRef,
  );

  return (
    <div>
      <h1>{data.name}</h1>
      {data.__query.viewer.canDeleteUsers && <button>Delete</button>}
    </div>
  );
}

Tradeoffs

Pros

1. If there are any @skip/@include along the path from the query root to the fragment where __query is selected, Relay can include those conditions in the root selections.
2. If multiple items fetch this data, Relay compiler will dedupe them. This is more efficient than re-exposing the root field on a named type, especially if the component is being rendered in a list.

Cons

1. This is yet another special syntax for users to learn, and it's not part of the specification.
2. It's unclear what should happen if the fragment is transitively referenced in a subscription or mutation. Should the __query be ignored? Should it error? Ignoring it could be confusing, and making it an error could significantly reduce the feature's utility since spreading fragments into mutations is a common pattern.