liminfo

GraphQL Reference

Free reference guide: GraphQL Reference

25 results

About GraphQL Reference

The GraphQL Reference is a comprehensive, searchable guide to the GraphQL query language and server-side schema definition. It covers all six major areas of a GraphQL API: Schema (type, input, enum, interface, union), Query (basic queries, queries with variables, fragments, and field aliases), Mutation (create/update/delete mutations with and without variables), Subscription (real-time data via PubSub and subscription resolvers), Resolver (Query/Mutation/Field resolvers with context, plus DataLoader for N+1 batch loading), and Directive (@deprecated, @skip, @include, custom auth directives, and @cacheControl).

Full-stack developers, backend engineers, and API designers who work with GraphQL APIs — whether using Apollo Server, graphql-yoga, Hasura, or another implementation — will find this reference invaluable. Each schema definition entry shows the SDL (Schema Definition Language) syntax with concrete type examples. Each query entry shows the client-side request syntax. Resolver entries demonstrate the (parent, args, context) resolver signature and how to return data from a database context object, which is the standard pattern in Apollo Server and similar frameworks.

The reference pays special attention to real-world GraphQL patterns that go beyond basic CRUD: the fragment system for reusing field sets across multiple queries, field aliases for fetching the same field twice with different arguments, the DataLoader batching pattern for eliminating N+1 query problems in field resolvers, and custom schema directives for cross-cutting concerns like authentication and caching. Both the SDL schema syntax and the JavaScript resolver implementation syntax are covered for each concept.

Key Features

  • Schema Definition Language (SDL): object types, input types, enums, interfaces with implements, and union types for polymorphic search results
  • Query syntax: basic queries, named queries with variables ($id: ID!), fragment definitions (fragment UserFields on User), and field aliases (admin: user(id: "1"))
  • Mutation operations: create, update, and delete mutations, both inline and with $input variables, with selection sets on the returned type
  • Subscription syntax and server-side PubSub pattern for real-time data: asyncIterator-based subscription resolvers triggered by pubsub.publish()
  • Resolver implementation patterns: Query resolvers with context.db, Mutation resolvers with input destructuring, and field resolvers for relationship resolution
  • DataLoader pattern for batching and caching: solving the N+1 query problem by grouping per-request database lookups into a single batch query
  • Built-in directives: @deprecated with reason string, conditional @skip(if: $var) and @include(if: $var) for client-controlled field selection
  • Custom directives: schema-level @auth(requires: Role!) for field-level access control, and @cacheControl(maxAge: N) for HTTP caching headers

Frequently Asked Questions

What is the difference between a GraphQL query and a mutation?

A query is used for read operations (fetching data) and can be executed in parallel. A mutation is used for write operations (create, update, delete) and is executed serially to prevent race conditions. Both use the same field selection syntax, but mutations typically return the modified object so the client can update its cache.

What are GraphQL fragments and why should I use them?

A fragment is a reusable set of fields defined with "fragment FragmentName on TypeName { ... }". You spread a fragment into a query with "...FragmentName". Fragments eliminate duplication when the same fields are needed in multiple queries or across multiple places in one query, keeping your client code DRY.

How do GraphQL variables work?

Variables are declared in the query signature (e.g., query GetUser($id: ID!)) and passed separately as a JSON object (e.g., { "id": "1" }). They replace inline argument literals, making queries reusable and preventing injection attacks. The ! suffix on a type means the variable is required.

What is the N+1 problem in GraphQL and how does DataLoader solve it?

The N+1 problem occurs when a field resolver runs a separate database query for each item in a list — 1 query for the list and N queries for each item's field. DataLoader solves this by collecting all IDs requested during a single event loop tick and batching them into a single database query, dramatically reducing round trips.

What is the difference between @skip and @include directives?

@skip(if: $condition) omits the field when the condition is true. @include(if: $condition) includes the field only when the condition is true. They are logical inverses. Both accept a Boolean variable, allowing the client to dynamically control which fields are fetched without changing the query string.

How do GraphQL subscriptions work for real-time data?

A subscription establishes a long-lived WebSocket connection from the client to the server. On the server, a PubSub instance publishes events (pubsub.publish("TOPIC", data)) from a mutation resolver. The subscription resolver subscribes to that topic with pubsub.asyncIterator(["TOPIC"]) and streams each published event to the connected client.

What is a custom GraphQL directive and when should I use one?

A custom directive is a schema annotation (e.g., directive @auth(requires: Role!) on FIELD_DEFINITION) that intercepts field resolution to add cross-cutting behavior like authentication, authorization, input validation, or rate limiting. It keeps this logic out of individual resolvers and centralizes it as a reusable schema-level concern.

What is the GraphQL context object and how is it used in resolvers?

The context is a shared object passed to every resolver in a request, typically containing the database connection, authenticated user information, and service instances. In resolver signatures (parent, args, context, info), you access it as the third argument: context.db.users.findAll(), context.user.id, etc. It is set up once per request in the server's context function.