GraphQL Schema Design Anti-Patterns

Poorly designed GraphQL schemas lead to N+1 queries, over-fetching, and breaking changes that are hard to evolve.

Avoid these common schema mistakes:

1. Exposing database structure directly

# BAD: mirrors DB tables
type User {
  id: ID!
  address_id: Int  # Exposes FK
}

# GOOD: domain-focused
type User {
  id: ID!
  address: Address  # Resolved relationship
}

1. Missing pagination on lists

# BAD: unbounded
type Query {
  users: [User!]!
}

# GOOD: cursor-based pagination
type Query {
  users(first: Int!, after: String): UserConnection!
}
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

1. Missing input validation types

# Use input types for mutations
input CreateUserInput {
  name: String!
  email: String!
}
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

1. Use DataLoader for N+1

const userLoader = new DataLoader(ids =>
  db.users.findMany({ where: { id: { in: ids } } })
);
// Batches all user lookups in a single tick into one query

GraphQL gives clients flexibility to query what they need, but that flexibility means schema design errors are amplified. A bad schema forces inefficient queries.

Designing GraphQL APIs