The term "query" is overloaded and can be ambiguous

[benjie]

We have a general issue in the GraphQL ecosystem that the term "query" is overloaded - sometimes it refers to the query operation type or a query operation, sometimes it refers to a GraphQL request or a GraphQL document containing operations, sometimes it refers to the contents of selection sets (as in "query reuse"), and sometimes it is used as a verb to refer to the generic act of querying a server for information.

This is exacerbated by us using the term "query" in the communication with the server via {query, variables, operationName}. Arguably query should be document here since it may contain multiple operations, and those operations might be of different operation types (query, mutation, subscription). I believe this ship may have already sailed, however, and may not be worth the churn of changing this particular usage now.

---

The spec tends to be fairly disciplined in referencing query currently; it uses the following phrases:

• 'query operation' (an operation of the query type)

  • • If {operation} is a query operation:

• 'query error' (an error during execution of an operation, applies to all operation types)

  • If an input value does not match a coercion rule, a query error must be raised.

• 'query reuse' (refering to reusing selection sets, e.g. within fragments)

  • A document may contain operations (queries, mutations, and subscriptions) as well as fragments, a common unit of composition allowing for query reuse.

• 'query keyword' (literally the keyword query in a query operation)

  • If a Document contains only one operation, that operation may be unnamed or represented in the shorthand form, which omits both the query keyword and operation name.

• 'query execution' (executing an operation of any operation type)

  • GraphQL services which only seek to provide GraphQL query execution may choose to only include {ExecutableDefinition} and omit the {TypeSystemDefinition} and {TypeSystemExtension} rules from {Definition}.

  • Since the result of evaluating a selection set is ordered, the serialized Map of results should preserve this order by writing the map entries in the same order as those fields were requested as defined by query execution.

---

The term query or GraphQL query, when used as a noun outside the above phrases, typically refers to an operation (within a document). In this use it generally applies to all operation types:

• To achieve congruence with the structure of these applications, a GraphQL query itself is structured hierarchically.

• The query is shaped just like the data it returns.

• A GraphQL query can be parameterized with variables, maximizing query reuse, and avoiding costly string building in clients at runtime.

• Given a query, tools can ensure that the query is both syntactically correct and valid within the GraphQL type system before execution, i.e. at development time, and the server can make certain guarantees about the shape and nature of the response.

• At each argument position in a query may be a literal {Value}, or a {Variable} to be provided at runtime.

• Once a query is written, it should always mean the same thing and return the same shaped result.

but sometimes it only applies to the query operation type:

• The fields on the query root operation type indicate what fields are available at the top level of a GraphQL query.

Sometimes, rather than referring to an operation within a document, query refers to the operation type itself:

• The data entry in the response will be the result of the execution of the requested operation. If the operation was a query, this output will be an object of the schema's query root type; if the operation was a mutation, this output will be an object of the schema's mutation root type.

---

I'd like to attempt to reduce the ambiguity of the term query by carefully replacing it with more appropriate terms (typically operation, document and maybe request) throughout the GraphQL spec. However, as this is likely to take quite some time to do I wanted to seek approval before investing the time in a pull request. Further, it may make sense to do this in stages.

[eapache]

Yes please! I strongly support this disambiguation. Shopify has felt this pain at several points internally, both in explaining GraphQL to devs and in our actual code - you don't want to know how many distinct class Querys we have 😬 .

(edit: secondary 👍 to request, that's one in particular we've hit since historically we talked about "querying" our REST API).

[balshor]

This has been incredibly painful for me as well -- the ambiguity of this term has been particularly challenging with security and authorization, query registration and persistence, and similar cross-cutting and infrastructure concerns.

I already try to point people to the graphql spec to make these conversations more precise, so I'm very supportive of any efforts to disambiguate the word "query" in the spec itself.

[benjie]

Accepted to progress by the GraphQL WG. I'll be the champion for this and will be outlining steps forward over the coming weeks.

[StephenBarlow]

At Apollo we were recently discussing where to use "query" in docs and UI, and where to avoid it in favor of another word to avoid ambiguity. Some of the opinions behind our current strategy are:

• Because a "query" is a type of thing you can do, and a "mutation" is also a type of thing you can do, avoid calling "the things you can do" queries. Use operation instead
• In introductory docs, we call it "querying your graph" anyway, because it's faster and more intuitive to read than "executing operations on your graph", especially since this is a "query language"
• In docs where the assumption is the reader has cleared introductory hurdles, use "operation"
• Anywhere in UI that applies to more than one type of operation, use "operation"

[benjie]

Thanks for your input @StephenBarlow; this is in line with my thoughts. "Querying your graph" definitely sounds like the query (as opposed to mutation) side of things to me, and I think that's fine depending on context.

[benjie]

Have filed a PR for this via #777 and am adding it to the next GraphQL WG: https://github.com/graphql/graphql-wg/pull/497

(Sorry about the delay; it's been hectic. Took a day without internet to finally get around to this!)