Skip to content

Update description of Fragments to emphasize evolving data needs #1193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Update description of Fragments to emphasize evolving data needs #1193

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5cf74db
Update the description for when to use a fragment
janettec Sep 12, 2025
992fb15
some small edits for new lines + updating a word
janettec Sep 12, 2025
12793fc
Simplify language and remove reference to 'colocation'
janettec Sep 19, 2025
4dc59ca
format
janettec Sep 19, 2025
df32811
Respond to feedback from last working group meeting
janettec Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 18 additions & 12 deletions spec/Section 2 -- Language.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -587,13 +587,13 @@ FragmentName : Name but not `on`

Fragments are the primary unit of composition in GraphQL.

Fragments allow for the reuse of common repeated selections of fields, reducing
duplicated text in the document. Inline Fragments can be used directly within a
selection to condition upon a type condition when querying against an interface
or union.
Each client component should declare its data needs in a dedicated fragment.
These fragments may then be composed in the same fashion as the components
themselves to form a GraphQL operation to issue to the server.
Comment on lines +590 to +592
Copy link
Member

@benjie benjie Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm concerned that "component" here will be read too specifically (e.g. to mean a React component) rather than broadly (e.g. a "component" of client logic such as a function, class, or other...). Perhaps something along the lines of:

Suggested change
Each client component should declare its data needs in a dedicated fragment.
These fragments may then be composed in the same fashion as the components
themselves to form a GraphQL operation to issue to the server.
Each data-consuming component (function, class, UI element, and so on) of
a client application should declare its data needs in a dedicated fragment.
These fragments may then be composed, following the usage of the components
themselves, to form a GraphQL operation to issue to the server.

Copy link
Member

@benjie benjie Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's worth noting here that this places a should on the client not the server.


For example, if we wanted to fetch some common information about mutual friends
as well as friends of some user:
For example, if we have some logic that requires `id`, `name`, and `profilePic`
to render a profile, and we want to apply that logic to the friends and mutual
friends of a user:

```graphql example
query noFragments {
Expand All @@ -612,29 +612,35 @@ query noFragments {
}
```

The repeated fields could be extracted into a fragment and composed by a parent
fragment or operation.
The fields required to render a profile can be extracted into a fragment and
composed by a parent fragment or operation.

```graphql example
query withFragments {
user(id: 4) {
friends(first: 10) {
...friendFields
...friendProfile
}
mutualFriends(first: 10) {
...friendFields
...friendProfile
}
}
}
```

"Common fields for a user's friends."
fragment friendFields on User {
```graphql example
"Fields required to render a friend's profile"
fragment friendProfile on User {
id
name
profilePic(size: 50)
}
```

If the profile rendering logic no longer needs `name`, the `name` field can be
removed from the `friendProfile` fragment and it will no longer be fetched in
both locations the fragment is consumed.

Fragments are consumed by using the spread operator (`...`). All fields selected
by the fragment will be added to the field selection at the same level as the
fragment invocation. This happens through multiple levels of fragment spreads.
Expand Down