Fragment Modularity

[mjmahone]

See This RFC for more details: https://github.com/graphql/graphql-wg/blob/main/rfcs/FragmentModularity.md

In an ideal world, fragments would be so modular that our validation rules would be inductive: if Query Q depends on Fragment B and C, then so long as we know fragments B and C are valid, and we run validation on Q against B and C's type declarations (i.e. just the fragment B on Foo portion of the fragment definition, the stuff before the selection set brackets { ... }), then we know Q is valid.

I'm hoping this discussion helps us clarify the work required to set us in that direction, and makes sure related projects, like Client Controlled Nullability, are at least compatible with this evolution.

Currently I see three different "solution spaces" for addressing this problem:

• Adding a new syntax to have fragment names as keys in our existing tree-shaped responses.
• Creating an alternative response format that would bring the cost of including fragment information down
• Adding metadata to allow clients to know which fragments are fulfilled

Personally, I'm of the opinion that the metadata approach is a cudgel: it might give clients some hooks to help solve client-specific problems, but doesn't give us a clear path towards solving other, related problems like Error Boundaries. So I'm more focused on the other two paths: my favored approach would be one where you could safely opt-in to everything being modular.

To get the discussion started, cc @josephsavona @captbaritone @hwillson @twof who have all explicitly expressed interest in this area.

[twof]

I'm feeling like Aliased Spreads are my favorite at the moment. It feels like a logical extension of the mechanics already available in GraphQL.

Since the basis for this discussion is Relay, would you be down to provide an example Relay component? Especially one at the level of complexity where we start to see the problems that this RFC is trying to resolve. I think it will help with discussion.

[josephsavona]

Example 1: Testing If an Inline Fragment Matched

Consider a component that displays an entity, which might be an Actor (an entity with a name). If it's an actor we want to render the name, otherwise render nothing. This commonplace operation is surprisingly not well supported in GraphQL. The basic shape of the code (in Relay) is something like this:

function Profile(props) {
  const entity = useFragment(
    graphql`
      fragment Profile_user on Node { // Node is an interface
        ... on Actor { // Actor is an interface
          name // String!
        }
        id
      }
    `, 
    props.entity,
  );
  // goal: render the name if the entity was an Actor, else null.
  if ( /* entity is Actor */ ) {
    const name: string = /* get entity as Actor */.name;
    return name;
  }
  return null;
}

As you can see, it isn't clear how to test that the ... on Actor inline fragment evaluated, and it also isn't clear how to safely access the name if that fragment did evaluate.

Status Quo

In the above case Relay currently emits a Flow type (or similar TypeScript) type as follows:

type Profile_user = {
  id: string,
  name?: string?, // optional because it isn't evaluated if the type doesn't match
};

Note that querying __typename within the ... on Actor spread doesn't help, since you'd still end up having to do an existence check on a key in the response. So you end up with code today that is like:

function Profile(props) {
  const entity = /* ... same ... */
  // goal: render the name if the entity was an Actor, else null.
  if (entity.hasOwnProperty('name')) { // in practice you might also need a null check on the value too
    const name: string = entity.name;
    return name;
  }
  return null;
}

Ideal: Check a named property

Ideally though, we'd have aliased inline fragments and named fragments, so you could just name the ... on Actor condition and use this named result to test. That would look like:

function Profile(props) {
  const entity = useFragment(
    graphql`
      fragment Profile_user on Node { // Node is an interface
        asActor: ... on Actor { // Actor is an interface. The alias could also be automatic based on the type
          name // String!
        }
        id
      }
    `, 
    props.entity,
  );
  // goal: render the name if the entity was an Actor, else null.
  if (entity.asActor != null) {
    const name: string = entity.asActor.name;
    return name;
  }
  return null;
}

Where here the result type would be described by the following Flow/TS type:

type Profile_user = {
  id: string,
  asActor?: {
    name: string,
  },
}

Here, it's very clear that if the asActor property exists, it is data that conforms to the expected shape.

Example 2: For Fragment Spreads

This also works well for fragment spreads. Consider that we want to render a child component only if its fragment was evaluated (only if its type matched — though this could work well for spreads that are condition w eg @include/@skip too). We could use an aliased fragment spread to make it easy to check whether the fragment was evaluated or not:

function Profile(props) {
  const entity = useFragment(
    graphql`
      fragment Profile_user on Node { // Node is an interface
        asActor: ...ActorProfile_actor // given "fragment ActorProfile on Actor", where Actor is an interface
        id
      }
    `, 
    props.entity,
  );
  // goal: render <ActorProfile> if that fragment matched (ie entity was an Actor
  if (entity.asActor != null) {
    return <ActorProfile actor={entity.asActor} />;
  }
  return null;
}

Again, the presence of asActor in the response means we have a shape that can be passed to the child component.

Status Quo

There isn't a great workaround for the fragment spread case today. Developers would basically have to do:

function Profile(props) {
  const entity = useFragment(
    graphql`
      fragment Profile_user on Node { // Node is an interface
        ...ActorProfile_actor // given "fragment ActorProfile on Actor", where Actor is an interface
        ... on Actor { // This type has to be kept in sync w the fragment definition **manually** 
          isActor: __typename
        }
        id
      }
    `, 
    props.entity,
  );
  // goal: render <ActorProfile> if that fragment matched (ie entity was an Actor
  if (entity.hasOwnProperty('isActor')) {
    return <ActorProfile actor={entity} />;
  }
  return null;
}

Note how we have to manually add an extra inline fragment, the type of which has to be kept in sync w the fragment's type manually. Gross, and brittle.

[glasser]

I don't have any strong opinions about which outcome is better. I was a bit surprised, though, to not see the benefits of field merging mentioned as part of the tradeoffs involved. While field merging certainly adds a lot of complexity to GraphQL and gets in the way of some of the functionality described in the RFC, it also means that you can put together a page's query by cobbling together potentially-overlapping fragments from subcomponents and not have to worry about whether you'll be getting identical data repeated many times on the wire. So I think understanding which potential solutions may end up bloating response sizes with repeated data would be helpful.

[mjmahone]

As to the cost: from what I understand, we already were paying that cost because all of our server-client traffic was compressed by default. When we used our standard internal networking libraries, these came for free as other teams basically had resolved the answer that compressing/decompressing is almost always going to be faster (and less expensive) than the network time to send those extra bytes. I wasn’t personally involved in this investigation, though, so it would absolutely be worth independently verifying this holds true (and still holds true) in other ecosystems.

This answer might be different in different environments though: for server to server traffic where the servers are on a local network, maybe compression and decompression is actually a worse trade off than large responses?

[yaacovCR]

• You can create hashes on the fly based on the first response path that the node is resolved in.

Does this last option preclude combining nodes from different paths in the tree?

[yaacovCR]

I guess I don’t understand how these hashes would be calculated otherwise!

[mjmahone]

Does this last option preclude combining nodes from different paths in the tree?

Nope! Your server just needs some way of saying "this part of the tree is the same as this other part, so provide the same primary key". I likely wouldn't recommend the on-the-fly hash approach, but it's possible we'd design some form of "how do strong objects work" spec that would allow a server to implement a graph response via on-the-fly primary key computation.

[josephsavona]

This is definitely the big tradeoff with named fragments. I wrote up a proposal for a normalized response format internally at Meta and @captbaritone is prototyping it so that we can test aspects such as response size and processing time relative to the spec's "tree" format.

[yaacovCR]

In terms of fragment modularity and different response formats, I think it's important to note explicitly that the introduction of the defer/stream directives creates a different response format with an error boundary (graphql/defer-stream-wg#23), or, at least it does as currently implemented. The only reason that it does not offer a more complete solution to fragment modularity is that the new response format is strongly recommended, but ultimately optional, if a server feels it can otherwise provide better performance., so fields within a deferred fragment can still not conflict with other fields. (There is also the separate problem of fulfillment, of course....) Mentioning this just for completeness of the problem space, really, not (cough, cough) heaven forbid, because I am still pushing that the directives be mandatory...

More seriously, any new format we have above should take into account how defer/stream will be handled. For instance, in @josephsavona 's examples above:

      fragment Profile_user on Node { // Node is an interface
        isActor: ... on Actor @defer { // Actor is an interface
          name // String!
        }
        id
      }

isActor might not end up in the initial response because the node is not an Actor, or because the server agreed to defer isActor as recommended. Presumably, in the case of a deferred fragment, we would need to substitute some placeholder special "pending" type value to indicate that more is to come. Perhaps "true" would work, as we could already indicate to the client that we know the node is an actor, although this is only natural with the appropriately named alias as above.

Anyway, the overall proposal looks incredibly interesting, would love to follow along/participate.

[yaacovCR]

Actually, the above scenario/suggestion also applies in a world where defer is mandatory. The idea is that we are talking so far about communicating just a binary fulfilled state, but there is another state, will not be fulfilled, that could also be communicated explicitly, rather than waiting for all data to finish.

[yaacovCR]

It’s certainly ok if we decide not to communicate that state as soon as we have it, on the assumption that a UI change might be premature until fields are ready, just makes sense to reject it explicitly. :)

[josephsavona]

or because the server agreed to defer isActor as recommended.

This is definitely an aside but what do you mean "recommended"? Has the defer/stream spec actually evolved to allow the server a choice in honoring these directives? That's...not good if it's the case.

[josephsavona]

I see two main approaches for handling defer/stream and named fragments:

• Use a normalized response format (Relay is experimenting with this) with explicit support for defer/stream. Our proposal is modeled as a stream with different item types, which include things like "start defer at ", "resolve defer at ", etc.
• Use a meta field to indicate deferral status within the current ("tree") format:

fragment Profile_user on Node { // Node is an interface
  isActor: ... on Actor @defer { // Actor is an interface
    name // String!
  }
  id
}

Would return something like:

{
  data: {
    id: "<node-id>",
    isActor: 
      // we know that the parent object (the Node) exists since we got here at all, so it's always safe 
      // to return an empty object that gives us a place to synchronously return a metadata field 
      // indicating that the defer is pending. The client could then choose to alias this to distinguish 
      // different fragments at the same location
      {
        __fragmentStatus: "deferred" 
      },
  },
  hasNext: true
}
{
  path: [....},
  label: "...",
  data: {
    __fragmentStatus: "resolved", // update the fragment status to resolved (could also have an error case)
    name: "<node-name>"
  },
  hasNext: ...,
}

[yaacovCR]

This is definitely an aside but what do you mean "recommended"? Has the defer/stream spec actually evolved to allow the server a choice in honoring these directives? That's...not good if it's the case.

Highly recommended is the current wording I believe, allowing the server to not defer if it already has the data, ie client should be able to rely on performance request just not actual defer response type.

@josephsavona

graphql/defer-stream-wg#7

[AnthonyMDev]

Thank you for putting together this proposal! I recognize the problem statement provided is valid, and I believe we should be working on solutions. The Apollo iOS Client and our users struggle with these issues constantly.

The approach of modularizing fragments under their own response keys seems to be the clear favorite, but I am concerned about the duplication of data with this approach (FWIW, I think making it opt-in via aliases is definitely the way to go if we use this approach). But I worry that every time someone hits a validation conflict, they will just opt-in to modularity and make their operations less performant. Start nesting those modular fragments at large scale and you are going to duplicate a lot of data for the sake of developer convenience.

One of the big selling points of GraphQL is reducing data OTA by fetching only what you need. This solution, if implemented, is going to actively encourage duplication of data in way too many places.

Similarly, build tools must implement these whole-program validations, making the cost to changes O(codebase) rather than O(changed fragment). Because any change to a fragment could break the no-conflicting-aliases rule, any change to any fragment has to be checked against all the operations that transitively reference that fragment. Developers see this in the form of slower builds and slower tools, and rightfully attribute this as GraphQL introducing friction in their develpment process.

While this is true, there are always trade offs to performance. This proposal removes developer-side validation checks speeding up build times, but incurs a greater run-time cost. Execution of duplicated data is going to increase CPU cycles and data transport. I think that’s generally a bad trade-off to make.

Fragment spreads as they work today were intended to provide for the modularity we are seeking here. But as we’ve seen, there are serious limitations concerning whole-program validation and alias conflicts.

But providing opt-in for breaking fragments out into duplicated data sets seems heavy-handed to me. I’d like us to explore more possibilities of how to resolve the conflicts prior to data duplication.

Perhaps there is a way to create unique keys for conflicting fields in response data and have clients map each of those fields to the correct response key at run time?

I am not outright against this proposal, but I do think we should do a deeper dive into other possible solutions before moving in this direction. Starting with an understanding all of the cases in which conflicts can cause validation errors, we can determine if there are ways for servers and clients to be smarter about resolving them.

I am, however, strongly in favor of the __fulfilled metadata field. It makes a LOT of client side work much easier and resilient to schema changes without the drawbacks of separating out fragments.

[mjmahone]

Fragment spreads as they work today were intended to provide for the modularity we are seeking here

Kind of. They were essentially created with DRY and inheritance in mind. The first iteration of our client used schema based type models: type models were used for the majority of the data GraphQL clients consumed when GraphQL was first open sourced, but even then we knew they were a mistake. Inheritance based response models (similar to Apollo's JS client models) were relatively new at that point. Note I don't consider response models modular, because they can't be decomposed across package boundaries without importing all grandchild (and great grandchild, etc.) fragments a definition spreads, or without somehow explicitly including all of the recursively used fields into a single structure.

I’d like us to explore more possibilities of how to resolve the conflicts prior to data duplication.

I agree, which is why I've proposed exploring a "Graph Mode" for fragments, which should both allow us to solve the modularity issues I describe below and also avoid duplication in the response. Basically, if an operation receives a "graph mode" response, it would mean that conflicting overlapping fields are allowed (how we do that is up for debate, but there are a few potential solutions) but won't cause duplication. With that, we should be able to cheaply include in the response the set of fragments that were fulfilled by any specific value in the graph.

[mjmahone]

@AnthonyMDev: great point, let's do a deep dive on validation issues! I'm going to create another top-level response to kick off that deep dive. We can keep discussions about response size I think inline with the other top-level responses.

Overview

There's a few reasons validation rules are non-modular today. I'll classify all our validation rules into 5 buckets, ranked from, in my opinion, most-modular to least-modular.

There are, by my count, 26 Executable Definition validation rules. Of these, 17 are already fully modular (Bucket 1). 4 rules could be made compatible with standard package/module based build systems, if we created the concept of "definition declarations" (Bucket 2) and "imports" for fragment spreads (Bucket 3). 3 more rules are not modular because fragments do not define each variable they use as part of their "definition declaration" (Bucket 4). Bucket 4's rules could be made modular if we had the declarations and imports from Buckets 2 and 3, and also required fragments to declare all the variables they use. The final set is a single rule, that Fields in a Set must be able to merge. Specifically, that fields in a set must be able to merge with fields in a selection set's fragment spreads, recursively (Bucket 5). This one rule is what makes fragments hopelessly non-modular, even if all of the above is solved. All of the other buckets could be solved without changing the response shape: we would need to potentially change GraphQL's syntax, but that changed syntax should only need to modify validation, rather than the query's execution algorithm. But for Field Set Merging Across Fragments, we need a way to know fields cannot end up overlapping with incompatible fields in order to solve.

1: Rules requiring only a definition and the declarations of its first order fragment spreads

For these, we can run the validation entirely knowing only: the contents of a definition, and the definition declaration of any fragment it spreads. What I mean by a definition declaration, is the contents of a definition that come before the opening selection set. That includes:

• Whether it's an operation or fragment
• The type that the definition's selection set is on
• The variables defined on the definition, if any
• Any operation or variable definition directives used (we can ignore directives for the rest of this discussion, though)

So this would include the bolded portion of the definitions:

• query Foo($x: String!) @bar { ...Bar }
• fragment Bar on Node { id }

The 17 rules that fit this category are:

• Subscription Single Root Field
• Field Selections
• Leaf Field Selections
• Argument Names
• Argument Uniqueness
• Fragment Spread Type Existence
• Fragments On Composite Types
• Fragment Spread Target Defined
• Fragment Spread is Possible, including the 5 sub-validation rules
• Values of Correct Type
• Input Object Field Names
• Input Object Field Uniqueness
• Input Object Required Fields
• Directives are Defined
• Directives are in Valid Locations
• Directives are Unique Per Location
• Variables are Input Types

2: Rules requiring knowing the declaration of all definitions

These rules require knowing each definition's declaration, but do not require knowledge about the definition's selection set contents.

The 3 rules are:

• Operation Name Uniqueness
• Lone Anonymous Operation
• Fragment Name Uniqueness

3: Rules requiring both the declaration and fragment spreads of each definition

These rules are those that require we know the dependencies of all definitions, i.e. which fragments they spread, and may need to know the declaration of every definition too.

The 2 rules are:

• Fragments Must Be Used
• Fragment Spreads Must Not Form Cycles

4: Rules that need to know what variables a fragment used

Because fragments do not define all the variables they use, during validation we need to keep track of all the variables that were defined, and also what variables a specific fragment uses, in order for these rules to work. However, if we always included these variable usages in a fragment's definition declaration, we could make these modular provided we solved buckets 2-3 too.

The 3 rules are:

• All Variables Uses Defined
• All Variable Usages Allowed
• All Variables Used

5: Rules that require knowing the contents of the selection sets of all definitions

These are the least modular: there's no gimmicks you can do to avoid looking through every field in every definition and keeping track of some mutable state in order to come to the right answer for these validation rules. There's only a single rule in this set.

The 1 rule is:

• FieldsInSetCanMerge

[AnthonyMDev]

How do you resolve conflicts but not non-conflicts, without knowing the entirety of all definitions?

You're right, you don't. You have to know the entirety of all definitions. But isn't that how it works today?

You have a few problem statements. 1. Resolving conflicts of fields in fragments. 2. Build time is too long because of validation.

I'm focusing here on the first issue:

Developers cannot reason about fragments in isolation. Because the results of a fragment are spread/inlined at their usage site, GraphQL requires global validations such as preventing conflicting fields/arguments at a given path in the response. Developers frequently have to come up with arbitrary aliases for fields as a way to avoid accidental collisions with unrelated code — breaking encapsulation.

If the primary issue you are trying to resolve is the build time issue, I don't think that your fragment modularity proposal is the correct approach. The reason your proposal makes this opt-in behavior is because it is less performant at run-time and should only be used when really needed. If you are using it to reduce build times, you will be using it as best practice everywhere. Even when your fragments don't have any conflicts, you are going to opt-in to modularity just so you don't incur the overhead of checking for conflicts that don't exist. You are going to duplicate data all over the place unnecessarily. As I said above, I think this trade-off is a bad one. Meta is of course allowed to make that choice, but I would not support making it part of the spec.

I'm not sure what the solution to your build time issues are right now. My first thought would be caching metadata on already compiled fragments and operations and tracking changes, but I'm sure you have already explored that line of thought. I know BUCK does a ton of caching already, I assume it's caching GraphQL stuff as well.

---

I think this line of thought goes into some dangerous and complicated territory, but for the thought experiment, theoretically:

A Fragment is only ever executed as part of an operation. If you versioned fragments, you could have operations that rely on a version of a fragment. In that case, you can make changes to a Fragment and avoid checking every operation for references to that fragment. You'd just need to have operations update to the new version of a fragment. Then you only need to check fragments when you compile an individual operation.

---

I'm all for investing in making GraphQL work well at the largest scale. Meta almost certainly has the largest GraphQL schema out there, but many others that I support are growing rapidly in scale and already have huge schemas.

I'd like us to continue to consider solutions to both the local reasoning issue AND the build time issue. But I don't think that modular fragment responses is the right approach to either of those problems. The drawbacks are far too great.

[mjmahone]

You have to know the entirety of all definitions. But isn't that how it works today?

Not really. We've made 95% of our system such that when you make a change to a fragment, the developer just rebuilds that single library, and reliably knows every app using that library will build, without needing to do the full build on every app. This basically only breaks down when adding conflicting fields and adding/removing variables (though we have some hacks for variables people rely on which we'd like to formalize).

The reason your proposal makes this opt-in behavior is because it is less performant at run-time and should only be used when really needed.

I'm not totally confident this is true. I'll try to do some real testing in the next few weeks to get concrete numbers, but we take this on faith right now that duplicating fields in the response is always worse for performance. Especially once you include execution time costs of merging deeply nested trees, there's definitely a tradeoff to measure.

If the primary issue you are trying to resolve is the build time issue

The primary issue is developer experience, but build time is one component of that. Having fully modular builds is positive proof that the developer experience can be made to work in a modular way. As a concrete example, say I have three different client binary apps (APKs or IPAs). Each of these will use a single query, but they all share a core fragment. The shared fragment was developed by a team that only ever builds App A, but is also used by developers for Apps B and C.

Shared Fragment

fragment ProfilePicture on Profile {
  profile_image(width: 50) {
    uri
  }
}

If some random app has their main query like this:

query C {
  user {
    ...ProfilePicture
    ...CProfile
  }
}

fragment CProfile on User {
  smallImage: profile_image(width: 100) { uri }
}

then in order to make changes to ProfilePicture, I need to not only know and potentially update every definition that directly depends on me (expected when changing a declaration), but I also need to know about every sibling fragment, and all of their recursive dependencies, which I might cause to no longer be valid in the parent definition's context. That's what we're trying to resolve: I should never need to build CProfile in order to validate that my changes to ProfilePicture are good to ship.

For a team building features two hundred or more teams consume, needing to find and update every clash across every consuming team's nested dependency hierarchy is not tenable.

[josephsavona]

If the primary issue you are trying to resolve is the build time issue, I don't think that your fragment modularity proposal is the correct approach.

To clarify, we're concerned with solving all the problems described in the problem statement. When I referred to the "core issue" as being with build times, I was meant that the core issue with the alternatives to named fragments in this thread is that they solve the DX concerns listed in the problem statement, but unfortunately don't solve the build concerns of keeping builds O(changed).

The reason your proposal makes [modular fragments] opt-in behavior is because it is less performant at run-time and should only be used when really needed.

I think there's a misunderstanding here: we propose making modular fragments opt-in for backwards compatibility. We would expect that our clients would fully switch to modular fragments, with validation disallowing the legacy "spread" behavior.

I'd like us to continue to consider solutions to both the local reasoning issue AND the build time issue. But I don't think that modular fragment responses is the right approach to either of those problems. The drawbacks are far too great.

If I'm understanding correctly, your main concern is about the performance costs of modular fragments due to increased query execution time (potentially calling the same resolvers multiple times, per modular fragment) and increased response size (including the result at each modular fragment). To be clear, we're also concerned about the potential overhead. However, our investigations around different response formats (@mjmahone mentioned above our use of flatbuffers in the past) has shown that alternative response formats could alleviate or remove this overhead — yes, a naive implementation of modular fragment responses would incur overhead, but it is not yet clear that there is no mechanism to reduce/avoid it. There are also other compelling reasons to explore alternative response formats (for example, for apps with highly cyclic data models and lots of querying parent->child->parent->child relationships, the current response format can incur the same repetition and bloating you're concerned about!).

Given the intuitive mental model and syntax for named fragments and the fact that it takes us closer to solving all the problem statements, we believe that the best place to focus is on investigating the potential runtime performance and ways to mitigate it. We're actively working on an experiment to measure the overhead of a normalized response format, for example.

Of course, we also welcome alternative proposals that address both the DX and build speed challenges!

[AnthonyMDev]

@mjmahone @josephsavona I have a lot of thoughts to respond to this. I just had a discussion with my team and I'm getting the sense that we aren't completely clear about what the build step you're trying to speed up is really trying to accomplish. I'd love our teams to have a chat and collaborate further on providing a solution for this. I haven't been able to find either of your e-mail addresses, but if you're interested, I think it would be productive for us to have a call and talk through the technical details of what you are trying to achieve a bit more. If you are willing to, you can e-mail me at [email protected] so we can find a time to have a meeting!

@mjmahone

How do you resolve conflicts but not non-conflicts, without knowing the entirety of all definitions?

Thinking about this more, I'm wondering if a solution similar to my approach could actually solve this. I may be missing information on what you are trying to achieve here and how your system works. But perhaps fragments can be built independently of know all definitions if we approach resolving conflicts at the operation level.

At some point, you have to actually build each the operation definition, and at that point, you would have an understanding of where your conflicts are and figure out how to resolve them. But when building your fragments, you wouldn't have to do that. If the operation understands how the data for the conflicting fields is being remapped, then you can have some sort of transform of the data to the shape that a fragment expects when accessing that fragment at runtime.

So given my example above, an operation could receive this response:

{
  "id": 0,
  "BarFragment.name": "Checking Account",
  "account_number": "1813584651657684",
  "AsUser.name": "AnthonyMDev",
  "age": 29
}

And when you access the BarFragment, the operation (or some helper somewhere) could map the name field in the response data that it provides to the BarFragment to the BarFragment.name field. And when accessing the ... on User inline fragment, it would map the name field to the AsUser.name field.

So the BarFragment receives response data that looks like this:

{
  "name": "Checking Account",
  "account_number": "1813584651657684"
}

and the ... on User inline fragment receives data that looks like this:

{
  "name": "AnthonyMDev",
  "age": 29
}

This provides you with fragment modularity, while preventing the duplication of data. Would something like this work for you?

[josephsavona]

@AnthonyMDev I replied below

[josephsavona]

I just had a discussion with my team and I'm getting the sense that we aren't completely clear about what the build step you're trying to speed up is really trying to accomplish.

We're happy to discuss offline, but I also think it's important for us to be clear about this to the broader GraphQL community, so i'll try to answer here (also, it's performance review time at Meta and this is the perfect way to procrastinate btw writing reviews).

Our goal for our GraphQL tooling is to be as fast and responsive as possible in order to keep developers in the flow of building their app. This impacts how we think about designing our build tools and our IDEs. In general our GraphQL clients promote writing GraphQL as small fragments colocated with UI/product code that describe the specific data dependencies of that product code, which then compose (via fragment spreads) the dependencies of any child UI components or product code that it may call. Let's refer to these as colocated fragments, though of course at the root of a UI surface you might have actually have a query that defines the fields needed by the root of your UI and spreads for child components.

For our build tools, our goal is to allow developers to quickly change their colocated fragments, ie to change their data selections, and then preview the updated application as quickly as possible. This translates to re-producing as few artifacts as possible to preview the updated version of the application: eg any generated classes, type definitions, or other artifacts necessary to rebuild. So for example we generally try to avoid rebuilding the entire GraphQL corpus, and instead rebuild only the artifacts that could actually be affected by the change to the fragment. That's our current state of the art: to rebuild all queries and fragments which are transitively referenced by any operation which (transitively) references the changed fragment. For highly shared fragments, this can be a ton of queries and fragments. Our goal is that we would, in the common case, rebuild exactly one artifact: the class/type definition/ast/other representing the fragment itself, without even having to look at the definition of any other fragment or operation. And by common case I mean changing the selections of the fragment without changing its signature: if fragments were truly modular, then changes to selections alone could never invalidate build artifacts from other fragments.

For our IDE tooling, our goal is to near-instantaneously return all validation errors across the codebase as a result of the user's change: the earlier that our tooling provides feedback, the easier and faster it is for a developer to address. Here, it's clear that if fragments are not modular, then any change to a fragment's selections could cause invalidation errors anywhere that fragment is transitively referenced, requiring checking all those places. So just like with builds, we similarly want to make fragments modular so that by design, changes to selections only does not require running validation rules on anything other than the fragment definition in isolation (you have to check that any fragment spreads are valid, but you only have to look at their signature, not their contents).

I hope this helps to clarify why the solutions you've proposed don't achieve our goal: they require an additional build stage in which we must look and transform the contents of the transitive fragments referenced by operations, and not just the fragment that was changed.

One thing that is probably not obvious from the above is: how do you actually run the updated queries using the new fragment content? If our build tools only process the changed fragment, that would seem to imply that we haven't constructed updated operations referencing it, and therefore can't run the app and fetch the correct data. The catch here is that we use persisted queries: our build tools tell the server about each document that exists on the client. When we build a changed fragment, we similarly inform the server about the updated version of that fragment. In development mode, the server could then dynamically construct a query from the latest version of each fragment. This of course only works if we know that the query would be valid, which again relies on making fragments truly modular.

But when you put this all together, you get: near-instantaneous builds, near-instantaneous IDE feedback, and rapid iteration at dev time. For production builds we can of course take extra time to pre-build each operation on the server to avoid overhead.

So the solution has to make fragments truly modular — we need to avoid needing any form of transitive rewriting phase on operations affected by fragment changes. That hopefully clarifies why we are exploring the specific set of solutions:

• Named fragment spreads are by construction modular: the potential processing/size overhead needs investigation but we believe it's premature to rule this option out.
• Auto-aliasing of fields is also a viable option (either by client build tools or by the server with canonical responses), but this only addresses the build question, and not other concerns we have raised in this proposal around making it easier for developers to understand when fragment spreads and inline fragment selections are evaluated or not.

[AnthonyMDev]

@AnthonyMDev: At some point, you have to actually build each of the operation definitions, and at that point, you would have an understanding of where your conflicts are and figure out how to resolve them. But when building your fragments, you wouldn't have to do that. If the operation understands how the data for the conflicting fields is being remapped, then you can have some sort of transform of the data to the shape that a fragment expects when accessing that fragment at runtime.

@josephsavona: The catch here is that we use persisted queries: our build tools tell the server about each document that exists on the client. When we build a changed fragment, we similarly inform the server about the updated version of that fragment. In development mode, the server could then dynamically construct a query from the latest version of each fragment. This of course only works if we know that the query would be valid, which again relies on making fragments truly modular.

Maybe I'm missing something, but I'm thinking something like my proposal above could still work if we pushed off the resolution of conflicting fields to the server-side during execution. Rather than operations understanding the conflicts when being compiled (persisted) and mapping the data to the fragments, what if the server just recognized conflicts while executing the operation. As you merge the executed field data into the flattened response, if you get a conflict, you namespace the fields in the response data at that point.

In this case individual fragments or the compiled operation wouldn't know if any given field had a conflict when compiled client side.
But they could check for the flattened field in the response data, if it doesn't exist, then that means there was a conflict and they then look for the name-spaced version of the field.

So you still get this response, but the conflict is resolved JIT during the run-time execution server side.

{
  "id": 0,
  "BarFragment.name": "Checking Account",
  "account_number": "1813584651657684",
  "AsUser.name": "AnthonyMDev",
  "age": 29
}

And clients would generate field accessors that map the data like this. (psuedo-code)

BarFragment {

  init(data: JSON) {
    name = data["name"] ?? data["BarFragment.name"]
    account_number = data["account_number"] ?? data["BarFragment.account_number"]
  }

}

[josephsavona]

@AnthonyMDev That approach definitely seems viable, it allows modular builds while avoiding data duplication. However, this approach also isn't free: the server would have to keep track of which fields were fetched in order to detect collisions (ie incurring much of the overhead of the no-conflicting-aliases rule on every execution instead of once at build time). Client-side response processing code would also get larger, to handle the possibility of looking in two places for ~every field. Like with auto-aliasing, this approach also doesn't provide a syntax that allows developers to check if an inline fragment or fragment spread matched.

So to summarize these are main viable approaches we've found so far:

• Client-determined static aliases, where all fields are assigned a deterministic static alias based on name/args
  • ✅ Modular builds
  • ✅ Near-zero runtime overhead (other than slightly increased number of aliases in the query, which can inflate the query size)
  • ❌ Developers cannot conveniently check if a fragment was evaluated (there is no named entity in the response)
  • ❌ Does not allow fragments to act as an explicit boundary, ie for null bubbling
• Server-determined canonical aliases, where all response fields use field name + argument names/values, eg field(arg:value)
  • ✅ Modular builds
  • ✅ Low runtime overhead (cost is proportional to the number of fields with arguments, which tends to be low)
  • ❌ Developers cannot conveniently check if a fragment was evaluated (there is no named entity in the response)
  • ❌ Does not allow fragments to act as an explicit boundary, ie for null bubbling
• Server-determined collision avoidance, eg falling back to 'FragmentName.alias' when a collision would occur at runtime
  • ✅ Modular builds
  • ⚠️ Modest overhead - server has to track every field that has been fetched at every response path to determine if a collision would occur
  • ❌ Developers cannot conveniently check if a fragment was evaluated (there is no named entity in the response)
  • ❌ Does not allow fragments to act as an explicit boundary, ie for null bubbling
• Named fragment spreads
  • ✅ Modular builds
  • ⚠️ Potentially high runtime overhead due to duplicate field evaluation, larger response sizes
  • ✅ Developers can conveniently check if a fragment was evaluated (there is no named entity in the response)
  • ✅ Allows fragments to act as an explicit boundary, ie for null bubbling

Overall, named fragment spreads are the most robust solution for addressing the use-case. Our inclination is that we should get real data about the runtime behavior of named fragment spreads to understand the actual runtime overhead.

[josephsavona]

One other consideration: named fragments are a powerful tool that aligns with the mental model of fragments as the data equivalent to UI components and other units of application/business logic. They have tradeoffs that developers should be aware of, but critically they provide a genuinely improved "user interface" for accessing data in GraphQL. Named fragments would be opt-in for backwards compatibility, and some apps may choose not to use them. Others may use named fragments in their public API, but compile them away in the queries they send to the server where possible. That seems like an okay outcome: that we have a tool you can use when necessary but that you don't have to.

[AnthonyMDev]

@josephsavona Thank you for all of the wonderful discussion on this topic. I do recognize the value of this proposal, and hope to see something that solves these problems go forward. I'm still not a huge fan of the duplication of data, but I'm not sure if there is a way around it now that really resolves all of the product concerns.

I that the tradeoffs of this need to be really clear to developers. Unless server implementations can do some really smart stuff to ensure the performance trade offs are really negligible, I'd want to discourage pervasive usages of this by client developers.

If we did have a different response format that resolved the duplication of data better (like a graph based format), i'd be more comfortable with these changes, but that's a huge undertaking in its own right.

At this point, I've more than made my concerns clear, and I appreciate your responses to all of my questions and suggestions. I'd like to see what the rest of the community thinks still!

[josephsavona]

@AnthonyMDev Totally fair! I hope I've been clear that we are definitely also concerned about the potential perf impact of data duplication. Our inclination is that we should move forward with experimental syntax support for named fragments (behind a flag as we did with fragment variable definitions) so that we can allow tools to experiment and gain experience and report back.

For example, we'd like to experiment with this internally but we use prettier for formatting GraphQL, which in turn uses graphql-js. So having experimental syntax would help unblock us (and others likely in a similar boat) from experimentation.

[mike-marcacci]

This is all very interesting. I wanted to toss in a link to this issue/conversation where I discuss a closely related problem set and raise some very rough potential solutions. In it, @leebyron provided some context around the history and thought behind the current situation, which I found very helpful and might be useful here as well.

[josephsavona]

Thanks for the link. The comment you mentioned suggests that named fragment spreads might be problematic for normalizing clients:

How should Relay or Apollo normalize and incorporate that data into their store? By creating an intermediate object we've muddied this relationship and made life more challenging for client code. Instead you might image Relay or Apollo needing to insert some additional fields:

This comment is outdated, and named fragment spreads don't present a problem for normalizing clients. Per discussion above the main potential negative with named fragment spreads is about the possibility of duplication of data, which we'd like to explore by enabling the syntax experimentally.