GraphQL Operation Names

An operation name is a label you give to a query, mutation, or subscription. It is optional in development but highly recommended in production. Operation names make your logs readable, your errors traceable, and your codebase maintainable.

Anonymous vs Named Operations

  Anonymous (shorthand) — development only:
  ──────────────────────────────────────────
  {
    products {
      name
    }
  }

  Named operation — production standard:
  ────────────────────────────────────────
  query GetAllProducts {
    products {
      name
    }
  }

Why Names Matter in Production

When something goes wrong in production, your server logs record the operation. Without a name, every failing query appears as an anonymous blob of text. With a name, you immediately see "GetCheckoutCart failed" and know exactly which feature to investigate.

  Server log without names:          Server log with names:
  ──────────────────────────         ──────────────────────
  ERROR: { products { name           ERROR: GetAllProducts
    price reviews { rating } } }       Duration: 4500ms
  Duration: 4500ms                     Error: DB timeout
  Error: DB timeout

  Which page broke? Unknown.         Which query broke? Obvious.

Naming Conventions

Use PascalCase for operation names. Start with a verb that describes the action, followed by the subject. This matches how most GraphQL teams name their operations.

  Operation type    Naming pattern       Examples
  ──────────────    ───────────────      ─────────────────────────
  query             Get + Subject        GetUser, GetOrderHistory
  query (list)      List + Subject       ListProducts, ListComments
  query (search)    Search + Subject     SearchMovies, SearchUsers
  mutation (create) Create + Subject     CreatePost, CreateAccount
  mutation (update) Update + Subject     UpdateProfile, UpdateCart
  mutation (delete) Delete + Subject     DeleteComment, DeleteFile
  subscription      On + Event           OnMessageReceived, OnOrderPlaced

Multiple Operations in One Document

A GraphQL document can contain multiple named operations. When you send the document to the server, you also send an operationName field to tell the server which one to execute.

  Document with two operations:
  ──────────────────────────────
  query GetUser($id: ID!) {
    user(id: $id) { name email }
  }

  query GetUserPosts($userId: ID!) {
    posts(userId: $userId) { title }
  }

  HTTP request body selects which one runs:
  ──────────────────────────────────────────
  {
    "query": "... both operations ...",
    "operationName": "GetUser",
    "variables": { "id": "u5" }
  }

This pattern is how code generators and GraphQL clients manage large collections of queries in a single file.

Operation Names in Client Code

Apollo Client and other GraphQL clients use the operation name to identify queries in their cache and dev tools. Naming your operations lets you see exactly which query populated which part of the UI in Apollo DevTools.

  // React + Apollo Client
  const GET_PROFILE = gql`
    query GetUserProfile($id: ID!) {
      user(id: $id) {
        name
        avatarUrl
        bio
      }
    }
  `;

  // Apollo DevTools shows: "GetUserProfile" in the cache explorer

Key Points

• Operation names are optional syntactically but essential for production code.
• Named operations make server logs, error reports, and client dev tools readable.
• Use PascalCase with a verb prefix: GetUser, CreateOrder, OnPaymentComplete.
• When a document contains multiple operations, the operationName field in the HTTP request selects which one runs.