Skip to content

GraphQL Hoja de referencia

Lenguaje de consultas y runtime para APIs.

01

Primeros pasos

Consulta básica

GraphQL permite a los clientes especificar exactamente qué datos necesitan. Una query trae datos y la respuesta refleja la forma de la consulta. Esto evita el over-fetching y el under-fetching comunes en APIs REST.

graphql
# Query - read data
query {
  user(id: 1) {
    id
    name
    email
    posts {
      title
      content
    }
  }
}

# Response
{
  "data": {
    "user": {
      "id": 1,
      "name": "Alice",
      "email": "[email protected]",
      "posts": [
        { "title": "Hello", "content": "World" }
      ]
    }
  }
}

Query con variables

Las variables parametrizan las consultas para que una misma operación pueda reutilizarse con entradas distintas. Se declaran en la cabecera de la operación con $name: Type. La cadena de la query permanece estática; solo cambia el JSON de variables por llamada.

graphql
# Declare variables with operation name
query GetUser($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

# Variables sent alongside the query
{
  "id": "1",
  "withPosts": true
}

Fundamentos de mutation

Las mutations modifican datos y devuelven un selection set igual que las queries. Por convención deberían ir seguidas de la lectura de los datos modificados. GraphQL ejecuta las mutations en serie (una tras otra), mientras que los campos de las queries corren en paralelo.

graphql
# Mutation - write data, then return the result
mutation {
  createUser(input: { name: "Bob", email: "[email protected]" }) {
    id
    name
  }
}

# Response
{
  "data": {
    "createUser": {
      "id": "42",
      "name": "Bob"
    }
  }
}

Campos y selection sets

Un selection set es la lista de campos dentro de las llaves. Los escalares y los enums devuelven valores hoja; los tipos objeto requieren un selection set anidado. Olvidar una sub-selección en un tipo objeto es un error de validación común.

graphql
# You must select fields - GraphQL never returns whole objects
query {
  user(id: 1) {
    # this block is a "selection set"
    name
    email
  }
}

# Selecting a scalar returns its value directly
# Selecting an object REQUIRES a sub-selection set
query {
  user(id: 1) {
    name          # scalar - OK
    posts {       # object - needs { ... }
      title
    }
  }
}

GraphQL vs REST

REST expone muchos endpoints con formas fijas; GraphQL expone un solo endpoint donde el cliente define la forma. Esto reduce los viajes de ida y vuelta y previene el over/under-fetching. El costo es un servidor más complejo y el caché vía POST.

graphql
# REST: multiple round trips, fixed shapes
GET /users/1            -> { id, name, email, address, ... }
GET /users/1/posts      -> [ { id, title, body, author, ... } ]

# GraphQL: one request, client-defined shape
query {
  user(id: 1) {
    name
    posts { title }
  }
}

# One endpoint, one POST request
POST /graphql
{ "query": "...", "variables": { ... } }

Introspección

La introspección permite a los clientes descubrir el schema en tiempo de ejecución. Herramientas como GraphiQL, Apollo Studio y los generadores de código dependen de ella. Los campos raíz __schema y __type son los puntos de entrada. Los servidores en producción pueden desactivar la introspección para ocultar detalles internos.

graphql
# Ask the schema what types and fields it has
{
  __schema {
    types {
      name
      kind
    }
  }
}

# Inspect a specific type's fields
{
  __type(name: "User") {
    name
    fields {
      name
      type { name kind ofType { name kind } }
    }
  }
}
02

Schema y sistema de tipos

Declaración del schema

El bloque schema conecta los tipos de operación raíz. Si tus tipos raíz se llaman Query, Mutation y Subscription, Apollo/GraphQL.js infiere el schema automáticamente y puedes omitir por completo esta declaración.

graphql
# SDL - Schema Definition Language
schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

# In most servers the schema is inferred from the
# Query/Mutation/Subscription types, so this block is optional.

Tipos raíz

Query, Mutation y Subscription son los puntos de entrada de un schema. Query es el único tipo raíz obligatorio. Cada campo raíz se convierte en una operación que los clientes pueden ejecutar. Nombrarlos como verbos (createUser) para mutations y sustantivos para queries es la convención.

graphql
type Query {
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

type Subscription {
  postAdded: Post!
}

Definiciones de tipos

Los tipos se definen con la palabra clave type seguida de campos. Cada campo tiene un nombre y un tipo de retorno. El sufijo ! significa no nulo; [Type!] significa una lista de elementos no nulos; [Type!]! significa una lista no nula de elementos no nulos.

graphql
# Object type - the most common building block
type User {
  id: ID!
  name: String!
  age: Int
  email: String
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  author: User!
}

Agregar descripciones

Las cadenas entre comillas triples (o las cadenas de una línea antes de una definición) pasan a formar parte del schema como descripciones. Aparecen en la documentación de GraphiQL y en la introspección. Los comentarios con # son solo para desarrollo y se eliminan, así que usa cadenas entre comillas triples para la documentación orientada al usuario.

graphql
"""A registered user of the platform."""
type User {
  """The unique, immutable identifier."""
  id: ID!

  "Display name shown publicly."
  name: String!

  # plain # comments are NOT exposed to clients
  email: String
}

Schema con extensiones

extend type agrega campos a un tipo declarado en otro lugar. Así se divide un schema grande entre varios archivos o se agregan campos específicos de un módulo. Un tipo puede declararse una vez y extenderse muchas veces, pero cada campo solo puede definirse una vez.

graphql
# Extend an existing type without redefining it
type User {
  id: ID!
  name: String!
}

extend type User {
  age: Int
  posts: [Post!]!
}

# Useful for splitting a schema across files,
# or for adding fields only in certain modules.

Schema-first vs Code-first

Schema-first escribe el SDL a mano y adjunta los resolvers (el enfoque clásico de Apollo). Code-first construye el schema programáticamente con decorators/builders de TypeScript (Nexus, TypeGraphQL, Pothos), ganando seguridad de tipos entre el schema y los resolvers. Ambos producen el mismo schema en tiempo de ejecución.

graphql
# 1) Schema-first: write SDL, bind resolvers
const typeDefs = `
  type Query { hello: String }
`;
const resolvers = { Query: { hello: () => "world" } };
const server = new ApolloServer({ typeDefs, resolvers });

# 2) Code-first: build with builders (Nexus, TypeGraphQL)
export const Query = queryType({
  definition(t) {
    t.string("hello", { resolve: () => "world" });
  },
});
03

Tipos escalares

Escalares integrados

GraphQL incluye cinco escalares integrados: Int, Float, String, Boolean e ID. ID se serializa como cadena pero semánticamente significa un identificador — los clientes deben tratarlo como opaco. No hay Date ni DateTime integrados; los defines tú mismo.

graphql
type Example {
  id: ID!          # unique identifier, serialized as string
  name: String!    # UTF-8 text
  age: Int         # 32-bit integer
  score: Float     # double-precision float
  active: Boolean! # true / false
}

Escalares personalizados

Los escalares personalizados permiten representar primitivas del dominio. Tras declararlos, debes proporcionar un resolver que serialize (a JSON), parse (desde variables) y opcionalmente parse literales (desde el AST en línea). De lo contrario el valor pasa tal cual.

graphql
# Declare a custom scalar in SDL
scalar DateTime
scalar URL
scalar JSON

type Event {
  id: ID!
  at: DateTime!
  link: URL
  metadata: JSON
}

Resolvers de escalares

Un resolver de escalar tiene tres funciones opcionales. serialize convierte un valor interno a la salida JSON. parseValue convierte una entrada de variable a la forma interna. parseLiteral convierte un literal en línea del AST de la query a la forma interna. Define los tres para un escalar completamente tipado.

graphql
const resolvers = {
  DateTime: {
    // value -> JSON sent to client
    serialize: (value: Date) => value.toISOString(),
    // variable value -> internal value
    parseValue: (value: string) => new Date(value),
    // inline AST literal -> internal value
    parseLiteral: (ast) => {
      if (ast.kind === "StringValue") {
        return new Date(ast.value);
      }
      return null;
    },
  },
};

Escalar Date/DateTime

El paquete graphql-scalars incluye escalares probados en batalla: DateTime, Date, Time, EmailAddress, URL, UUID, BigInt, JSON y más. Prefiérelo a implementarlos a mano, especialmente para el parseo de fechas ISO 8601 donde abundan los casos límite.

graphql
# Use graphql-scalars for well-tested common types
import { DateTimeResolver } from "graphql-scalars";

const resolvers = {
  DateTime: DateTimeResolver,
  Date: DateResolver,
  Time: TimeResolver,
};

# In SDL
scalar DateTime

type Query {
  now: DateTime!
}

Escalar JSON

Los escalares JSON dejan pasar datos arbitrarios, útiles para configuración dinámica o metadatos. El costo: pierdes seguridad de tipos y validación a nivel de campo, y los clientes no pueden seleccionar subcampos. Úsalo con moderación — un tipo objeto tipado es casi siempre mejor.

graphql
scalar JSON

type Query {
  # accept arbitrary JSON as input or output
  config: JSON
  setConfig(value: JSON): JSON
}

# The simplest pass-through resolver
const resolvers = {
  JSON: {
    serialize: (v) => v,
    parseValue: (v) => v,
    parseLiteral: (ast) => parseJsonLiteral(ast),
  },
};
04

Tipos objeto

Definir tipos objeto

Un tipo objeto es una colección de campos con nombre y tipos de retorno. Los tipos objeto forman el grafo — se referencian entre sí para construir relaciones (User tiene Posts, Post tiene Author). Los tipos objeto son de salida; usa tipos de entrada para las entradas.

graphql
type User {
  id: ID!
  name: String!
  email: String
  createdAt: String!
}

type Post {
  id: ID!
  title: String!
  body: String!
  published: Boolean!
}

Campos y tipos de campo

Cada campo declara un tipo de retorno. Nullable es el valor por defecto; ! lo vuelve no nulo. Las listas se envuelven con []. La posición de ! importa: [String] puede ser null y contener nulls; [String!] puede ser null pero los elementos no; [String!]! nunca puede ser null ni contener nulls.

graphql
type Product {
  id: ID!                # non-null ID
  name: String!          # non-null string
  price: Float!          # non-null float
  discount: Float        # nullable float
  tags: [String!]!       # non-null list of non-null strings
  reviews: [Review]      # nullable list of nullable reviews
}

No nulo y listas

La posición del ! controla la nulabilidad en cada nivel. No nulo es potente pero arriesgado: si un resolver devuelve null en un campo no nulo, el error burbujea y anula también el campo padre. Por defecto usa nullable y opta por no nulo solo donde el valor está realmente garantizado.

graphql
type Example {
  a: [String]       # may be null; items may be null
  b: [String!]      # may be null; items NOT null
  c: [String]!      # NOT null; items may be null
  d: [String!]!     # NOT null; items NOT null

  name: String      # may be null
  name2: String!    # NOT null - errors if null returned
}

Objetos anidados

Los tipos objeto se referencian entre sí para formar el grafo, permitiendo consultas que recorren relaciones (user -> posts -> author -> profile). Las referencias circulares entre tipos están bien y son comunes. El grafo es lo que hace de GraphQL un grafo, no un árbol de endpoints.

graphql
type User {
  id: ID!
  name: String!
  profile: Profile!
  posts: [Post!]!
}

type Profile {
  bio: String
  avatar: String
}

type Post {
  id: ID!
  title: String!
  author: User!   # back-reference creates the graph
}

Argumentos de campo en objetos

Cualquier campo — no solo los raíz — puede recibir argumentos. Esto permite que un solo tipo exponga vistas filtradas/paginadas de datos relacionados (por ejemplo user.posts(limit: 10)). Los argumentos con valores por defecto se vuelven opcionales en las queries.

graphql
type User {
  id: ID!
  name: String!
  # an object field can take arguments
  posts(limit: Int = 5, after: ID): [Post!]!
  role(type: RoleType!): Role
}

type Query {
  user(id: ID!): User
}
05

Queries

Tipo Query

El tipo Query es el punto de entrada de todas las lecturas. Cada campo aquí es una operación de primer nivel que los clientes pueden solicitar. Mantenlo enfocado en lecturas; pon las escrituras en Mutation. Nombrar los campos como sustantivos (users, user, search) es la convención.

graphql
type Query {
  me: User!
  user(id: ID!): User
  users(limit: Int = 20, offset: Int = 0): [User!]!
  search(term: String!): [SearchResult!]!
}

# Clients run these as operations:
# query { me { name } }
# query { user(id: "1") { name } }

Múltiples campos

Una query puede seleccionar varios campos raíz en una sola solicitud. GraphQL los ejecuta en paralelo (excepto en las mutations). Esto agrupa las lecturas relacionadas en un solo viaje, una ganancia de eficiencia clave frente a REST.

graphql
# Several fields in one request - executed in parallel
query {
  me { name email }
  user(id: "1") { name }
  users(limit: 3) { id name }
}

# Response contains all three under "data"
{
  "data": {
    "me": { "name": "Alice", "email": "[email protected]" },
    "user": { "name": "Bob" },
    "users": [ { "id": "1", "name": "Bob" }, ... ]
  }
}

Aliases

Los aliases renombran campos en la respuesta. Son obligatorios al seleccionar el mismo campo con argumentos distintos — las claves de un objeto JSON deben ser únicas. Los aliases también son útiles para claves de respuesta más cortas o con más significado.

graphql
# Same field twice with different args needs aliases
query {
  alice: user(id: "1") { name }
  bob:   user(id: "2") { name }
}

# Response keys match the aliases
{
  "data": {
    "alice": { "name": "Alice" },
    "bob":   { "name": "Bob" }
  }
}

Queries anidadas

Recorrer relaciones es el superpoder de GraphQL. El cliente camina el grafo (user -> posts -> comments -> author) en una sola query. El servidor resuelve cada campo vía su resolver; el anidamiento profundo está bien pero vigila las consultas N+1 en el backend.

graphql
query {
  user(id: "1") {
    name
    posts {            # traverse relationship
      title
      comments {        # and another level
        author {
          name
        }
      }
    }
  }
}

Query con argumentos

Los argumentos pueden ser literales en línea o variables. Los literales en línea están bien para valores estáticos; usa variables siempre que un valor venga de entrada del usuario o cambie por llamada. Las variables mantienen la query cacheable y evitan la concatenación de cadenas.

graphql
# Schema
type Query {
  user(id: ID!, includeEmail: Boolean = false): User
}

# Inline arguments
query {
  user(id: "1", includeEmail: true) {
    name
    email
  }
}

# Prefer variables for dynamic values
query($uid: ID!, $withEmail: Boolean!) {
  user(id: $uid, includeEmail: $withEmail) {
    name
    email
  }
}

Nombre de operación

Nombrar las operaciones (query GetUserProfile) es opcional pero muy recomendable. Las operaciones con nombre son más fáciles de depurar, aparecen en logs y Apollo Studio, y son necesarias al enviar varias operaciones en un documento o para persisted queries.

graphql
# Give operations a name - required in production
query GetUserProfile($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
  }
}
06

Mutations

Tipo Mutation

El tipo Mutation es el punto de entrada de las escrituras. Por convención nombra los campos de mutation como verbos (createUser, updatePost). Las mutations corren en serie en el orden escrito, así que los efectos secundarios dependientes del orden son seguros entre varios campos de mutation en una solicitud.

graphql
type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
  createPost(input: CreatePostInput!): Post!
}

# Client mutation
mutation {
  createUser(input: { name: "Alice", email: "[email protected]" }) {
    id
    name
  }
}

Mutation con input

Usa tipos de entrada para los argumentos de mutation. Agrupan campos relacionados, mantienen la firma limpia y evolucionan de forma segura (agrega campos opcionales sin romper). Pasa siempre los payloads de mutation vía variables, nunca literales en línea.

graphql
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

mutation($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
  }
}

# { "input": { "name": "Bob", "email": "[email protected]" } }

Devolver payloads

Un patrón común es un objeto payload que envuelve el resultado con errores, una bandera de éxito o un client mutation ID. Es más flexible que lanzar excepciones — puedes devolver éxito parcial y errores de validación estructurados junto a la entidad.

graphql
# Return the changed entity AND related fields like errors
type CreateUserPayload {
  user: User
  errors: [UserError!]!
}

type UserError {
  field: String
  message: String!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

Múltiples mutations

A diferencia de las queries (paralelas), las mutations de una operación se ejecutan en serie en el orden declarado. Esto garantiza que la segunda mutation vea los efectos de la primera. Si un campo de mutation falla, los siguientes igualmente corren — valida las entradas y usa transacciones donde sea necesario.

graphql
# Multiple mutations run SERIALLY in declared order
mutation {
  createPost(input: { title: "A" }) {
    id
  }
  publishPost(id: "1") {
    publishedAt
  }
}

Idempotencia

Los reintentos de red pueden duplicar escrituras. Una clave de idempotencia permite al servidor reconocer un reintento y devolver el resultado original en lugar de crear un duplicado. Es esencial para pagos, pedidos y cualquier acción no reversible.

graphql
# Use a client mutation id or idempotency key
input CreateOrderInput {
  idempotencyKey: String!
  productId: ID!
  quantity: Int!
}

type Mutation {
  createOrder(input: CreateOrderInput!): Order!
}

# Clients retry with the SAME idempotencyKey on failure
# Server returns the original order instead of creating a duplicate
07

Subscriptions

Tipo Subscription

Las subscriptions empujan datos del servidor al cliente cuando ocurren eventos, típicamente sobre WebSocket. Son operaciones de larga vida. Mantén los payloads pequeños — los clientes suelen traer los datos detallados con una query posterior en lugar de transmitir objetos grandes.

graphql
type Subscription {
  postAdded: Post!
  userJoined(roomId: ID!): User!
  messageReceived(userId: ID!): Message!
}

# Client subscribes (usually over WebSocket)
subscription {
  postAdded {
    id
    title
    author { name }
  }
}

Suscribirse a eventos

El resolver de una suscripción expone una función subscribe que devuelve un AsyncIterator. Las mutations (o cualquier código del servidor) publican eventos en el mismo topic vía pubsub. La función resolve opcional transforma el payload publicado a la forma del campo.

graphql
# Server-side resolver with asyncIterator
const resolvers = {
  Subscription: {
    postAdded: {
      subscribe: () => pubsub.asyncIterator(["POST_ADDED"]),
      resolve: (payload) => payload.postAdded,
    },
  },
};

# Trigger from a mutation
const resolvers = {
  Mutation: {
    createPost: async (_, args, { pubsub }) => {
      const post = await createPost(args);
      await pubsub.publish("POST_ADDED", { postAdded: post });
      return post;
    },
  },
};

PubSub

El PubSub de graphql-subscriptions funciona para una sola instancia del servidor. Para varias instancias detrás de un balanceador necesitas un broker compartido — redis-pubsub, MQTT o un pubsub respaldado por Kafka — para que los eventos lleguen a los clientes conectados a cualquier instancia.

graphql
import { PubSub } from "graphql-subscriptions";

const pubsub = new PubSub();

// publish an event
pubsub.publish("POST_ADDED", { postAdded: post });

// consume in a subscription resolver
subscribe: () => pubsub.asyncIterator(["POST_ADDED"])

# For multi-instance production, swap PubSub for
# Redis, NATS, or Kafka-based implementations.

Suscripción con filtros

withFilter permite que cada cliente conectado reciba solo los eventos relevantes — por ejemplo, mensajes dirigidos a él. La función de filtro recibe el payload publicado y las variables de la suscripción. Mantén los filtros baratos; corren por cada evento publicado y por cada cliente conectado.

graphql
const resolvers = {
  Subscription: {
    messageReceived: {
      subscribe: withFilter(
        () => pubsub.asyncIterator(["MESSAGE_RECEIVED"]),
        (payload, variables) =>
          payload.messageReceived.recipientId === variables.userId
      ),
      resolve: (payload) => payload.messageReceived,
    },
  },
};

# Only events where the filter returns true reach this client

Transporte WebSocket

Las subscriptions usan el protocolo graphql-ws (o el antiguo subscriptions-transport-ws) sobre WebSocket. Se recomienda el protocolo más nuevo graphql-ws. connectionParams transporta los tokens de autenticación. El servidor debe instalar el handler WS junto al endpoint HTTP.

graphql
# Client uses graphql-ws over WebSocket
import { createClient } from "graphql-ws";

const wsClient = createClient({
  url: "ws://localhost:4000/graphql",
  connectionParams: { authToken: "..." },
});

wsClient.subscribe(
  { query: "subscription { postAdded { id title } }" },
  {
    next: (data) => console.log(data),
    error: (err) => console.error(err),
    complete: () => console.log("done"),
  }
);
08

Argumentos

Argumentos de campo

Los argumentos son con nombre, nunca posicionales. Pueden aparecer en cualquier campo, no solo en los raíz. Los argumentos con nombre hacen que las consultas se expliquen por sí solas y no dependan del orden. Usa variables en lugar de literales en línea cuando los valores sean dinámicos.

graphql
type Query {
  user(id: ID!): User
  posts(limit: Int, offset: Int): [Post!]!
}

# Arguments can be inline literals
query {
  user(id: "1") { name }
  posts(limit: 10, offset: 0) { title }
}

Valores por defecto

Los argumentos con valores por defecto se vuelven opcionales — los clientes pueden omitirlos. Los valores por defecto se evalúan por solicitud. Para argumentos no nulos no hay valor por defecto; el cliente debe aportar un valor. Los valores por defecto mantienen las queries concisas a la vez que explícitas cuando hace falta.

graphql
type Query {
  # default values make arguments optional
  posts(limit: Int = 10, sort: String = "newest"): [Post!]!
  user(id: ID!, includeDeleted: Boolean = false): User
}

# These are equivalent:
query { posts { title } }
query { posts(limit: 10, sort: "newest") { title } }

Tipos de argumentos

Los argumentos pueden ser escalares, enums, listas o tipos objeto de entrada — nunca tipos objeto regulares (esos son solo de salida). Los input objects son la forma idiomática de pasar argumentos complejos y estructurados, especialmente para filtros y paginación.

graphql
type Query {
  # scalar arguments
  byId(id: ID!): User
  byAge(min: Int!, max: Int!): [User!]!

  # enum argument
  byStatus(status: UserStatus!): [User!]!

  # input object argument
  search(filter: UserFilter!): [User!]!

  # list argument
  byIds(ids: [ID!]!): [User!]!
}

Requerido vs opcional

El sufijo ! en un argumento lo vuelve requerido. Omitir un argumento requerido falla la validación antes de que corra el resolver, devolviendo un error claro. Prefiere requerido para entradas realmente necesarias y opcional-con-valor-por-defecto para comportamientos ajustables.

graphql
type Query {
  # required (non-null) - client MUST provide
  user(id: ID!): User

  # optional (nullable) - client may omit
  posts(limit: Int): [Post!]!

  # optional with default
  recentPosts(limit: Int = 5): [Post!]!
}

# Omitting a required argument is a validation error
# before any resolver runs.

Argumentos de lista

Los argumentos de lista usan corchetes. [ID!]! significa una lista no nula de IDs no nulos — el cliente debe pasar una lista y cada elemento debe ser no nulo. Pasa las listas vía variables en lugar de literales en línea por limpieza y para evitar problemas de escape.

graphql
type Query {
  usersByIds(ids: [ID!]!): [User!]!
  tags(allOf: [String!]): [Post!]!
}

# Inline list literal
query {
  usersByIds(ids: ["1", "2", "3"]) { name }
}

# Via variable
query($ids: [ID!]!) {
  usersByIds(ids: $ids) { name }
}
# { "ids": ["1", "2", "3"] }
09

Variables

Definición de variables

Las variables parametrizan las operaciones. Decláralas como $name: Type en la cabecera de la operación, referéncialas como $name en el cuerpo y envía los valores en un campo JSON de variables aparte. Esto separa la query estática de los datos dinámicos.

graphql
# Declare variables in the operation, then use them
query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
  }
}

# Variables are sent in a separate JSON object
{
  "id": "1"
}

Tipos de variables

Los tipos de las variables deben coincidir con los tipos de los argumentos del schema. Las variables pueden ser nullable, no nulas, listas o input objects. El tipo de una variable debe ser un tipo de entrada (escalar, enum o input object) — nunca un tipo objeto de salida.

graphql
query Search(
  $term: String!
  $limit: Int = 10
  $filters: PostFilter
  $tags: [String!]
) {
  search(term: $term, limit: $limit, filters: $filters, tags: $tags) {
    title
  }
}

Valores por defecto

Los valores por defecto de las variables aplican cuando el cliente omite la variable. Solo son legales en variables nullable — una variable no nula significa que el cliente DEBE aportar un valor. Los valores por defecto permiten a los clientes enviar conjuntos mínimos de variables mientras los servidores permanecen flexibles.

graphql
query Posts($limit: Int = 10, $sort: String = "newest") {
  posts(limit: $limit, sort: $sort) { title }
}

# If the client omits "limit", it defaults to 10.
# Only nullable variables can have defaults - a non-null
# variable with a default is a contradiction.

Variables requeridas

Una variable no nula (!) es requerida — omitirla falla la validación antes de que corra el resolver. Es la forma más segura de garantizar que una entrada existe. Las variables no nulas no pueden tener valores por defecto; si quieres uno, haz la variable nullable.

graphql
query User($id: ID!) {     # ! means required
  user(id: $id) { name }
}

# Missing required variable -> validation error
{ "id": "1" }      # OK
{ }                # ERROR: variable $id of type ID! is required

# A non-null variable cannot have a default value.

Variables con directivas

Las variables pueden controlar directivas como @include y @skip, dejando a los clientes alternar campos dinámicamente. Esto es genial para feature flags, pruebas A/B o secciones condicionales — con un único documento de query cacheado.

graphql
query User($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

# { "id": "1", "withPosts": false }  -> posts omitted
# { "id": "1", "withPosts": true }   -> posts included
10

Fragments

Fragments con nombre

Los fragments son selection sets reutilizables ligados a un tipo concreto (fragment Name on Type). Espráelos con ...Name dondequiera que aparezca ese tipo. Mantienen las queries DRY y permiten a los clientes compartir selecciones de campos entre operaciones.

graphql
# Define a reusable fragment
fragment UserFields on User {
  id
  name
  email
}

# Spread it into queries
query {
  user(id: "1") {
    ...UserFields
  }
  users {
    ...UserFields
  }
}

Composición de fragments

Los fragments pueden esparcir otros fragments, construyendo selecciones compuestas. Esto modulariza la elección de campos (perfil básico vs completo) y deja que cada componente de UI declare sus propias necesidades de datos, para luego componerlas en una sola query.

graphql
fragment UserBasic on User {
  id
  name
}

fragment UserWithEmail on User {
  ...UserBasic
  email
}

fragment UserFull on User {
  ...UserWithEmail
  posts { title }
}

# Fragments can spread other fragments of the same type.

Variables de fragments

Las variables de fragments al estilo Relay permiten que un fragment acepte parámetros (como un límite) que quien llama pasa vía @arguments. Esto hace los fragments realmente reutilizables con distintas configuraciones. Apollo lo admite vía la directiva @arguments de sus directivas de cliente.

graphql
fragment UserPosts on User
  @argumentDefinitions(limit: { type: "Int", defaultValue: 5 }) {
  posts(limit: $limit) {
    title
  }
}

query {
  user(id: "1") {
    ...UserPosts @arguments(limit: 10)
  }
}

# @argumentDefinitions and @arguments come from
# Relay; Apollo uses a similar pattern via client directives.

Fragments reutilizables

Colocar los fragments junto a los componentes que los renderizan es un patrón potente: cada componente declara sus necesidades de datos y el padre las compone en una sola query. Esto escala el fetching de datos en apps grandes (Relay y Apollo lo admiten ambos).

graphql
// Colocate fragments with the UI component that uses them
const USER_CARD = graphql`
  fragment UserCard_user on User {
    id
    name
    avatarUrl
  }
`;

function UserCard({ user }) {
  return <div>{user.name}</div>;
}

// The parent query spreads all needed fragments
query {
  users {
    ...UserCard_user
  }
}

Precauciones con fragments

Un fragment declarado sobre Post solo puede esparcirse donde se espere un Post — esparcirlo sobre un User es un error de validación. Usa inline fragments con condiciones de tipo para esparcir condicionalmente sobre unions/interfaces. Evita también las dispersiones circulares de fragments.

graphql
# A fragment must match the type where it's spread
fragment PostFields on Post { title body }

query {
  user(id: "1") {
    ...PostFields   # ERROR: user is not a Post
  }
}

# Fragments can only spread on the declared type
# (or via type conditions with inline fragments).
11

Inline fragments

Fundamentos de inline fragments

Un inline fragment es un selection set sin nombre con el prefijo ... on Type. Aplica los campos solo cuando el objeto en tiempo de ejecución coincide con la condición de tipo. Así se accede a los campos específicos de tipo en interfaces y unions.

graphql
# An inline fragment is a selection set with a type condition
query {
  user(id: "1") {
    id
    name
    # fields common to User
    ... on AdminUser {
      permissions
    }
  }
}

# No name - declared inline in the query.

Condiciones de tipo

La sintaxis ... on Type es una condición de tipo. Varios inline fragments en una selección permiten manejar por separado cada tipo posible de una union/interface. Los campos que comparten los tipos pueden seleccionarse directamente fuera de los fragments.

graphql
query Search($term: String!) {
  search(term: $term) {
    ... on User { name email }
    ... on Post { title author { name } }
    ... on Comment { body }
  }
}

Acceso a unions

Las unions no tienen campos compartidos más allá de __typename, así que para leer datos específicos del tipo debes usar inline fragments. __typename siempre es seleccionable y dice al cliente de qué tipo concreto es cada elemento — esencial para renderizar resultados de unions.

graphql
union SearchResult = User | Post | Comment

query {
  search(term: "graphql") {
    # shared __typename is always available
    __typename
    ... on User { name }
    ... on Post { title }
    ... on Comment { body }
  }
}

Acceso a interfaces

Las interfaces declaran campos compartidos. Esos campos pueden seleccionarse directamente sobre la interfaz; los campos específicos del tipo necesitan inline fragments. A diferencia de las unions, las interfaces garantizan un conjunto común de campos que cada tipo que la implemente debe proveer.

graphql
interface Node { id: ID! }
type User implements Node { id: ID! name: String! }
type Post implements Node { id: ID! title: String! }

query {
  node(id: "1") {
    id              # shared interface field - selectable directly
    ... on User { name }
    ... on Post { title }
  }
}

Fragment con nombre y condición de tipo

Los fragments con nombre llevan su propia condición de tipo, así que puedes esparcirlos sobre un resultado de union/interface y cada uno aplica solo a su tipo coincidente. Esto combina reutilización con selección condicional — esparce varios fragments con nombre para cubrir cada miembro de la union.

graphql
# Named fragments can also carry a type condition
fragment UserFields on User { name email }
fragment PostFields on Post { title }

query {
  search(term: "a") {
    ...UserFields
    ...PostFields
  }
}

# Equivalent to inlining those fragments inline.
12

Directivas

Directivas integradas

GraphQL incluye dos directivas de cliente integradas: @skip(if: Boolean!) omite el campo cuando es true, @include(if: Boolean!) lo incluye solo cuando es true. Son mutuamente excluyentes y pueden aplicarse a campos, dispersiones de fragments e inline fragments.

graphql
# @skip - omit field if true
query($skip: Boolean!) {
  user(id: "1") {
    name
    email @skip(if: $skip)
  }
}

# @include - include field only if true
query($withPosts: Boolean!) {
  user(id: "1") {
    posts @include(if: $withPosts) { title }
  }
}

@skip y @include

@skip y @include permiten que una sola query sirva múltiples formas. Reciben una variable Boolean, así que la misma persisted query puede renderizar un resumen o una vista detallada según las variables — sin mantener dos cadenas de query.

graphql
query User($id: ID!, $detailed: Boolean!) {
  user(id: $id) {
    name
    email @skip(if: $detailed)      # hide when detailed
    profile @include(if: $detailed) {  # show when detailed
      bio
    }
  }
}

# { "id": "1", "detailed": false } -> name, email
# { "id": "1", "detailed": true }  -> name, profile { bio }

Directivas personalizadas

Las directivas personalizadas empiezan con una declaración directive que da argumentos y ubicaciones permitidas. La semántica de ejecución no está integrada — la implementas con transformaciones de schema (Apollo) o visitantes de directivas (graphql-tools). Usos comunes: @auth, @cached, @deprecated.

graphql
# Declare a directive in SDL
directive @auth(requires: Role = ADMIN) on FIELD_DEFINITION

type Query {
  adminData: String @auth(requires: ADMIN)
  userData: String @auth(requires: USER)
}

# A directive needs a location: FIELD_DEFINITION, FIELD,
# OBJECT, ENUM, etc. Logic is implemented in the server
# (e.g. via schema transforms or a directive visitor).

Ubicaciones de directivas

Toda directiva declara dónde es legal — sobre operaciones, campos, fragments o definiciones de schema (FIELD_DEFINITION, OBJECT, etc.). Las directivas de cliente (aplicadas en queries) y las directivas de schema (aplicadas en SDL) usan conjuntos de ubicaciones distintos. Valida al construir el schema.

graphql
# Where a directive can appear
directive @example on
  | QUERY          # operation
  | FIELD          # a field in a selection
  | FRAGMENT_DEFINITION
  | FRAGMENT_SPREAD
  | INLINE_FRAGMENT
  | FIELD_DEFINITION  # in SDL (server-side)
  | OBJECT | INTERFACE | UNION | ENUM
  | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION;

# Multiple locations use | between them.

Argumentos de directivas

Las directivas pueden recibir argumentos tipados con valores por defecto. La integrada @deprecated(reason:) marca campos y valores de enum como obsoletos; las herramientas advierten a los clientes que los usan. Las directivas personalizadas con argumentos dirigen comportamientos como TTLs de caché o roles requeridos.

graphql
directive @deprecated(
  reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE

type Query {
  oldField: String @deprecated(reason: "Use newField")
  newField: String
}

enum Status {
  ACTIVE
  INACTIVE @deprecated(reason: "Use ARCHIVED")
  ARCHIVED
}
13

Enums

Definir enums

Un enum es un conjunto finito de valores con nombre. Los enums son tipos escalares — son valores hoja sin sub-selecciones. Úsalos para cualquier campo con un conjunto fijo de opciones (status, role, kind) en lugar de cadenas mágicas, ganando validación y autodescripción.

graphql
enum Role {
  ADMIN
  USER
  GUEST
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type User {
  role: Role!
}

type Post {
  status: PostStatus!
}

Valores de enum

Los valores de enum se escriben como identificadores sin comillas en las queries (color: RED), pero se serializan como cadenas en las variables JSON y en las respuestas. Por convención se nombran en UPPER_SNAKE_CASE. El servidor valida cualquier valor contra el conjunto declarado.

graphql
enum Color {
  RED
  GREEN
  BLUE
}

# In a query, enum values are unquoted identifiers
query {
  products(color: RED) { name }
}

# In variables JSON, they're sent as strings
{ "color": "RED" }

Uso de enums en queries

Los enums funcionan como tipos de campo y como tipos de argumento. Cuando se usan como argumento, el cliente pasa uno de los valores declarados. Los valores de enum inválidos fallan la validación antes de que corra el resolver, dando errores claros.

graphql
type Query {
  posts(status: PostStatus!): [Post!]!
}

query {
  posts(status: PUBLISHED) { title }
}

query($status: PostStatus!) {
  posts(status: $status) { title }
}
# { "status": "DRAFT" }

Resolvers de enums

Por defecto un valor de enum se mapea a sí mismo. Un resolver de enum permite mapear entre el nombre público de la API (ADMIN) y una representación interna (una cadena "admin" o un código numérico de rol). Esto desacopla tu schema de los detalles de almacenamiento.

graphql
# Map internal values <-> API values
enum Role {
  ADMIN
  USER
}

const resolvers = {
  Role: {
    ADMIN: "admin",   // internal DB value
    USER: "user",
  },
};

# Internally the resolver sees "admin"; the client sees ADMIN.
# Useful when DB values differ from the public API.

Buenas prácticas con enums

Prefiere siempre los enums sobre las cadenas libres para conjuntos fijos de opciones — validan entradas, documentan la API y habilitan mejores herramientas. Para quitar un valor de enum sin romper a los clientes, deprecádolo primero. Eliminar un valor que los clientes aún envían es un cambio disruptivo.

graphql
# Prefer enums over strings for fixed option sets
type User {
  role: Role!          # GOOD - validated, self-documenting
  roleStr: String      # AVOID - no validation, magic strings
}

# Deprecate values instead of removing them
enum Status {
  ACTIVE
  INACTIVE @deprecated(reason: "Use ARCHIVED")
  ARCHIVED
}
14

Interfaces

Definir interfaces

Una interfaz es un tipo abstracto que declara un conjunto de campos que los tipos que la implementen deben proveer. Define un contrato. Las interfaces son útiles para abstracciones compartidas como Node (IDs globales al estilo Relay) o Character entre tipos relacionados.

graphql
interface Node {
  id: ID!
}

interface Character {
  name: String!
}

type User implements Node & Character {
  id: ID!
  name: String!
  email: String!
}

Implementar interfaces

Un tipo declara que implementa una interfaz con la palabra clave implements. Debe definir cada campo que la interfaz declare, con tipos compatibles. Un tipo puede implementar varias interfaces (separadas por &). El schema valida esto al momento de construir.

graphql
interface Node {
  id: ID!
}

type User implements Node {
  id: ID!        # required by Node
  name: String!
}

type Post implements Node {
  id: ID!        # required by Node
  title: String!
}

# A type must implement every field of the interface.

Consultar interfaces

Cuando un campo devuelve una interfaz, puedes seleccionar los campos compartidos de la interfaz directamente. Para acceder a campos específicos del tipo, usa inline fragments (... on User). El tipo en tiempo de ejecución de cada resultado determina qué inline fragments aplican.

graphql
interface Node { id: ID! }

type Query {
  node(id: ID!): Node
}

query {
  node(id: "1") {
    id              # interface field - always selectable
    ... on User { name }
    ... on Post { title }
  }
}

Resolvers de interfaces

Una interfaz necesita una función __resolveType que devuelva el nombre del tipo concreto (o el objeto de tipo) para un valor dado en tiempo de ejecución. Esto le dice a GraphQL qué inline fragments aplicar. Sin ella, GraphQL no puede determinar el tipo concreto en tiempo de ejecución.

graphql
interface Character { name: String! }

type Human implements Character {
  name: String!
  starships: [String!]!
}

type Droid implements Character {
  name: String!
  primaryFunction: String
}

const resolvers = {
  Character: {
    // tell GraphQL which concrete type a value is
    __resolveType(obj) {
      return obj.primaryFunction ? "Droid" : "Human";
    },
  },
};

Múltiples interfaces

Un tipo puede implementar varias interfaces con el separador &. Esto compone capacidades — por ejemplo un Article que es Node, Timestamped y SoftDeletable. La consulta devuelve el tipo de la interfaz, y los clientes usan inline fragments para los campos concretos.

graphql
interface Node { id: ID! }
interface Timestamped { createdAt: String! }
interface SoftDeletable { deletedAt: String }

type Article implements Node & Timestamped & SoftDeletable {
  id: ID!
  createdAt: String!
  deletedAt: String
  title: String!
}

# Use & to list multiple implemented interfaces.
15

Unions

Definir unions

Una union es un tipo abstracto que puede ser uno de varios tipos concretos, sin exigir campos compartidos (a diferencia de las interfaces). Defínela con union Name = TypeA | TypeB. Las unions son geniales cuando los resultados son heterogéneos pero conceptualmente relacionados.

graphql
union SearchResult = User | Post | Comment

type User { id: ID! name: String! }
type Post { id: ID! title: String! }
type Comment { id: ID! body: String! }

type Query {
  search(term: String!): [SearchResult!]!
}

Union vs Interface

Usa una interfaz cuando los miembros comparten un contrato común (campos que comparten). Usa una union cuando los miembros no se relacionan salvo conceptualmente — no comparten campos. Un tipo puede estar en muchas unions; las unions no pueden implementar directamente otras unions.

graphql
# INTERFACE - shared contract
interface Node { id: ID! }
type User implements Node { id: ID! name: String! }
type Post implements Node { id: ID! title: String! }
# All members share the "id" field.

# UNION - no shared contract
union SearchResult = User | Post
# Members share NO required fields.

Consultar unions

Las unions no exponen campos propios, así que debes usar inline fragments para leer cualquier cosa. __typename siempre está disponible y dice al cliente de qué tipo concreto es cada elemento. Seleccionar un campo directamente sobre una union (sin condición de tipo) es un error de validación.

graphql
query {
  search(term: "graphql") {
    __typename          # always available
    ... on User { name email }
    ... on Post { title }
    ... on Comment { body }
  }
}

# You CANNOT select fields directly on a union
# (no shared fields) - only via inline fragments.

Resolvers de unions

Como las interfaces, las unions necesitan un resolver __resolveType que devuelva el nombre del tipo concreto para un valor en tiempo de ejecución. Sin él GraphQL no puede elegir los inline fragments. Devuelve el nombre del tipo como cadena o el objeto de tipo del schema.

graphql
union SearchResult = User | Post | Comment

const resolvers = {
  SearchResult: {
    __resolveType(obj) {
      if (obj.email) return "User";
      if (obj.title) return "Post";
      if (obj.body) return "Comment";
      return null;
    },
  },
};

Patrones comunes

Las unions modelan resultados de éxito-o-error: una mutation devuelve una union de un tipo de éxito y un tipo de error, forzando a los clientes a manejar ambos. Esto es más seguro en tipos que un único payload con campos de error opcionales. (El SDL exige union, no alias de tipo.)

graphql
# Mutation result that may be success or error
type CreateUserSuccess { user: User! }
type CreateUserError { messages: [String!]! }
type CreateUserPayload = CreateUserSuccess | CreateUserError
# (note: a type alias like this isn't valid SDL; use union)
union CreateUserPayload = CreateUserSuccess | CreateUserError

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}
16

Tipos de entrada

Tipos input object

Los tipos de entrada son tipos objeto usados como argumentos, declarados con input. Agrupan campos relacionados (un usuario, un filtro) en un solo argumento. A diferencia de los tipos objeto de salida, los tipos de entrada solo pueden contener tipos de entrada (escalares, enums, otros tipos de entrada).

graphql
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

mutation($input: CreateUserInput!) {
  createUser(input: $input) { id }
}
# { "input": { "name": "Alice", "email": "[email protected]" } }

Entrada vs salida

Los tipos de salida (type) pueden tener argumentos de campo y resolvers; los tipos de entrada (input) son simples portadores de datos sin resolvers. Son namespaces separados — puedes tener un tipo User y un input UserInput. No reutilices uno para ambos; rompe la evolución.

graphql
# OUTPUT type - returned from resolvers, has resolvers
type User {
  id: ID!
  name: String!
  posts: [Post!]!   # can have field arguments and resolvers
}

# INPUT type - passed into operations, no resolvers
input UserInput {
  name: String!
  email: String!
  # NO field arguments, NO resolvers, NO output object types
}

# A type cannot be used as both input and output.

Entradas anidadas

Los tipos de entrada pueden referenciar otros tipos de entrada y listas, modelando payloads complejos y anidados. Esto es ideal para formularios jerárquicos o filtros anidados. Cada nivel se valida contra el schema, dando errores claros ante entradas malformadas.

graphql
input AddressInput {
  street: String!
  city: String!
  zip: String!
}

input CreateUserInput {
  name: String!
  email: String!
  address: AddressInput      # nested input type
  tags: [String!]            # list input
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

Valores por defecto de entrada

Los campos y argumentos de entrada pueden tener valores por defecto. Cuando el cliente omite un campo, aplica el valor por defecto. Los valores por defecto hacen las entradas opcionales sin forzar a los clientes a enviar objetos completos. Nota: los valores por defecto son literales estáticos, no calculados por solicitud.

graphql
input PaginationInput {
  limit: Int = 20
  offset: Int = 0
  sort: SortOrder = DESC
}

enum SortOrder { ASC DESC }

type Query {
  posts(page: PaginationInput = { limit: 20, offset: 0 }): [Post!]!
}

# Defaults apply per-field when omitted by the client.

Validación de entradas

GraphQL valida los tipos y la no nulidad, pero no las reglas semánticas (formato de email, rango de edad, longitud de cadena). Implementa esas reglas en el resolver, lanzando UserInputError ante datos malos. Algunos servidores agregan directivas de validación (@constraint) para reglas declarativas.

graphql
input CreateUserInput {
  name: String!              # required, non-null
  email: String!             # format check needs custom code
  age: Int                   # range check needs custom code
}

# GraphQL validates structure; you validate semantics
function createUser(_, { input }) {
  if (!input.email.includes("@")) {
    throw new UserInputError("Invalid email");
  }
  if (input.age < 0 || input.age > 150) {
    throw new UserInputError("Invalid age");
  }
  // ...
}
17

Resolvers

Funciones resolver

Un resolver es una función que produce el valor de un campo. El mapa de resolvers refleja el schema: resolvers.Query.user maneja el campo user. Si falta un resolver, GraphQL usa uno por defecto que lee la propiedad correspondiente del padre.

graphql
const resolvers = {
  Query: {
    user: (parent, args, context, info) => {
      return context.db.user.findById(args.id);
    },
    users: () => db.users.findAll(),
  },
  Mutation: {
    createUser: (_, { input }, { db }) =>
      db.user.create(input),
  },
};

Argumentos de resolvers

Cada resolver recibe cuatro argumentos: parent (el valor resuelto del campo padre), args (los argumentos de este campo), context (un objeto compartido por solicitud) e info (AST y metadatos de ejecución). Los dos primeros son los más comunes; info es para casos avanzados como inspeccionar la sub-selección.

graphql
// (parent, args, context, info)
const resolvers = {
  Query: {
    user: (parent, args, context, info) => {
      // parent   - value returned by the parent field (root for Query)
      // args     - arguments passed to this field
      // context  - shared per-request object (db, user, loaders)
      // info     - AST + execution info (rarely needed)
      return context.db.user.findById(args.id);
    },
  },
};

Cadena de resolvers

Los resolvers corren en una cadena depth-first: el resolver del campo padre produce un objeto, luego el resolver de cada campo hijo corre con ese objeto como parent. Este flujo de arriba abajo permite que cada campo se resuelva de forma independiente — el grafo se ensambla campo por campo.

graphql
# query { user(id: "1") { name posts { title } } }
const resolvers = {
  Query: {
    user: () => ({ id: "1", name: "Alice" }),   // runs first
  },
  User: {
    posts: (user, args, ctx) => {                // runs after user
      return ctx.db.posts.findByAuthor(user.id);
    },
  },
  Post: {
    title: (post) => post.title,                 // runs after posts
  },
};

Resolvers asíncronos

Los resolvers pueden devolver Promises; GraphQL las espera antes de continuar con los campos hijos. Así llamas a bases de datos y APIs. Usa async/await por legibilidad. Los resolvers del mismo nivel corren en paralelo (para queries), así que el trabajo asíncrono independiente se agrupa de forma natural.

graphql
const resolvers = {
  Query: {
    // return a Promise - GraphQL awaits it
    user: async (_, { id }, { db }) => {
      const user = await db.user.findById(id);
      if (!user) throw new Error("User not found");
      return user;
    },
  },
  User: {
    posts: async (user, _, { db }) =>
      db.posts.findByAuthor(user.id),
  },
};

Resolvers por defecto

Si un campo no tiene resolver, GraphQL lee del objeto padre la propiedad del mismo nombre (devolviendo null si no está definida). Solo escribes resolvers para campos que necesitan lógica o fetching. El comportamiento por defecto funciona cuando tus objetos padre ya tienen la forma correcta.

graphql
# If you don't define a resolver, GraphQL reads from the parent
const resolvers = {
  User: {
    // name resolver missing - default behavior:
    // (parent) => parent.name
    posts: (user) => fetchPosts(user.id),  // only this is custom
  },
};

// Equivalent explicit default:
User: {
  name: (user) => (user.name === undefined ? null : user.name),
}

Buenas prácticas con resolvers

Mantén los resolvers delgados: delega el fetching a clases de fuentes de datos en el context. Esto centraliza el acceso a datos (testeable, mockeable) y deja que las fuentes de datos agrupen y cacheen. Los resolvers deben orquestar, no contener SQL ni lógica de fetch directamente.

graphql
# Keep resolvers thin - delegate to data sources
const resolvers = {
  Query: {
    user: (_, { id }, { dataSources }) =>
      dataSources.userAPI.getUser(id),
  },
  User: {
    posts: (user, _, { dataSources }) =>
      dataSources.postAPI.byAuthor(user.id),
  },
};

// dataSources live on context, are injected per request,
// and can batch/cache calls internally.
18

Context y DataLoader

Objeto context

El context es un objeto por solicitud compartido entre los resolvers de una operación. Pon aquí las dependencias compartidas: clientes de base de datos, el usuario autenticado, data loaders y loggers. La función de context corre una vez por solicitud y su valor de retorno se pasa a cada resolver.

graphql
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => ({
    db: new PrismaClient(),
    user: getUserFromToken(req.headers.authorization),
    loaders: buildLoaders(),
  }),
});

// Inside any resolver, the third argument is context:
(parent, args, context) => context.db.user.findById(args.id);

Context por solicitud

Crea instancias frescas de DataLoader dentro de la función de context para que sus cachés se limiten a una sola solicitud. Reutilizar un loader entre solicitudes filtraría datos cacheados entre usuarios. El context mismo se construye una vez por solicitud, así que la configuración por solicitud va aquí.

graphql
const context = async ({ req }) => {
  const token = req.headers.authorization || "";
  const user = await verifyToken(token);  // may be null

  return {
    user,
    db,
    // a FRESH DataLoader instance per request
    // so caches don't leak across requests
    userLoader: new DataLoader((ids) => batchGetUsers(ids)),
  };
};

El problema N+1

El problema N+1: traer una lista de N elementos y luego hacer una consulta extra por elemento para cargar una relación. La resolución paralela de campos de GraphQL lo hace fácil de topar — un resolver User.posts corre una vez por usuario. El resultado es una inundación de consultas redundantes.

graphql
# query { users { id name posts { title } } }
// BAD: 1 query for users, then N queries for each user's posts
const resolvers = {
  User: {
    posts: (user, _, { db }) =>
      db.posts.findByAuthor(user.id),  // runs once per user!
  },
};

// If there are 100 users, that's 101 DB queries.
// This is the classic N+1 problem.

Fundamentos de DataLoader

DataLoader fusiona muchas cargas individuales en una sola solicitud agrupada. Le das una función de batch que recibe un array de claves y devuelve un array de resultados en el mismo orden. DataLoader entonces reúne todas las cargas dentro de un tick y llama a tu función de batch una sola vez.

graphql
import DataLoader from "dataloader";

// A batch function receives an array of keys, returns
// an array of values IN THE SAME ORDER as the keys.
const userLoader = new DataLoader(async (userIds) => {
  const users = await db.users.findMany({ where: { id: { in: userIds } } });
  // reorder to match the input keys
  return userIds.map((id) =>
    users.find((u) => u.id === id) ?? null
  );
});

DataLoader en resolvers

Usa loader.load(key) en los resolvers en lugar de llamadas directas a la BD. Dentro de un mismo tick, todas las cargas del mismo loader se agrupan en una consulta, y los resultados se cachean durante la solicitud. Esto elimina los N+1 manteniendo los resolvers simples.

graphql
const resolvers = {
  User: {
    posts: (user, _, { loaders }) =>
      loaders.postLoader.load(user.id),
  },
  Post: {
    author: (post, _, { loaders }) =>
      loaders.userLoader.load(post.authorId),
  },
};

// 100 users -> ONE batched query for all their posts,
// instead of 100 separate queries.

Batching y caché

DataLoader hace dos cosas: batching (muchas cargas en un tick del event loop se vuelven una llamada de batch) y caché por clave (cargas repetidas de la misma clave devuelven la misma Promise). La caché es por instancia de loader, razón por la que creas un loader nuevo por solicitud.

graphql
// Batching: many .load() calls in one tick -> one batch fn call
await Promise.all([loader.load(1), loader.load(2), loader.load(3)]);
// -> batchGetUsers([1, 2, 3]) called ONCE

// Caching: repeated .load(sameKey) returns the cached Promise
loader.load(1); loader.load(1); loader.load(1);
// -> batchGetUsers([1]) called ONCE; later calls hit cache

// .clear(key) invalidates; .clearAll() resets everything.
19

Manejo de errores

Formato de respuesta de errores

Los errores se devuelven en un array errors de primer nivel junto a data. Cada error tiene un message, la location en la query, el path al campo que falló y extensions para códigos legibles por máquina. Un error de campo anula ese campo (o burbujea si es no nulo) mientras data sigue devolviendo las partes exitosas.

graphql
# Errors appear in a top-level "errors" array
{
  "errors": [
    {
      "message": "User not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND",
        "exception": { "stacktrace": ["..."] }
      }
    }
  ],
  "data": { "user": null }
}

Lanzar errores

El manejo de errores más simple: lanzar un Error. GraphQL lo captura, anula el campo y agrega una entrada al array errors. Para más estructura, usa clases de error especializadas (ApolloError, UserInputError) que llevan un código de error en extensions.

graphql
const resolvers = {
  Query: {
    user: async (_, { id }, { db }) => {
      const user = await db.user.findById(id);
      if (!user) {
        throw new Error("User not found");
      }
      return user;
    },
  },
};

# Thrown errors become entries in the "errors" array.

Errores personalizados

Usa clases de error tipadas para transmitir intención: UserInputError para entradas malas del cliente (4xx), AuthenticationError para autenticación ausente, ForbiddenError para falta de permisos, y ApolloError con un código para casos personalizados. El código en extensions permite a los clientes ramificar de forma confiable ante errores.

graphql
import { ApolloError, UserInputError } from "apollo-server-errors";

const resolvers = {
  Mutation: {
    createUser: (_, { input }) => {
      if (!isValidEmail(input.email)) {
        throw new UserInputError("Invalid email", {
          field: "email",
        });
      }
      if (emailTaken(input.email)) {
        throw new ApolloError("Email taken", "EMAIL_TAKEN", {
          email: input.email,
        });
      }
      // ...
    },
  },
};

Extensions de errores

extensions transporta datos legibles por máquina: una cadena de código estable, pistas de reintento, rutas de campos de validación, etc. Los clientes deben actuar según extensions.code en lugar de parsear el mensaje humano, que puede cambiar. Mantén los stacktraces fuera de las respuestas de producción.

graphql
# Structured, machine-readable error data
throw new ApolloError("Rate limited", "RATE_LIMITED", {
  code: "RATE_LIMITED",
  retryAfter: 60,
  limit: 100,
});

# Clients check extensions.code to handle errors
if (err.extensions.code === "RATE_LIMITED") {
  wait(err.extensions.retryAfter);
}

Resultados parciales

GraphQL devuelve resultados parciales: los campos exitosos vuelven en data mientras los campos fallidos quedan null (o burbujean si son no nulos) y se listan en errors. Prefiere campos nullable para que un fallo no anule toda la respuesta. No nulo es un contrato fuerte — úsalo deliberadamente.

graphql
# A non-null field error nulls the parent; nullable just nulls the field
type Query {
  user(id: ID!): User       # nullable - error nulls only "user"
  me: User!                 # non-null - error bubbles up to null "me"
}

# Query selecting multiple fields:
query { me { name } user(id: "bad") { name } }
# If "user" errors but "me" succeeds:
{
  "data": { "me": { "name": "Alice" }, "user": null },
  "errors": [{ "path": ["user"], "message": "..." }]
}
20

Apollo Server e integración

Configurar Apollo Server

Apollo Server es el servidor GraphQL de Node.js más popular. Pasa typeDefs (SDL) y resolvers para construirlo, luego arranca con el servidor standalone para desarrollo rápido. Para producción, integra con un framework HTTP existente (Express, Fastify, Next.js) en lugar del standalone.

graphql
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";

const typeDefs = `#graphql
  type Query { hello: String }
`;

const resolvers = {
  Query: { hello: () => "Hello, world!" },
};

const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});
console.log(`Server ready at ${url}`);

Integración con Express

Para Express, usa expressMiddleware de @apollo/server/express4. Arranca el servidor antes de montar el middleware. La función de context recibe el req/res de Express, permitiéndote leer headers, sesiones o adjuntar autenticación. Esto compone GraphQL en una app Express existente.

graphql
import { ApolloServer } from "@apollo/server";
import { expressMiddleware } from "@apollo/server/express4";
import express from "express";
import cors from "cors";
import bodyParser from "body-parser";

const app = express();
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();

app.use("/graphql", cors(), bodyParser.json(),
  expressMiddleware(server, {
    context: async ({ req }) => ({ user: getUser(req) }),
  })
);
app.listen(4000);

Construcción del schema

makeExecutableSchema (de @graphql-tools/schema) construye un schema a partir de typeDefs y resolvers, devolviendo un objeto GraphQLSchema que pasas a ApolloServer. Esta indirección habilita transformaciones de schema, fusión de múltiples módulos y aplicación de directivas personalizadas — útil en bases de código grandes.

graphql
import { makeExecutableSchema } from "@graphql-tools/schema";

const schema = makeExecutableSchema({
  typeDefs,
  resolvers,
});

const server = new ApolloServer({ schema });

// makeExecutableSchema lets you apply schema transforms,
// directive visitors, and merge modules before serving.

Función de context

La función de context corre una vez por solicitud y su valor de retorno lo comparten los resolvers. Lee los headers de autenticación y adjunta aquí el usuario autenticado, los clientes de base de datos y DataLoaders frescos. Lanza una excepción dentro del context para rechazar una solicitud antes de que corra cualquier resolver (por ejemplo, mala autenticación).

graphql
const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => {
    const token = req.headers.authorization || "";
    const user = await verifyToken(token);
    return { user, db, loaders: makeLoaders() };
  },
  listen: { port: 4000 },
});

Apollo Studio / Sandbox

Apollo Sandbox (en el navegador, en la URL de tu servidor) permite explorar el schema y ejecutar operaciones durante el desarrollo. Apollo Studio es el equivalente en la nube para historial de schema, métricas y tracing. Desactiva la introspección en producción si quieres ocultar tu schema a extraños.

graphql
# Apollo Sandbox is a dev IDE in the browser
# Visit the server URL in a browser to open it.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  // Apollo Studio reports go through this key (optional)
  // apollo: { graphRef: "my-graph@current" },
});

# For introspection in production, enable it explicitly:
# new ApolloServer({ introspection: true });

Ciclo de vida de la solicitud

Apollo Server ejecuta un ciclo de vida por solicitud: construir el context, parsear la query, validar contra el schema, ejecutar los resolvers y formatear la respuesta. formatError personaliza la forma de los errores; los plugins se enganchan a fases como didResolveOperation, willSendResponse — genial para logs, caché y métricas.

graphql
# Order: HTTP request -> context -> parse -> validate ->
#        execute (resolvers) -> format response -> HTTP response

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formatted, error) => ({
    message: error.message,
    code: formatted.extensions?.code,
  }),
  plugins: [loggingPlugin, cachePlugin],
});

# plugins hook into every lifecycle phase.

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.