GraphQL Complete Guide 2026: Schema, Resolvers, Subscriptions, Apollo, Relay, and Security

A query language for APIs that allows clients to request exactly the data they need. Single endpoint, typed schema, client-specified queries. Eliminates over-fetching and under-fetching. Created by Facebook in 2012, open-sourced in 2015.

The type system that defines the API. Describes types, fields, relationships, queries, mutations, and subscriptions. Written in SDL (Schema Definition Language) or generated from code (code-first). The contract between client and server.

A read operation in GraphQL. Clients specify exactly which fields they need. Queries can be nested to fetch related data in a single request. Corresponds to GET in REST.

A write operation in GraphQL. Used for creating, updating, or deleting data. Returns the modified data. Corresponds to POST/PUT/DELETE in REST. Mutations execute sequentially (unlike queries which can be parallel).

A real-time operation in GraphQL. The client subscribes to events, and the server pushes updates when data changes. Typically uses WebSocket transport (graphql-ws protocol). Used for: chat, notifications, live dashboards.

A function that returns data for a field in the schema. Each field has a resolver. Resolvers can fetch from databases, APIs, caches, or compute values. The resolver chain traverses the query tree depth-first.

A named set of fields in the GraphQL schema. Object types define the shape of data. Scalar types (String, Int, Float, Boolean, ID) are leaf values. Enum types define allowed values. Input types define mutation arguments.

A reusable set of fields on a type. Reduces query duplication. Inline fragments for union/interface type narrowing. Relay uses fragments extensively for component data requirements.

An annotation on schema or query elements that modifies behavior. Built-in: @deprecated, @skip, @include. Custom: @auth, @cacheControl. Schema directives transform the schema at build time. Query directives modify execution.

A batching and caching utility that solves the N+1 query problem. Collects individual load calls within a single tick and batches them into one database query. Per-request caching prevents duplicate loads. Essential for GraphQL performance.

An architecture for composing multiple GraphQL services into a single supergraph. Each service (subgraph) owns part of the schema. The router combines them. Apollo Federation is the most popular implementation. Enables team-owned services.

A GraphQL feature that allows querying the schema itself. The __schema and __type queries return type information. Used by: GraphQL Playground, Apollo Studio, codegen tools. Should be disabled in production for security.

The most popular GraphQL client library. Features: normalized cache (InMemoryCache), local state management, optimistic updates, pagination, code generation. Supports React, Vue, Angular, and vanilla JS.

Facebook GraphQL client with a compiler. Fragment-driven: each component declares its data needs via fragments. Compiler optimizes queries, validates types, and generates flow/TypeScript types. Best for large React applications.

Pre-registered queries identified by hash. Client sends hash instead of full query string. Benefits: reduced bandwidth, query allowlisting (security), CDN caching. Automatic Persisted Queries (APQ) register on first use.

Combining multiple GraphQL schemas into one. The gateway delegates fields to source schemas. Simpler than federation but less scalable. Being replaced by Apollo Federation and GraphQL Mesh for most use cases.

Generating TypeScript types, hooks, and SDK from GraphQL schema and operations. Tools: GraphQL Code Generator, Relay Compiler. Ensures type safety between schema and client code. Run in CI to catch breaking changes.

Apollo Client stores query results as a flat map of objects by ID. Updating one object updates all queries referencing it. Requires __typename and id fields. Automatic cache updates for mutations returning modified objects.

A performance issue where a resolver makes one database query per item in a list. For 100 users with posts, that is 1 query for users + 100 queries for posts = 101 queries. Solution: DataLoader batches the 100 post queries into 1.

A special type used for mutation arguments. Cannot have resolvers or circular references (unlike object types). Keeps mutation signatures clean and reusable. Defined with the input keyword in SDL.

A type that can be one of several object types. Example: SearchResult = User | Post | Comment. Client uses inline fragments to query type-specific fields. Useful for polymorphic return types.

A type that defines a set of fields that implementing types must include. Example: interface Node { id: ID! }. Types implement interfaces: type User implements Node. Useful for shared field sets.

A leaf type that resolves to a concrete value. Built-in: String, Int, Float, Boolean, ID. Custom scalars: DateTime, JSON, URL, EmailAddress. Custom scalars need serialization/parsing functions.

A type restricted to a set of allowed values. Example: enum Role { ADMIN EDITOR VIEWER }. Provides type safety for fixed value sets. Enums are serialized as strings in JSON responses.

A unit of data in GraphQL. Each field has a name, type, optional arguments, and a resolver. Fields can be nullable (String) or non-nullable (String!). Lists use brackets ([String]). Fields compose the query tree.

Parameters passed to fields or directives. Defined in the schema: field(arg: Type). Used for: filtering (users(role: ADMIN)), pagination (posts(first: 10, after: cursor)), configuration. Always validated against the schema.

Renaming a field in the query result. Allows querying the same field with different arguments: { admin: user(id: 1) editor: user(id: 2) }. Aliases prevent field name conflicts in the response.

Dynamic values passed to a query separately from the query string. Defined with $ syntax: query GetUser($id: ID!) { user(id: $id) }. Variables are validated, prevent injection, and enable query caching.

Pagination using opaque cursors instead of offset/page numbers. Each item has a cursor; request next page with after: cursor. Consistent with concurrent writes. Relay Connection specification standardizes edges, nodes, and pageInfo.

A pagination specification: { edges { node { ...fields } cursor } pageInfo { hasNextPage endCursor } }. Standardized by Relay. Provides consistent pagination across all list fields. Supported by Apollo and most GraphQL clients.

GraphQL returns errors alongside data (partial responses). errors array with message, locations, path, and extensions. Custom error codes in extensions. Never throw HTTP errors for field-level issues. Use union types for typed errors: Result = Success | Error.

A directive that modifies schema behavior at build time. Example: @auth(requires: ADMIN) on a field enforces authorization. @cacheControl(maxAge: 3600) sets caching. Implemented as schema transformers in the server.

An optional name for a query/mutation/subscription. Required for: persisted queries, server logging, analytics, and debugging. Convention: PascalCase describing the operation: query GetUserProfile, mutation CreatePost.

GraphQL fields are nullable by default. Non-null: String! (guaranteed to have a value). List nullability: [String]! (list is non-null), [String!] (items are non-null), [String!]! (both). Non-null propagation: if a non-null field resolves to null, the parent becomes null.

Analyzing the query before execution to optimize database access. Look-ahead: inspect requested fields to select only needed columns. Join planning: determine which JOINs are needed. Tools: graphql-parse-resolve-info, Hasura query planner.

Sending multiple operations in a single HTTP request as an array. Reduces network round trips. Server processes all operations and returns an array of responses. Must be rate-limited to prevent abuse.

An alternative to subscriptions where the client queries and the server re-executes when data changes. Simpler model than subscriptions but more server load. Experimental in most implementations. Hasura supports live queries.

A central service that stores and versions GraphQL schemas. Tracks schema changes, validates compatibility, and prevents breaking changes. Apollo Studio, Hive. Essential for federated architectures with multiple subgraphs.

The specification for serving GraphQL over HTTP. POST with JSON body (query, variables, operationName). GET for persisted queries (query parameter). Response: { data, errors, extensions }. Content-Type: application/json.

Apollo Client configuration for how types are cached and merged. keyFields defines the cache key. merge function controls how incoming data merges with existing cache. read function customizes how cached data is read.