graphql / graphql/graphql-spec
The term "query" is overloaded and can be ambiguous
- Dominant language
- JavaScript
- Stars
- 14.6k
- Forks
- 1.2k
- PR merge metrics
- No merged PRs in 30d
Description
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.
Contributor guide
Assessment
This issue has not been assessed yet.