Writing GraphQL operations

This chapter follows Input types and arguments.

A GraphQL document can contain multiple operations, each with a type (query, mutation, or subscription) and optional name. Named operations improve logs, persisted-query registries, and Apollo Studio traces. Anonymous documents are allowed when exactly one operation is present.

Queries and selection sets

A query read operation uses a selection set { ... } to list fields:

1
query UserProfile($id: ID!) {
2
  user(id: $id) {
3
    name
4
    posts(first: 5) {
5
      title
6
    }
7
  }
8
}

Variables ($id) are typed and passed in a separate JSON object alongside the document. All variables must be scalars, enums, or input objects.

Mutations

Mutations change server-side state. Top-level mutation fields execute in order, unlike query fields:

1
mutation ArchivePost($id: ID!) {
2
  archivePost(id: $id) {
3
    id
4
    archivedAt
5
  }
6
}

Return fields from the mutation payload so clients update UI without a follow-up query—a common schema design guideline covered in the servers chapter.

Subscriptions

Subscriptions maintain a channel (typically WebSocket with the graphql-transport-ws protocol) for server-pushed updates:

1
subscription OnCommentAdded($postId: ID!) {
2
  commentAdded(postId: $postId) {
3
    id
4
    body
5
  }
6
}

Clients must handle reconnect, auth on connection_init, and backpressure; subscriptions share authorization concerns with queries but add long-lived connection state.

Variables and operation names

Production documents should name operations and declare variables explicitly:

1
query OrderList($status: OrderStatus) {
2
  orders(status: $status) { id total }
3
}

1
{ "status": "PENDING" }

Hard-coded literals in queries make codegen and persisted-query hashes harder to reuse across environments.

Aliases and fragments

Aliases rename fields in the response:

1
query Compare {
2
  draft: post(id: "1") { title }
3
  published: post(id: "2") { title }
4
}

Fragments reuse field sets on a type:

1
fragment PostSummary on Post {
2
  id
3
  title
4
}
5

6
query Feed {
7
  posts { ...PostSummary }
8
}

Fragment names must match the type in on Post. Variables used inside fragments inherit from the enclosing operation.

Inline fragments and directives

For interfaces and unions, inline fragments select type-specific fields:

1
search(text: "graph") {
2
  __typename
3
  ... on Book { title }
4
  ... on Author { name }
5
}

Directives @include(if: $flag) and @skip(if: $flag) conditionally include fields based on variables—handy for feature flags without duplicating entire operations.

Sending operations over HTTP

Most clients POST JSON { "query", "variables", "operationName" }. Some gateways allow GET with a query parameter for cache-friendly reads; mutations should stay on POST. The servers and security chapters discuss CSRF implications of GET.

Next: Resolvers and execution.