GraphQL Operations Guide

This guide covers best practices for writing GraphQL operations (queries, mutations, subscriptions) as a client developer. Well-written operations are efficient, type-safe, and maintainable.

Start From the Schema

Write every operation against the project's schema, not against the examples in this guide.

1. Find the schema before you write anything. Check the schema entry in codegen.ts, graphql.config.*, or apollo.config.*, then look for *.graphql SDL files.
2. Use only the fields, arguments, and enum values that the schema defines. Field names in this guide, such as updatedAt or orderBy: { field: CREATED_AT, direction: DESC }, are illustrations.
3. Save the operation as a document next to the client's existing operations. Leave the server schema unchanged unless the user asks for a schema change.

Operation Basics

Query Structure