Anatomy of a GraphQL Operation

One Document, Three Operation Types

A GraphQL document is not the same thing as a query. The document is the text you send; it can hold several operations plus shared fragments, and the request picks which operation to run.

query GetCart($userId: ID!) {
  cart(userId: $userId) {
    itemCount
    items {
      ...LineItem
    }
  }
}

mutation AddItem($sku: String!, $qty: Int!) {
  addItem(sku: $sku, quantity: $qty) {
    ...LineItem
  }
}

subscription StockChanged($sku: String!) {
  stockChanged(sku: $sku) {
    ...LineItem
  }
}

fragment LineItem on CartItem {
  sku
  title
  unitPriceCents
  quantity
}

Three operation types, three behaviors at execution:

An operation can be anonymous (the query keyword with no name, or the bare { field } shorthand) only when the document contains exactly one operation. Two anonymous operations in one document are a validation error, not a style choice.

Names earn their keep in three places. With multiple operations in one document, the request carries operationName to pick one. Names show up in server logs, APM traces, and error reports, so GetCartFailed tells you more than query17. And persisted-query registries key operations by name and hash, see query variables for how the values arrive at execution.

Braces delimit every selection set: the operation's set, and each object-typed field's set nested inside it. The rule that trips people up is that an object type must always be followed by a selection set, while a scalar or enum field must never be followed by one.

Anatomy of a Selection Set

A selection set is a list of entries, and there are only a few kinds of entry. Reading a query well means recognizing each one on sight.

query ProductPage($id: ID!, $withReviews: Boolean!) {
  product(id: $id) {
    id
    title
    small: thumbnail(size: 64)
    thumbnail(size: 256)
    ...PriceBlock
    reviews(first: 5) @include(if: $withReviews) {
      rating
      body
    }
  }
}

fragment PriceBlock on Product {
  priceCents
  currency
}

Line by line:

• id is a plain field. The response key is the field name.
• small: thumbnail(size: 64) is an aliased field. The response key becomes small, which lets one document request two shapes of the same field without a collision. The second thumbnail call appears under its own name.
• ...PriceBlock is a fragment spread: the named fragment's selection set is pasted in at that position. Fragments are how shared shapes avoid being copy-pasted into every document.
• reviews(...) @include(if: $withReviews) carries arguments and a directive. Arguments configure the field; @include/@skip decide at runtime whether the entry is part of the operation at all.
• Nested braces under product repeat the pattern: object fields recurse, leaf fields stop.

Two practical consequences follow. First, the response object keys are aliases when present and field names otherwise, which is why aliases are also how you request the same field twice with different arguments. Second, fragments can carry a type condition (on CartItem), which is how a document selects fields that only exist on one variant of a union or interface; see inline fragments for that pattern.

Literals are legal in a document, but every value that varies by user or request belongs in a variable. A query with id: "42" baked in cannot be cached, cannot be reused, and ends up as a string-interpolation hole in the client.

Four Phases Between Text and Data

The document you send passes through a fixed pipeline, and every error you will ever see belongs to exactly one stage of it.

The order is the whole point. Validation compares the document to the schema before any resolver runs, so a typo in a field name can never reach the database. That is the practical payoff of putting types on the server: invalid operations are rejected structurally, not by whatever defensive code each resolver happens to carry.

Each stage also produces a different-shaped failure, which is why HTTP transport details can map them to status codes: parse and validation failures stop the request before execution, while execution failures travel inside a successful response alongside partial data.

Two validation rules are worth memorizing because they look like runtime bugs:

1. Fields must be mergeable. Selecting the same field twice with different arguments or different sub-selections in one scope is a validation error, not a silent overwrite.
2. Leaf and composite fields are exclusive. A scalar field with a sub-selection fails validation; an object field without one fails validation.

Interview questions in this area are almost always phrased as debugging stories: "the client sends a query and nothing reaches your resolver, what do you check?" Walk the four phases in order and the answer writes itself.