GraphQL Reference

type TypeName { field: Type }

Define a named object type with typed fields.

scalar CustomName

Built-in scalars: Int, Float, String, Boolean, ID. Define custom scalars for special formats.

enum EnumName { VALUE_A VALUE_B }

A set of allowed string values for a field.

input InputName { field: Type }

Special object type used exclusively for mutation and query arguments.

interface InterfaceName { field: Type }

Abstract type that concrete types must implement.

union UnionName = TypeA | TypeB

A type that can be one of several object types. Resolved with inline fragments.

field: Type!

The exclamation mark makes a field non-nullable — the server guarantees a value.

field: [Type] / [Type!]! / [Type]!

Square brackets denote a list. Combine with ! for null control on list and items.

query { field { subfield } }

Fetch data by selecting fields. The query keyword is optional for single operations.

query OperationName { ... }

Name your query for debugging and logging. Required when sending multiple operations.

field(arg: value)

Pass arguments to fields to filter or parameterise results.

alias: field(arg: value)

Rename a field in the response to avoid conflicts when querying the same field twice.

field { nested { deep } }

Traverse object relationships by nesting field selections.

field(first: N, after: cursor) { edges { node } pageInfo }

Relay-style cursor-based pagination for large datasets.

mutation { action(input: {}) { result } }

Write operations that create, update, or delete data.

mutation OperationName($var: Type!) { ... }

Named mutation with variables for reusable, parameterised writes.

mutation { updateEntity(id: ID!, input: {}) { ... } }

Modify an existing record by ID with partial input.

mutation { deleteEntity(id: ID!) { success } }

Remove a record and return confirmation.

mutation { a: action(...) { } b: action(...) { } }

Execute multiple mutations in a single request using aliases. They run sequentially.

optimisticResponse: { ... }

Client-side pattern: predict the mutation result to update the UI immediately before the server responds.

subscription { event { field } }

Real-time data pushed from the server over WebSocket.

subscription OpName($var: Type!) { ... }

Named subscription with variables for parameterised real-time streams.

subscription { event(filter: value) { ... } }

Server-side filtering so the client only receives relevant events.

type Subscription { event: Type }

Define subscription fields in the schema root.

field @skip(if: $condition)

Conditionally exclude a field when the Boolean variable is true.

field @include(if: $condition)

Conditionally include a field when the Boolean variable is true.

field: Type @deprecated(reason: "...")

Mark a field or enum value as deprecated in the schema.

directive @name(arg: Type) on FIELD_DEFINITION

Define custom schema directives for cross-cutting concerns like auth or caching.

scalar Name @specifiedBy(url: "...")

Link a custom scalar to its specification URL.

fragment Name on Type { fields }

Reusable field selection set — avoids repeating the same fields across queries.

... on Type { fields }

Select fields conditionally based on the concrete type (for unions and interfaces).

query($var: Type!) { field(arg: $var) }

Parameterise operations with typed variables — passed as a separate JSON object.

query($var: Type = defaultValue) { ... }

Provide a fallback value when the variable is not supplied.

fragment Name on Type { field(arg: $var) }

Fragments can reference variables defined in the operation that spreads them.

{ "errors": [{ "message": "..." }] }

GraphQL responses include an errors array alongside data — partial success is possible.

extensions: { code: "...", ... }

Custom error metadata — use the extensions field to add error codes and details.

union Result = Success | Error

Model errors as part of the schema using union return types instead of relying on the errors array.

{ __schema { types { name } } }

Introspect the entire schema — list all types, directives, and the query/mutation/subscription roots.

{ __type(name: "TypeName") { fields { name } } }

Introspect a single type — list its fields, arguments, and descriptions.

{ field { __typename } }

Meta-field available on every type — returns the concrete type name at runtime.

"""Description""" type Name { ... }

Add documentation strings to types, fields, and arguments — visible in GraphiQL/Playground.

@key(fields: "id") / extend type

Compose multiple GraphQL services into a single unified graph (Apollo Federation pattern).

extensions: { persistedQuery: { sha256Hash } }

Send a query hash instead of the full query string — reduces bandwidth and prevents arbitrary queries.