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

DataLoader is specifically designed to mitigate the N+1 problem in GraphQL by fetching related data in bulk. Increasing the HTTP connection pool primarily addresses network latency, not GraphQL query efficiency. Adding Cache-Control headers would improve caching but doesn't address the root cause of a large response size. Returning fewer fields simply reduces the amount of data transferred, which is a good practice but doesn't solve performance issues stemming from deeply nested relationships.

Nested queries in GraphQL are designed to efficiently retrieve related data without making separate calls. They leverage the relationships defined within your schema (e.g., a user has many products, and each product belongs to a category) to fetch all necessary information with a single query. Options 1 and 2 describe different concepts; option 3 describes field selection, and option 4 relates to optimization techniques, but not the specific structure of a nested query itself.

Non-nullable in GraphQL schemas indicates that the `user` field *must* have a value assigned to it when a query is executed. This enforces data integrity and prevents unexpected errors or null values from propagating through your application. Options 1 correctly defines non-null; option 2 describes type constraints, option 3 describes how nullable fields are handled (and the opposite of what we're discussing), and option 4 focuses on performance optimization.

Schema-first development begins with defining the GraphQL schema—the structure of your data and available queries/mutations—before generating the underlying code. This approach ensures that the API accurately reflects the business requirements. Code-first starts with implementing the backend logic and then creating the schema to match, which can sometimes lead to inconsistencies or a less well-defined API.

The syntax [String!]! signifies that the `Product` field is a non-nullable (cannot be null) string type. The ! indicates a *non-null* constraint, and String defines its data type. This ensures that this field always has a valid string value when queried.