Skip to content

Commit 61217f0

Browse files
janettecleebyronbenjie
authored
Update description of Fragments to emphasize evolving data needs (#1193)
* Update the description for when to use a fragment * some small edits for new lines + updating a word * Simplify language and remove reference to 'colocation' * format * Respond to feedback from last working group meeting * Apply suggestion from @benjie Co-authored-by: Benjie <benjie@jemjie.com> --------- Co-authored-by: Lee Byron <lee@leebyron.com> Co-authored-by: Benjie <benjie@jemjie.com>
1 parent 9c0442b commit 61217f0

File tree

1 file changed

+19
-12
lines changed

1 file changed

+19
-12
lines changed

spec/Section 2 -- Language.md

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -587,13 +587,14 @@ FragmentName : Name but not `on`
587587

588588
Fragments are the primary unit of composition in GraphQL.
589589

590-
Fragments allow for the reuse of common repeated selections of fields, reducing
591-
duplicated text in the document. Inline Fragments can be used directly within a
592-
selection to condition upon a type condition when querying against an interface
593-
or union.
590+
Each data-consuming component (function, class, UI element, and so on) of
591+
a client application should declare its data needs in a dedicated fragment.
592+
These fragments may then be composed, following the usage of the components
593+
themselves, to form a GraphQL operation to issue to the server.
594594

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

598599
```graphql example
599600
query noFragments {
@@ -612,29 +613,35 @@ query noFragments {
612613
}
613614
```
614615

615-
The repeated fields could be extracted into a fragment and composed by a parent
616-
fragment or operation.
616+
The fields required to render a profile can be extracted into a fragment and
617+
composed by a parent fragment or operation.
617618

618619
```graphql example
619620
query withFragments {
620621
user(id: 4) {
621622
friends(first: 10) {
622-
...friendFields
623+
...friendProfile
623624
}
624625
mutualFriends(first: 10) {
625-
...friendFields
626+
...friendProfile
626627
}
627628
}
628629
}
630+
```
629631

630-
"Common fields for a user's friends."
631-
fragment friendFields on User {
632+
```graphql example
633+
"Fields required to render a friend's profile"
634+
fragment friendProfile on User {
632635
id
633636
name
634637
profilePic(size: 50)
635638
}
636639
```
637640

641+
If the profile rendering logic no longer needs `name`, the `name` field can be
642+
removed from the `friendProfile` fragment and it will no longer be fetched in
643+
both locations the fragment is consumed.
644+
638645
Fragments are consumed by using the spread operator (`...`). All fields selected
639646
by the fragment will be added to the field selection at the same level as the
640647
fragment invocation. This happens through multiple levels of fragment spreads.

0 commit comments

Comments
 (0)