GraphQL Schema Design Patterns

TL;DR

• Bottom line: Design your GraphQL schema around client use cases and business domain, not database tables -- use Relay connections for pagination, input types for mutations, and interfaces/unions for polymorphism.
• Key tool/command: type ProductConnection { edges: [ProductEdge!]! pageInfo: PageInfo! } -- the Relay connection spec is the universal pagination pattern.
• Watch out for: N+1 queries -- every resolver that fetches related data without DataLoader batching will multiply your database round-trips by the list size.
• Works with: Any GraphQL server (Apollo Server 4.x, graphql-yoga 5.x, Strawberry 0.x, gqlgen 0.17+, Absinthe 1.7+).

Constraints

• NEVER expose database schema directly as your GraphQL schema -- design around client use cases, not table structures
• ALWAYS implement depth limiting and query complexity analysis on public-facing APIs to prevent denial-of-service via deeply nested queries
• ALWAYS use DataLoader or equivalent batching to solve N+1 query problems
• Mutation inputs MUST use dedicated Input types -- never reuse output types as mutation arguments
• Relay connection fields MUST return Connection types with edges/node/pageInfo -- never raw lists for paginated data
• Breaking schema changes (removing fields, changing types) require a deprecation period using @deprecated

Quick Reference

Decision Tree

START
|-- Single team or monolith?
|   |-- YES --> Use single GraphQL server (Apollo Server, graphql-yoga, Strawberry)
|   |   |-- Need pagination? --> Use Relay connection spec
|   |   |-- Need polymorphism? --> interfaces (shared fields) or unions (disjoint types)
|   |   |-- Need real-time? --> Add subscriptions (WebSocket) or @defer/@stream
|   |-- NO (multiple teams/services) |
|       |-- Teams own separate domains? --> Apollo Federation v2 with subgraphs
|       |-- Integrating legacy GraphQL APIs? --> Schema stitching (last resort)
|
|-- Schema-first or code-first?
|   |-- Team needs shared SDL review (design-first) --> Schema-first (SDL files + codegen)
|   |-- Developers prefer type-safe code --> Code-first (TypeGraphQL, Nexus, Strawberry)
|
|-- REST alongside GraphQL?
|   |-- YES --> GraphQL as BFF layer over REST microservices (Apollo RESTDataSource)
|   |-- NO (pure GraphQL) --> Direct database/service resolvers with DataLoader
|
|-- Relay client?
|   |-- YES --> MUST implement Node interface, connection spec, global IDs
|   |-- NO --> Connection spec still recommended for pagination; Node interface optional

Step-by-Step Guide

1. Define your domain entities as object types

Start with the core types your clients need. Use descriptive field names and include @deprecated for fields being phased out. [src2]

"""A product in the catalog."""
type Product implements Node {
  """Global Relay ID."""
  id: ID!
  """Human-readable unique handle."""
  handle: String!
  title: String!
  description: String
  price: Money!
  status: ProductStatus!
  createdAt: DateTime!
  updatedAt: DateTime!
  """Paginated list of product variants."""
  variants(first: Int, after: String): VariantConnection!
}

enum ProductStatus {
  ACTIVE
  DRAFT
  ARCHIVED
}

Verify: npx graphql-inspector validate schema.graphql -- should produce no errors.

2. Implement Relay connection pagination

For any list that can grow, use the connection spec: Connection, Edge, PageInfo. [src3]

type ProductConnection {
  edges: [ProductEdge!]!
  pageInfo: PageInfo!
  totalCount: Int
}

type ProductEdge {
  node: Product!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Verify: Query { products(first: 2) { pageInfo { hasNextPage endCursor } edges { cursor node { title } } } } returns valid cursors.

3. Design mutations with Input types and Payload types

Each mutation takes a single input argument and returns a payload with the result plus user-facing errors. [src4]

input CreateProductInput {
  title: String!
  description: String
  price: MoneyInput!
  status: ProductStatus = DRAFT
}

type CreateProductPayload {
  product: Product
  userErrors: [UserError!]!
}

type Mutation {
  createProduct(input: CreateProductInput!): CreateProductPayload!
}

Verify: Mutation with invalid input returns userErrors array, not a GraphQL error.

4. Add interfaces and unions for polymorphism

Use interfaces when types share common fields; use unions when types are disjoint. [src1]

interface Node {
  id: ID!
}

union SearchResult = Product | Article | Category

type Query {
  node(id: ID!): Node
  search(query: String!, first: Int): SearchResultConnection!
}

Verify: { __type(name: "SearchResult") { possibleTypes { name } } } returns all union members.

5. Implement DataLoader for batched resolution

Every resolver that fetches related data must use DataLoader to batch requests within a single tick. [src6]

import DataLoader from 'dataloader';

const createLoaders = () => ({
  productById: new DataLoader(async (ids) => {
    const products = await db.products.findByIds(ids);
    const map = new Map(products.map(p => [p.id, p]));
    return ids.map(id => map.get(id) || null);
  }),
});

const resolvers = {
  OrderItem: {
    product: (item, _, { loaders }) =>
      loaders.productById.load(item.productId),
  },
};

Verify: Enable query logging -- a list of 50 orders should produce 1 batch query, not 50.

6. Add query complexity and depth limiting

Protect your API from abusive queries by setting maximum depth and complexity budgets. [src1]

import depthLimit from 'graphql-depth-limit';
import { createComplexityRule, simpleEstimator, fieldExtensionsEstimator }
  from 'graphql-query-complexity';

const server = new ApolloServer({
  schema,
  validationRules: [
    depthLimit(10),
    createComplexityRule({
      maximumComplexity: 1000,
      estimators: [
        fieldExtensionsEstimator(),
        simpleEstimator({ defaultComplexity: 1 }),
      ],
    }),
  ],
});

Verify: A deeply nested query (11+ levels) is rejected with a depth-limit error.

Code Examples

Node.js / Apollo Server: Federation subgraph schema

# Input:  SDL file for Apollo Federation v2
# Output: Subgraph that composes into a supergraph

extend schema @link(url: "https://specs.apollo.dev/federation/v2.3",
  import: ["@key", "@shareable", "@external"])

type Product @key(fields: "id") {
  id: ID!
  title: String!
  price: Money!
  reviews(first: Int = 10, after: String): ReviewConnection!
}

type Money {
  amount: Int!       # cents
  currencyCode: String!
}

Python / Strawberry: Type-safe code-first schema

# Input:  Python classes defining GraphQL types
# Output: Executable schema with Relay pagination

import strawberry
from strawberry import relay

@strawberry.type
class Product(relay.Node):
    id: relay.NodeID[int]
    title: str
    price_cents: int

    @relay.connection(relay.ListConnection[Product])
    def variants(self, info) -> list["Product"]:
        return get_variants(self.id)

@strawberry.type
class Query:
    @relay.connection(relay.ListConnection[Product])
    def products(self, info, status: str | None = None) -> list[Product]:
        return get_products(status=status)

schema = strawberry.Schema(query=Query)

TypeScript / TypeGraphQL: Decorator-based code-first

// Input:  TypeScript classes with decorators
// Output: Executable schema with type safety

import { ObjectType, Field, ID, InputType, Mutation, Arg, Resolver }
  from "type-graphql";

@ObjectType()
class Product {
  @Field(() => ID)
  id!: string;

  @Field()
  title!: string;

  @Field({ deprecationReason: "Use priceV2 instead" })
  price!: number;

  @Field(() => Money)
  priceV2!: Money;
}

@InputType()
class CreateProductInput {
  @Field()
  title!: string;

  @Field({ nullable: true })
  description?: string;
}

@Resolver(Product)
class ProductResolver {
  @Mutation(() => Product)
  async createProduct(@Arg("input") input: CreateProductInput) {
    return await ProductService.create(input);
  }
}

Anti-Patterns

Wrong: Exposing database tables as GraphQL types

# BAD -- mirrors database schema, exposes internal column names
type products {
  product_id: Int!
  product_name: String
  category_fk: Int          # leaking foreign keys
  is_deleted: Boolean       # internal soft-delete flag
  created_at_utc: String    # raw DB column naming
}

Correct: Domain-driven type design

# GOOD -- models the business domain, hides implementation
type Product implements Node {
  id: ID!                   # opaque global ID
  title: String!            # domain language
  category: Category!       # resolved object, not FK
  createdAt: DateTime!      # custom scalar, consistent naming
  # is_deleted never exposed -- filter at resolver level
}

Wrong: Returning raw lists without pagination

# BAD -- unbounded list, no cursor, no page info
type Query {
  products: [Product!]!     # returns ALL products
  orderItems(orderId: ID!): [OrderItem!]!
}

Correct: Relay connection pagination

# GOOD -- bounded, cursor-based, with metadata
type Query {
  products(first: Int!, after: String): ProductConnection!
  orderItems(orderId: ID!, first: Int = 20, after: String): OrderItemConnection!
}

Wrong: Reusing output types as mutation inputs

# BAD -- output type used as input; id and computed fields cause confusion
type Mutation {
  updateProduct(product: Product!): Product!
}

Correct: Dedicated Input types per mutation

# GOOD -- separate input type with only writable fields
input UpdateProductInput {
  title: String
  description: String
  price: MoneyInput
}

type Mutation {
  updateProduct(id: ID!, input: UpdateProductInput!): UpdateProductPayload!
}

Wrong: No query depth or complexity limits

// BAD -- no protection against malicious deep queries
const server = new ApolloServer({ schema });
// attacker can send: { user { posts { comments { author { posts { ... } } } } } }

Correct: Depth limit + complexity analysis

// GOOD -- bounded depth and computed complexity budget
import depthLimit from 'graphql-depth-limit';
import { createComplexityRule } from 'graphql-query-complexity';

const server = new ApolloServer({
  schema,
  validationRules: [
    depthLimit(10),
    createComplexityRule({ maximumComplexity: 1000 }),
  ],
});

Common Pitfalls

• N+1 query explosion: Without DataLoader, resolving a list of 100 orders with order.product fires 100 separate DB queries. Fix: new DataLoader(ids => batchFetchProducts(ids)) and create loaders per-request. [src6]
• Schema-database coupling: Auto-generating schema from DB exposes internal structure and makes frontend changes require DB migrations. Fix: treat the schema as a separate API contract. [src4]
• Breaking changes without deprecation: Removing a field or changing its type breaks existing clients silently. Fix: add @deprecated(reason: "Use fieldV2"), monitor usage for 2+ months, then remove. [src1]
• Overly broad @shareable in federation: Marking all fields @shareable defeats ownership boundaries. Fix: only share fields that genuinely need multi-subgraph resolution. [src5]
• Cursor opacity violation: Using raw database IDs as cursors couples pagination to the database. Fix: base64-encode cursor payloads. [src3]
• Missing error handling in mutations: Returning GraphQL errors for validation failures mixes user errors with system errors. Fix: return userErrors array in the mutation payload type. [src4]
• Global DataLoader instances: Sharing a DataLoader across requests causes data leaks between users. Fix: create DataLoader instances per-request in the context factory. [src6]

Diagnostic Commands

# Introspect schema and save locally
npx graphql-inspector introspect http://localhost:4000/graphql > schema.graphql

# Validate schema against best practices
npx graphql-inspector validate schema.graphql

# Diff two schema versions for breaking changes
npx graphql-inspector diff old-schema.graphql new-schema.graphql

# Check query complexity of a specific operation
npx graphql-query-complexity-cli --schema schema.graphql --query query.graphql

# List all deprecated fields still in use (Apollo Studio)
rover graph check my-graph@prod --schema schema.graphql

# Test a connection query with curl
curl -X POST http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products(first:5) { pageInfo { hasNextPage endCursor } edges { node { id title } } } }"}'

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• @defer and @stream are still draft directives as of February 2026 -- server and client support varies; do not rely on them in production without verifying your toolchain supports incremental delivery.
• Apollo Federation v2 is not backward-compatible with v1 -- migrating subgraphs requires updating directives and testing composition; use rover subgraph check to validate before deploying.
• Query complexity analysis adds ~1-3ms per query -- for latency-critical APIs, consider static analysis at build time instead of runtime complexity checks.
• GraphQL subscriptions over WebSocket require sticky sessions or a pub/sub layer (Redis, NATS) in multi-instance deployments.
• The Relay connection spec is optional for non-Relay clients, but it is the de facto standard -- deviating creates friction with code generators and client libraries.