GraphQL Cheat Sheet
A searchable reference of GraphQL schema, query, and directive syntax and what each part means.
| Syntax | What it does |
|---|---|
type User { id: ID! } | Define an object type with named fields that clients can request. |
type Query { me: User } | The root read type; every top-level field here is an entry point for a query. |
type Mutation { addUser(name: String!): User } | The root write type; each field changes data and returns a result. |
type Subscription { messageAdded: Message } | The root type for real-time updates a client subscribes to over a stream. |
schema { query: Query mutation: Mutation } | The schema block names which types act as the query, mutation, and subscription roots. |
Int | Built-in scalar for a signed 32-bit integer. |
Float | Built-in scalar for a signed double-precision floating-point value. |
String | Built-in scalar for a UTF-8 character sequence. |
Boolean | Built-in scalar for a true or false value. |
ID | Built-in scalar for a unique identifier, serialized as a string. |
scalar DateTime | Declare a custom scalar whose parsing and serialization the server defines. |
name: String | A field definition pairs a field name with the type it returns. |
name: String! | The trailing bang marks the field non-null, so the server must return a value. |
[String] | Square brackets denote a list; this field returns an array of the inner type. |
[String!]! | A non-null list of non-null items; both the list and each item must be present. |
enum Role { ADMIN USER } | Define an enum type that restricts a field to a fixed set of named values. |
interface Node { id: ID! } | Define an interface of fields that any implementing object type must include. |
union Result = User | Post | Define a union so a field can return any one of the listed object types. |
input UserInput { name: String! } | Define an input object type used to pass structured arguments into a field. |
type User implements Node { id: ID! } | Declare that an object type implements an interface and supplies its fields. |
type User implements A & B | A type can implement several interfaces by joining them with an ampersand. |
extend type Query { ping: String } | Add fields to an existing type, often to split a schema across modules. |
query { me { name } } | Read data by selecting fields; an anonymous query is the default operation. |
query GetUser { user { name } } | Give a query a name for clearer logging, caching, and debugging. |
mutation { addUser(name: "Ada") { id } } | Change data on the server and select fields from the returned result. |
subscription { messageAdded { text } } | Open a long-lived stream that pushes data whenever the event fires. |
{ id name email } | A selection set: the braces list exactly which sub-fields to return. |
user { posts { title } } | Select fields on related objects by nesting one selection set inside another. |
query Get($id: ID!) { user(id: $id) { name } } | Declare typed variables on the operation and reference them inside it. |
mutation Add($n: String!) { addUser(name: $n) { id } } | Pass a variable into a mutation instead of hardcoding the value. |
user(id: 42) { name } | Pass arguments in parentheses to parameterize what a field returns. |
$id | A dollar sign marks a variable whose value the client supplies at run time. |
field(key: $value) | Supply an argument by binding it to a declared variable or a literal. |
query ($limit: Int = 10) | Give a variable a default value so the client can omit it. |
addUser(input: { name: "Ada" }) | Pass a structured argument that matches an input object type. |
search(tags: ["a", "b"]) | Arguments can be lists, written with square brackets. |
admin: user(id: 1) { name } | An alias renames a field in the response so you can request it more than once. |
fragment Fields on User { id name } | Define a reusable named set of fields on a type to avoid repetition. |
...Fields | Insert a named fragment into a selection set with the spread operator. |
... on User { name } | An inline fragment selects fields that apply only when the result is that type. |
@include(if: $flag) | Include a field only when the boolean argument is true. |
@skip(if: $flag) | Skip a field when the boolean argument is true. |
__typename | A meta-field returning the concrete type name, useful with unions and interfaces. |
@deprecated(reason: "use x") | Mark a field or enum value as deprecated with an optional reason. |
resolver function | A function that returns the value for one field; the server calls one per field. |
parent (root) | First resolver argument: the value returned by the parent field. |
args | Second resolver argument: the arguments passed to the field. |
context | Third resolver argument: shared per-request data such as the current user or loaders. |
info | Fourth resolver argument: details about the query and current execution state. |
N+1 problem | Resolving a list and then one query per item causes many redundant round trips. |
DataLoader | A batching and caching helper that collapses many per-item loads into one query. |
No syntax matches your search.
Runs entirely in your browser. Nothing you type is sent anywhere; open DevTools and watch the Network tab to verify zero requests.
What this tool does
This is a searchable quick reference for GraphQL syntax, covering the schema language you use to define types and the query language clients use to fetch data. Each row pairs a small piece of syntax with a plain-English note on what it does, grouped into schema, types, operations, arguments, features, and resolvers. Type in the filter box to search across both columns, or tap a category button to focus on one area. The whole list is built into the page, so it works offline and sends nothing anywhere.
How to use it
Start typing in the Filter box. Entering non-null
jumps to the fields about the bang; entering fragment surfaces reuse
and inline fragments; entering directive shows include, skip, and
deprecated. The category buttons (Schema, Types, Operations,
Arguments, Features, Resolvers) narrow the table to one area and combine with the
text filter, so you can pick Operations and type subscription to zero
in on streaming. Clear the box to see the full sheet again.
Common use cases
- Recalling exactly where the bang goes in a non-null list type like
[String!]!. - Copying accurate schema syntax when defining a new
typeorinput. - Remembering how to declare and pass operation variables such as
$id. - Explaining the difference between an interface and a union to a teammate.
- Reviewing core GraphQL syntax before an interview or a new project.
Common pitfalls
- Putting the bang in the wrong place on a list. A list has two
non-null positions.
[String!]!is a non-null list of non-null strings, while[String]!allows null items inside a list that must itself be present. Decide each position on its own. - Treating a mutation like a query. Only mutation fields are guaranteed to run in series; top-level query fields may resolve in parallel. Put writes in a mutation and do not rely on ordering side effects inside a single query.
- Forgetting
__typenameon unions. A union has no shared fields, so you select inside inline fragments and usually request__typenameto tell the members apart. Leaving it out makes the response hard to branch on. - Ignoring the N+1 problem. Each field resolves on its own, so a list
resolver that fetches per item can fire many queries. Batch with a loader such as
DataLoaderto collapse them into one.
Frequently asked questions
- What is the difference between a query and a mutation?
- A query reads data and should not change anything on the server, so multiple queries can run in parallel. A mutation is meant to change data, such as creating or updating a record, and the top-level fields of a mutation run one after another in order. Both return a selection set, so a mutation can hand back the updated object in the same round trip.
- What does the exclamation mark mean in GraphQL?
- A trailing exclamation mark, often called a bang, marks a type as non-null. On a field it promises the server will always return a value rather than null; on an argument or variable it means the caller must supply a value. Applied to a list, the position of the bang tells you whether the list itself, its items, or both are non-null.
- What is a fragment in GraphQL?
- A fragment is a named, reusable set of fields defined on a specific type. You define it once and then spread it into any query that needs the same fields, which keeps large queries readable and consistent. An inline fragment is an unnamed variant used to select fields that apply only when a result is a particular type, which is common with interfaces and unions.
- What is the N+1 problem in GraphQL?
- The N+1 problem happens when resolving a list of N items triggers one extra data fetch per item, so a single request fans out into N plus one queries against your database. It is easy to hit because each field resolves independently. The usual fix is a batching layer such as DataLoader, which collects the individual loads within a tick and resolves them with one batched query.
- What is the difference between an interface and a union?
- An interface is a set of shared fields that several object types agree to implement, so any type behind the interface is guaranteed to expose those fields. A union simply lists a group of object types with no shared fields at all, so a union field can be any one of them but promises nothing in common. With a union you almost always select fields inside inline fragments and read __typename to tell the members apart.
- Does this cheat sheet send my searches anywhere?
- No. The entire syntax list is baked into the page at build time and every filter runs locally in your browser with JavaScript, so nothing you type is sent to any server. Open your browser DevTools and watch the Network tab while you search to confirm there are zero requests.
Cite this tool
For academic, journalistic, or technical references. Pick a format:
Citations use 2026 as the publication year. Access date is left as a fillable placeholder where the citation style expects one.