What is the point of naming queries and mutations in GraphQL?

Question

Pardon the naive question, but I've looked all over for the answer and all I've found is either vague or makes no sense to me. Take this example from the GraphQL spec:

query getZuckProfile($devicePicSize: Int) {
  user(id: 4) {
    id
    name
    profilePic(size: $devicePicSize)
  }
}

What is the point of naming this query getZuckProfile? I've seen something about GraphQL documents containing multiple operations. Does naming queries affect the returned data somehow? I'd test this out myself, but I don't have a server and dataset I can easily play with to experiment. But it would be good if something in some document somewhere could clarify this--thus far all of the examples are super simple single queries, or are queries that are named but that don't explain why they are (other than "here's a cool thing you can do.") What benefits do I get from naming queries that I don't have when I send a single, anonymous query per request?

Also, regarding mutations, I see in the spec:

mutation setName {
  setName(name: "Zuck") {
    newName
  }
}

In this case, you're specifying setName twice. Why? I get that one of these is the field name of the mutation and is needed to match it to the back-end schema, but why not:

mutation {
  setName(name: "Zuck") {
...

What benefit do I get specifying the same name twice? I get that the first is likely arbitrary, but why isn't it noise? I have to be missing something obvious, but nothing I've found thus far has cleared it up for me.

ruohola · Accepted Answer · 2021-09-17 11:25:28Z

61

The query name doesn't have any meaning on the server whatsoever. It's only used for clients to identify the responses (since you can send multiple queries/mutations in a single request).

In fact, you can send just an anonymous query object if that's the only thing in the GraphQL request (and doesn't have any parameters):

{
  user(id: 4) {
    id
    name
    profilePic(size: 200)
  }
}

This only works for a query, not mutation.

EDIT:
As @orta notes below, the name could also be used by the server to identify a persistent query. However, this is not part of the GraphQL spec, it's just a custom implementation on top.

edited Sep 17, 2021 at 11:25

ruohola

24.8k7 gold badges76 silver badges118 bronze badges

answered Dec 9, 2015 at 17:52

Petr Bela

8,7912 gold badges36 silver badges38 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

Danielo515 Over a year ago

Do you have a reference for this sentence: Once you use the query keyword you need to provide a name? I am faced this problem and I didn't found an official documentation about it

Petr Bela Over a year ago

The official specification is at spec.graphql.org. Don't take my word for it (read the full spec if you're implementing a server or a library and need a reference) but I think it's actually possible to specify a query with the keyword but without a name. I think mutation fields still need a name though.

ruohola Over a year ago

The unnamed versions: query { myName } and mutation { setName(name: "Zuck") { newName } } are both valid according to the spec: spec.graphql.org/draft/#sec-Root-Operation-Types. Edited the incorrect information out of the answer.

Eric Burel Over a year ago

Any source with feedback in terms of consequences at scale? Removing query name and injecting values in the query rather than using variables seems fine when the variables are known ahead of time (not using user input), but maybe there are consequences I do not foresee ?

orta · Accepted Answer · 2018-09-27 18:15:46Z

17

We use named queries so that they can be monitored consistently, and so that we can do persistent storage of a query. The duplication is there for query variables to fill the gaps.

As an example:

query getArtwork($id: String!) {
  artwork(id: $id) {
    title
  }
}

You can run it against the Artsy GraphQL API here

The advantage is that the same query each time, not a different string because the query variables are the bit that differs. This means you can build tools on top of those queries because you can treat them as immutable.

answered Sep 27, 2018 at 18:15

orta

4,3051 gold badge28 silver badges34 bronze badges

Collectives™ on Stack Overflow

What is the point of naming queries and mutations in GraphQL?

2 Answers 2

4 Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

4 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related