1# GraphQL Schema Design Patterns
2 
3## Schema Organization
4 
5### Modular Schema Structure
6 
7```graphql
8# user.graphql
9type User {
10  id: ID!
11  email: String!
12  name: String!
13  posts: [Post!]!
14}
15 
16extend type Query {
17  user(id: ID!): User
18  users(first: Int, after: String): UserConnection!
19}
20 
21extend type Mutation {
22  createUser(input: CreateUserInput!): CreateUserPayload!
23}
24 
25# post.graphql
26type Post {
27  id: ID!
28  title: String!
29  content: String!
30  author: User!
31}
32 
33extend type Query {
34  post(id: ID!): Post
35}
36```
37 
38## Type Design Patterns
39 
40### 1. Non-Null Types
41 
42```graphql
43type User {
44  id: ID! # Always required
45  email: String! # Required
46  phone: String # Optional (nullable)
47  posts: [Post!]! # Non-null array of non-null posts
48  tags: [String!] # Nullable array of non-null strings
49}
50```
51 
52### 2. Interfaces for Polymorphism
53 
54```graphql
55interface Node {
56  id: ID!
57  createdAt: DateTime!
58}
59 
60type User implements Node {
61  id: ID!
62  createdAt: DateTime!
63  email: String!
64}
65 
66type Post implements Node {
67  id: ID!
68  createdAt: DateTime!
69  title: String!
70}
71 
72type Query {
73  node(id: ID!): Node
74}
75```
76 
77### 3. Unions for Heterogeneous Results
78 
79```graphql
80union SearchResult = User | Post | Comment
81 
82type Query {
83  search(query: String!): [SearchResult!]!
84}
85 
86# Query example
87{
88  search(query: "graphql") {
89    ... on User {
90      name
91      email
92    }
93    ... on Post {
94      title
95      content
96    }
97    ... on Comment {
98      text
99      author {
100        name
101      }
102    }
103  }
104}
105```
106 
107### 4. Input Types
108 
109```graphql
110input CreateUserInput {
111  email: String!
112  name: String!
113  password: String!
114  profileInput: ProfileInput
115}
116 
117input ProfileInput {
118  bio: String
119  avatar: String
120  website: String
121}
122 
123input UpdateUserInput {
124  id: ID!
125  email: String
126  name: String
127  profileInput: ProfileInput
128}
129```
130 
131## Pagination Patterns
132 
133### Relay Cursor Pagination (Recommended)
134 
135```graphql
136type UserConnection {
137  edges: [UserEdge!]!
138  pageInfo: PageInfo!
139  totalCount: Int!
140}
141 
142type UserEdge {
143  node: User!
144  cursor: String!
145}
146 
147type PageInfo {
148  hasNextPage: Boolean!
149  hasPreviousPage: Boolean!
150  startCursor: String
151  endCursor: String
152}
153 
154type Query {
155  users(first: Int, after: String, last: Int, before: String): UserConnection!
156}
157 
158# Usage
159{
160  users(first: 10, after: "cursor123") {
161    edges {
162      cursor
163      node {
164        id
165        name
166      }
167    }
168    pageInfo {
169      hasNextPage
170      endCursor
171    }
172  }
173}
174```
175 
176### Offset Pagination (Simpler)
177 
178```graphql
179type UserList {
180  items: [User!]!
181  total: Int!
182  page: Int!
183  pageSize: Int!
184}
185 
186type Query {
187  users(page: Int = 1, pageSize: Int = 20): UserList!
188}
189```
190 
191## Mutation Design Patterns
192 
193### 1. Input/Payload Pattern
194 
195```graphql
196input CreatePostInput {
197  title: String!
198  content: String!
199  tags: [String!]
200}
201 
202type CreatePostPayload {
203  post: Post
204  errors: [Error!]
205  success: Boolean!
206}
207 
208type Error {
209  field: String
210  message: String!
211  code: String!
212}
213 
214type Mutation {
215  createPost(input: CreatePostInput!): CreatePostPayload!
216}
217```
218 
219### 2. Optimistic Response Support
220 
221```graphql
222type UpdateUserPayload {
223  user: User
224  clientMutationId: String
225  errors: [Error!]
226}
227 
228input UpdateUserInput {
229  id: ID!
230  name: String
231  clientMutationId: String
232}
233 
234type Mutation {
235  updateUser(input: UpdateUserInput!): UpdateUserPayload!
236}
237```
238 
239### 3. Batch Mutations
240 
241```graphql
242input BatchCreateUserInput {
243  users: [CreateUserInput!]!
244}
245 
246type BatchCreateUserPayload {
247  results: [CreateUserResult!]!
248  successCount: Int!
249  errorCount: Int!
250}
251 
252type CreateUserResult {
253  user: User
254  errors: [Error!]
255  index: Int!
256}
257 
258type Mutation {
259  batchCreateUsers(input: BatchCreateUserInput!): BatchCreateUserPayload!
260}
261```
262 
263## Field Design
264 
265### Arguments and Filtering
266 
267```graphql
268type Query {
269  posts(
270    # Pagination
271    first: Int = 20
272    after: String
273 
274    # Filtering
275    status: PostStatus
276    authorId: ID
277    tag: String
278 
279    # Sorting
280    orderBy: PostOrderBy = CREATED_AT
281    orderDirection: OrderDirection = DESC
282 
283    # Searching
284    search: String
285  ): PostConnection!
286}
287 
288enum PostStatus {
289  DRAFT
290  PUBLISHED
291  ARCHIVED
292}
293 
294enum PostOrderBy {
295  CREATED_AT
296  UPDATED_AT
297  TITLE
298}
299 
300enum OrderDirection {
301  ASC
302  DESC
303}
304```
305 
306### Computed Fields
307 
308```graphql
309type User {
310  firstName: String!
311  lastName: String!
312  fullName: String! # Computed in resolver
313  posts: [Post!]!
314  postCount: Int! # Computed, doesn't load all posts
315}
316 
317type Post {
318  likeCount: Int!
319  commentCount: Int!
320  isLikedByViewer: Boolean! # Context-dependent
321}
322```
323 
324## Subscriptions
325 
326```graphql
327type Subscription {
328  postAdded: Post!
329 
330  postUpdated(postId: ID!): Post!
331 
332  userStatusChanged(userId: ID!): UserStatus!
333}
334 
335type UserStatus {
336  userId: ID!
337  online: Boolean!
338  lastSeen: DateTime!
339}
340 
341# Client usage
342subscription {
343  postAdded {
344    id
345    title
346    author {
347      name
348    }
349  }
350}
351```
352 
353## Custom Scalars
354 
355```graphql
356scalar DateTime
357scalar Email
358scalar URL
359scalar JSON
360scalar Money
361 
362type User {
363  email: Email!
364  website: URL
365  createdAt: DateTime!
366  metadata: JSON
367}
368 
369type Product {
370  price: Money!
371}
372```
373 
374## Directives
375 
376### Built-in Directives
377 
378```graphql
379type User {
380  name: String!
381  email: String! @deprecated(reason: "Use emails field instead")
382  emails: [String!]!
383 
384  # Conditional inclusion
385  privateData: PrivateData @include(if: $isOwner)
386}
387 
388# Query
389query GetUser($isOwner: Boolean!) {
390  user(id: "123") {
391    name
392    privateData @include(if: $isOwner) {
393      ssn
394    }
395  }
396}
397```
398 
399### Custom Directives
400 
401```graphql
402directive @auth(requires: Role = USER) on FIELD_DEFINITION
403 
404enum Role {
405  USER
406  ADMIN
407  MODERATOR
408}
409 
410type Mutation {
411  deleteUser(id: ID!): Boolean! @auth(requires: ADMIN)
412  updateProfile(input: ProfileInput!): User! @auth
413}
414```
415 
416## Error Handling
417 
418### Union Error Pattern
419 
420```graphql
421type User {
422  id: ID!
423  email: String!
424}
425 
426type ValidationError {
427  field: String!
428  message: String!
429}
430 
431type NotFoundError {
432  message: String!
433  resourceType: String!
434  resourceId: ID!
435}
436 
437type AuthorizationError {
438  message: String!
439}
440 
441union UserResult = User | ValidationError | NotFoundError | AuthorizationError
442 
443type Query {
444  user(id: ID!): UserResult!
445}
446 
447# Usage
448{
449  user(id: "123") {
450    ... on User {
451      id
452      email
453    }
454    ... on NotFoundError {
455      message
456      resourceType
457    }
458    ... on AuthorizationError {
459      message
460    }
461  }
462}
463```
464 
465### Errors in Payload
466 
467```graphql
468type CreateUserPayload {
469  user: User
470  errors: [Error!]
471  success: Boolean!
472}
473 
474type Error {
475  field: String
476  message: String!
477  code: ErrorCode!
478}
479 
480enum ErrorCode {
481  VALIDATION_ERROR
482  UNAUTHORIZED
483  NOT_FOUND
484  INTERNAL_ERROR
485}
486```
487 
488## N+1 Query Problem Solutions
489 
490### DataLoader Pattern
491 
492```python
493from aiodataloader import DataLoader
494 
495class PostLoader(DataLoader):
496    async def batch_load_fn(self, post_ids):
497        posts = await db.posts.find({"id": {"$in": post_ids}})
498        post_map = {post["id"]: post for post in posts}
499        return [post_map.get(pid) for pid in post_ids]
500 
501# Resolver
502@user_type.field("posts")
503async def resolve_posts(user, info):
504    loader = info.context["loaders"]["post"]
505    return await loader.load_many(user["post_ids"])
506```
507 
508### Query Depth Limiting
509 
510```python
511from graphql import GraphQLError
512 
513def depth_limit_validator(max_depth: int):
514    def validate(context, node, ancestors):
515        depth = len(ancestors)
516        if depth > max_depth:
517            raise GraphQLError(
518                f"Query depth {depth} exceeds maximum {max_depth}"
519            )
520    return validate
521```
522 
523### Query Complexity Analysis
524 
525```python
526def complexity_limit_validator(max_complexity: int):
527    def calculate_complexity(node):
528        # Each field = 1, lists multiply
529        complexity = 1
530        if is_list_field(node):
531            complexity *= get_list_size_arg(node)
532        return complexity
533 
534    return validate_complexity
535```
536 
537## Schema Versioning
538 
539### Field Deprecation
540 
541```graphql
542type User {
543  name: String! @deprecated(reason: "Use firstName and lastName")
544  firstName: String!
545  lastName: String!
546}
547```
548 
549### Schema Evolution
550 
551```graphql
552# v1 - Initial
553type User {
554  name: String!
555}
556 
557# v2 - Add optional field (backward compatible)
558type User {
559  name: String!
560  email: String
561}
562 
563# v3 - Deprecate and add new field
564type User {
565  name: String! @deprecated(reason: "Use firstName/lastName")
566  firstName: String!
567  lastName: String!
568  email: String
569}
570```
571 
572## Best Practices Summary
573 
5741. **Nullable vs Non-Null**: Start nullable, make non-null when guaranteed
5752. **Input Types**: Always use input types for mutations
5763. **Payload Pattern**: Return errors in mutation payloads
5774. **Pagination**: Use cursor-based for infinite scroll, offset for simple cases
5785. **Naming**: Use camelCase for fields, PascalCase for types
5796. **Deprecation**: Use `@deprecated` instead of removing fields
5807. **DataLoaders**: Always use for relationships to prevent N+1
5818. **Complexity Limits**: Protect against expensive queries
5829. **Custom Scalars**: Use for domain-specific types (Email, DateTime)
58310. **Documentation**: Document all fields with descriptions
584