Skip to content
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.

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

The term "query" is overloaded and can be ambiguous #715

benjie opened this issue Apr 29, 2020 · 6 comments

The term "query" is overloaded and can be ambiguous #715

benjie opened this issue Apr 29, 2020 · 6 comments
💡 Proposal (RFC 1) RFC Stage 1 (See


Copy link

benjie commented Apr 29, 2020

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.

Copy link

eapache commented Apr 29, 2020

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).

Copy link

balshor commented Apr 29, 2020

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.

Copy link
Member Author

benjie commented May 7, 2020

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

@leebyron leebyron added the 💡 Proposal (RFC 1) RFC Stage 1 (See label May 7, 2020
Copy link

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"

Copy link
Member Author

benjie commented May 12, 2020

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.

Copy link
Member Author

benjie commented Sep 14, 2020

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
💡 Proposal (RFC 1) RFC Stage 1 (See
None yet

No branches or pull requests

5 participants