Reuse a document for several reads
A client fetches different resources through one persisted or bundled document.
GraphQL · Function
separateOperations
Separate operations by defining multiple named GraphQL operations in one document, then selecting the desired operation at request time. This supports reusable documents and lets clients choose among queries, mutations, or subscriptions.
How it works
A GraphQL document may define multiple named operations. The client chooses the operation to execute by supplying its name separately from the document, while variables are supplied in a transport-specific dictionary.
Syntax
query OperationName($variable: Type) { field }Parameters
| Name | Type | Description |
|---|---|---|
document | GraphQL document | The GraphQL document containing one or more operations. |
operationName | string | The unique name of the operation to execute when the document contains multiple operations. |
variables | JSON object | Values for variables declared by the selected operation, supplied separately from the document. |
Returns
The response produced by executing the selected GraphQL operation.
Key points
- A document can hold different operation kinds, including queries, mutations, and subscriptions.
- Give each operation a unique name so clients and tooling can identify it.
- The operation type communicates the intended action to the GraphQL service.
Common mistakes
- When variables are used, the operation must include both an explicit operation type and a name.
Example: Selecting one operation
query GetUser($id: ID!) {
user(id: $id) {
id
name
}
}
query GetPost($id: ID!) {
post(id: $id) {
id
title
}
}A document can contain multiple named operations; the client selects which one to execute.
When to use it
Group alternative mutations
A client needs several related mutations but executes only one per request.
Improve observability
A development or tooling workflow wants named operations for tracing and debugging.
Interview questions
QHow do multiple operations work in one GraphQL document?
A GraphQL document can contain several operations, such as queries or mutations. Each operation needs a unique name, and the request identifies which named operation the server should execute.
Follow-up: What happens if the client omits the operation name? The server cannot unambiguously select an operation when the document contains multiple operations.
QWhat is the purpose of an operation type and name?
The operation type indicates whether the operation is a query, mutation, or subscription. When an operation has a name, the type keyword must also be present.
Follow-up: Can the type keyword be omitted? Only for the shorthand form of a single query operation; mutations and subscriptions always require it.
QHow are variables associated with a selected operation?
Variables are declared on a named operation and supplied separately from the GraphQL document, usually in a JSON variables object. This keeps dynamic values out of the query text.
Follow-up: Why must the operation be named when variables are used? The explicit operation definition provides the place where the variable declarations belong.
Related
querymutationsubscriptionoperation namevariablesaliases