GraphQL Cheat Sheet
GraphQL reference with queries, mutations, subscriptions, fragments, variables, and pagination patterns. Copy-ready syntax.
Queries
| Command | Description | Example |
|---|---|---|
| Basic query to fetch data | query { users { name email } } | |
| Named query with variables | query GetUser($id: ID!) { user(id: $id) { name } } | |
| Field with arguments | { users(limit: 10, offset: 0) { name } } | |
| Alias a field name in response | { admin: user(role: ADMIN) { name } } | |
| Nested field selection | { user { posts { title comments { text } } } } | |
| Conditionally skip a field | name @skip(if: $brief) | |
| Conditionally include a field | email @include(if: $withEmail) |
Mutations
| Command | Description | Example |
|---|---|---|
| Basic mutation to modify data | mutation { createUser(name: "Alice") { id } } | |
| Mutation with input variables | mutation CreatePost($input: PostInput!) { createPost(input: $input) { id } } | |
| Input type definition | input CreateUserInput { name: String! email: String! } |
Subscriptions
| Command | Description | Example |
|---|---|---|
| Subscribe to real-time events | subscription { messageAdded { text sender } } | |
| Filtered subscription | subscription($chatId: ID!) { newMessage(chatId: $chatId) { text } } |
Types
| Command | Description | Example |
|---|---|---|
| Object type definition | type User { id: ID! name: String! email: String } | |
| Scalar types | name: String! age: Int score: Float | |
| Non-nullable type | id: ID! (cannot be null) | |
| List type | friends: [User!]! (non-null list of non-null users) | |
| Enumeration type | enum Role { ADMIN USER MODERATOR } | |
| Interface type | interface Node { id: ID! } type User implements Node { ... } | |
| Union type | union SearchResult = User | Post | Comment | |
| Custom scalar definition | scalar DateTime scalar JSON |
Fragments
| Command | Description | Example |
|---|---|---|
| Reusable field selection | fragment UserFields on User { id name email } | |
| Spread a fragment | { user(id: 1) { ...UserFields } } | |
| Inline fragment | ... on User { email } ... on Bot { apiKey } |
Schema
| Command | Description | Example |
|---|---|---|
| Schema definition | schema { query: Query mutation: Mutation } | |
| Extend an existing type | extend type Query { search(term: String!): [Result] } | |
| Custom directive definition | directive @auth(role: Role!) on FIELD_DEFINITION | |
| Mark field as deprecated | oldField: String @deprecated(reason: "Use newField") |
Operations
| Command | Description | Example |
|---|---|---|
| JSON request format | { "query": "query($id: ID!) { user(id: $id) { name } }", "variables": { "id": "1" } } | |
| Variable with default value | query GetUsers($limit: Int = 10) { users(limit: $limit) { name } } | |
| Single-line comment | # This query fetches all users | |
| Documentation string | """A registered user""" type User { ... } |
Pagination
| Command | Description | Example |
|---|---|---|
| Cursor-based pagination args | users(first: 10, after: "cursor123") { edges { node { name } } } | |
| Connection edge type | { edges { node { ...UserFields } cursor } pageInfo { hasNextPage } } | |
| Page info for pagination | pageInfo { hasNextPage hasPreviousPage startCursor endCursor } | |
| Offset-based pagination | users(limit: 20, offset: 40) { id name } |
Frequently asked questions
How is GraphQL different from REST?
REST uses multiple endpoints with fixed data shapes. GraphQL uses a single endpoint where clients specify exactly what data they need. This eliminates over-fetching and under-fetching, but requires more complex server-side implementation.
When should I use GraphQL vs REST?
Use GraphQL when you have complex, nested data relationships, multiple client types (web, mobile, IoT) needing different data shapes, or when over-fetching is a performance concern. REST is simpler for CRUD APIs with straightforward resource models.
What is the N+1 problem in GraphQL?
When resolving nested fields, a naive implementation makes one database query per parent item. For 100 users with posts, that's 1 query for users + 100 queries for posts = 101 queries. DataLoader solves this by batching those 100 post queries into 1.
How do I handle authentication in GraphQL?
Authentication is typically handled at the transport layer (HTTP headers with JWT/session tokens), not in GraphQL itself. Authorization (permissions) is handled in resolvers or with schema directives like @auth. Never expose auth logic in the schema definition.
What are the best GraphQL clients?
Apollo Client is the most feature-rich (caching, local state, devtools). urql is lighter and more flexible. Relay is Facebook's client optimized for large apps. For simple needs, plain fetch() with typed queries works fine.
How do I handle file uploads in GraphQL?
The GraphQL spec doesn't cover file uploads. Common approaches: use the graphql-upload library with multipart requests, upload to a presigned URL (S3) and pass the URL in a mutation, or handle uploads via a separate REST endpoint.
Go from reference to real skills
Cheat sheets are great for quick lookups. Our in-depth courses take you from the fundamentals to professional-level mastery.
Browse all courses