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 4 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
4 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
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
29 changes: 17 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,12 @@ 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.
Fragments allow for the definition of modular selection sets that make it easier
Copy link
Contributor

Choose a reason for hiding this comment

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

Need to flush out what modular means. Matt + Pascal's suggestion: single purpose.

to add and remove selections as needed.
Comment on lines +590 to +591
Copy link
Member

Choose a reason for hiding this comment

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

Maybe something along the lines of (written whilst on Zoom, not final wording!):

Fragments allow client components and logic to describe their specific
data requirements locally. Fragments can then be composed together to
form a GraphQL operation to issue to 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 `friendProfile` logic that requires `id`, `name`,
and `profilePic`, and we want to apply that logic to the mutual friends as well
as friends of some user:

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

The repeated fields could be extracted into a fragment and composed by a parent
fragment or operation.
The fields required by `friendProfile` 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 display a friend's profile"
fragment friendProfile on User {
id
name
profilePic(size: 50)
}
```

If `friendProfile` 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