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.
# 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.
# 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.
# 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.
# 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.
# 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.
# 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 } }
}
}
}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.
# 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.
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.
# 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.
"""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.
# 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.
# 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" });
},
});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.
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.
# 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.
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.
# 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.
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),
},
};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.
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.
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.
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.
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.
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
}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.
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.
# 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.
# 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.
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.
# 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.
# 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
}
}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.
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.
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.
# 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.
# 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.
# 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 duplicateSubscriptions
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.
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.
# 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.
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.
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 clientTransporte 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.
# 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"),
}
);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.
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.
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.
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.
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.
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"] }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.
# 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.
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.
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.
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.
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 includedFragments
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.
# 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.
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.
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).
// 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.
# 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).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.
# 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.
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.
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.
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.
# 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.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.
# @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.
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.
# 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.
# 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.
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
}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.
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.
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.
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.
# 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.
# 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
}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.
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.
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.
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.
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.
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.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.
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.
# 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.
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.
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.)
# 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!
}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).
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.
# 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.
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.
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.
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");
}
// ...
}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.
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.
// (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.
# 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.
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.
# 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.
# 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.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.
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í.
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.
# 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.
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.
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.
// 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.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.
# 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.
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.
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.
# 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.
# 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": "..." }]
}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.
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.
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.
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).
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.
# 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.
# 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.Fragmentos de GraphQL relacionados
Copy-paste ready code for common tasks.
Schema and Types
Define types, enums, and scalars.
Queries
Read data with selection sets.
Mutations
Write data and return the result.
Subscriptions
Receive pushed updates over a stream.
Fragments
Reusable selection sets.
Variables
Parameterize operations dynamically.
Directives
Conditionally include or skip fields.
Resolvers
Functions that fulfill each field.
Was this helpful?