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
to add and remove selections as needed.

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