GraphQL Vocabulary

GraphQL operation types vocabulary:

Query
Fetches data. No server-side effects. Can be executed in parallel by the server.
• Transport: typically HTTP GET or POST
• Analogous to: REST GET
• Example: query { user(id: "1") { name, email } }

Mutation
Changes server state. Executed serially (mutations in a document are run one at a time).
• Transport: HTTP POST
• Analogous to: REST POST/PUT/PATCH/DELETE
• Example: mutation { createPost(input: {title: "Hello"}) { id, title } }
• Mutations should return the modified object so clients can update their cache

Subscription
Establishes a persistent connection for real-time push updates.
• Transport: WebSocket (most common), Server-Sent Events, or long polling
• Example: subscription { messageAdded(channelId: "42") { text, author { name } } }
• Use cases: chat messages, live scores, stock prices, CI/CD pipeline status
• Subscriptions require additional server infrastructure (subscriptions manager, pub/sub broker like Redis)

Vocabulary:
• operation — a named piece of GraphQL work (query / mutation / subscription)
• document — a GraphQL request body containing one or more operations
• operation name — optional name for a query, useful in logging and Apollo DevTools
• variable — parameterized input to an operation, sent separately from the query string
• persisted query — pre-stored query on the server identified by hash, reducing request payload size

GraphQL N+1 problem and DataLoader vocabulary:

Resolver
A function that fetches the data for one field in the GraphQL schema.
Each field in the type definition maps to a resolver (which can be explicit or inferred).

N+1 problem illustrated:

query { users { id, name, posts { title } } }

1. Resolver for users: SELECT * FROM users → returns 100 users
2. For each user (×100): SELECT * FROM posts WHERE user_id = ?
Total database queries: 1 + 100 = 101
Named "N+1" because 1 initial query triggers N subsequent queries.

DataLoader solution:
DataLoader (by Facebook, now Meta) defers and batches resolver calls using JavaScript's event loop:
1. In one event loop tick, 100 user resolvers call postLoader.load(userId) — not yet executing
2. Tick ends → DataLoader collects all queued IDs: [1, 2, 3, ..., 100]
3. Calls your batch function once: SELECT * FROM posts WHERE user_id IN (1,2,...,100) → 1 query
4. Distributes results back to the correct .load(id) promises

DataLoader also deduplicates:
If two fields both request userId=5, DataLoader only fetches it once (per-request in-memory cache).

Vocabulary:
• batch function — the function you write that receives an array of keys and returns an array of values
• N+1 query problem — a relational DB anti-pattern; also common in REST (loading related resources one at a time)
• eager loading — SQL JOIN or includes() to load related records in one query (ORM approach to solving N+1)
• per-request DataLoader — DataLoader instances must be created per request, not shared, to avoid cross-user data leaking
• cache — DataLoader's per-request in-memory memoization (not a distributed cache)

GraphQL non-null type modifier vocabulary:

Nullable vs. non-null in GraphQL:
By default, every GraphQL field is nullable — the server can return null for it.
Adding ! makes a field non-null: the server guarantees a value or returns a field-level error.

The four combinations for a String type:

String — nullable string. May be null or a string.
String! — non-null string. Always a string, never null.
[String] — nullable list. May be null, or a list that contains nulls: null, [], ["a", null, "b"]
[String!]! — non-null list of non-null strings. Always a list; elements are always strings: ["a", "b"]

Design implications:
• Prefer ! for fields you always return (id, createdAt, name)
• Nullable fields allow "unknown" or "not yet loaded" states
• Non-null increases frontend predictability (no null checks needed)
• If a non-null resolver returns null, GraphQL propagates the null error upward to the nearest nullable parent — potentially nulling out a large object in the response

Schema example:

type User {
  id: ID!          # always present
  name: String!    # always a string
  bio: String      # optional (can be null)
  roles: [Role!]!  # always a list; role objects not null
}

Vocabulary:
• input type — a special object type used for mutation arguments; uses the same ! modifier
• required input field — input field marked ! must be provided by the caller
• optional input field — nullable input field; can be omitted (treated as null)
• null propagation — when a non-null field returns null, GraphQL nulls the closest nullable parent field
• schema validation — GraphQL validates queries against the schema at parse time, before execution

GraphQL fragment vocabulary:

Named fragment
A reusable selection of fields, defined separately and applied with the spread syntax ...FragmentName.

Definition:

fragment UserCard on User {
  id
  name
  avatarUrl
  role
}

Usage:

query { user(id: "1") { ...UserCard } }

Benefits:
• DRY — define the fields once, reuse across queries
• Colocation in component frameworks (Relay, Apollo) — a component declares the fragment it needs
• Easier to add/remove fields from one place

Inline fragment
An anonymous fragment written directly in a selection set. Used primarily for unions and interfaces:

query {
  search(text: "error") {
    ... on User { name }
    ... on Post { title }
    ... on Comment { text }
  }
}

... on ConcreteType selects those fields only when the runtime object matches that type.
This is called type discrimination.

Inline fragments can also carry directives:
... @include(if: $isAdmin) { adminNote }

Vocabulary:
• union type — a type that can be one of several object types: union SearchResult = User | Post | Comment
• interface type — shared fields across types: inline fragment selects type-specific fields
• __typename — a meta-field that returns the object's type name at runtime; used for discriminated unions in clients
• fragment spread — the ...FragmentName syntax that includes a fragment
• Relay — Facebook's GraphQL client framework built on fragment-driven architecture
• fragment masking — hiding fragment data from parent components (encapsulation)

GraphQL schema-first vs code-first vocabulary:

Schema-first (SDL-first)
The team writes the GraphQL schema in SDL (Schema Definition Language) — .graphql files — before writing any code.

type User {
  id: ID!
  name: String!
  email: String!
}

Resolvers are then implemented to match this contract.

Advantages of schema-first:
• Schema serves as the API contract between frontend and backend teams
• Frontend can mock the API immediately using tools like Apollo MockedProvider or MSW
• Schema review in PRs is a clear documentation artifact
• Language-agnostic: works regardless of server language

Code-first (programmatic schema)
The developer writes server-side code; the SDL is generated from it automatically.

JavaScript/TypeScript examples:
• Pothos — type-safe TypeScript builder API; no SDL file needed
• TypeGraphQL — decorators on TypeScript classes generate the schema
• Nexus — programmatic schema builder

Python: Strawberry (type annotations → schema)
.NET: Hot Chocolate

Advantages of code-first:
• Schema and resolvers in one file: no risk of SDL/resolver mismatch
• Full type safety — TypeScript types flow directly into schema types
• IDE autocompletion and type checking for the schema itself

Vocabulary:
• SDL (Schema Definition Language) — GraphQL's declarative schema syntax; the .graphql file format
• type-safe resolvers — resolvers that TypeScript verifies match the schema types
• schema stitching — combining multiple GraphQL schemas into one (older approach)
• schema federation — Apollo Federation standard for composing schemas from microservices
• gateway — the entry point in a federated architecture that composes the supergraph
• supergraph — the composed schema from all subgraph services