Glossary
107 terms from GraphQL APIs, in plain words, each with the chapter that teaches it.
#
- __typename
- A hidden field on every type that returns the type's name. Clients such as urql use it to know what a reply holds.
A
- Alias
- A new name given to a field in a reply, written as `name: field`. It lets one query ask for the same field twice with different arguments, such as `espresso: product(sku: "ESP-5LB")` and `decaf: product(sku: "DEC-5LB")`.
- Anonymous operation
- A query written as just `{ ... }`, with no name and no variables. It's fine for trying things in GraphiQL, but real clients usually name their operations.
- Apollo Client
- A larger GraphQL client library for apps. It has a normalized cache, so one change to a product updates every query on screen that shows it.
- app.inject
- A Fastify method that sends a simulated HTTP request straight to the app without opening a network port. It is used in tests to POST GraphQL operations to `/graphql` and check the replies.
- Argument
- A named input passed to a field in brackets, as in `product(sku: "ESP-5LB")`. A resolver receives its arguments as its second parameter.
- Async iterator
- A source of values that arrive one at a time, whenever they're ready. A subscription's `subscribe` function returns one, so each stock change reaches the client as it happens.
- Authorization header
- An HTTP header that carries the login token, written as `Authorization: Bearer <token>`. kc-graph's context function reads it to find out who sent the request.
B
- base64url
- An encoding that turns text into letters, digits, `-` and `_`, so it is safe inside a URL. kc-graph uses it to turn a SKU or order id into a cursor.
- Batch function
- The function you give a DataLoader. It takes an array of keys and returns one value per key, in the same order, with `null` for a missing key.
- Batching
- Running many separate lookups as one. DataLoader gathers all the `load` calls made at the same moment and runs one SQL query for them.
C
- Cache hit / cache miss
- A hit means a client answered a query from its cache without calling the server. A miss means the answer wasn't cached, so the request went to kc-graph.
- Cache-Control
- An HTTP reply header telling browsers and CDNs how long they may reuse a reply, for example `max-age=60`. It works by URL, so it suits REST GET routes better than the single GraphQL endpoint.
- CDN
- A content delivery network: servers around the world that keep copies of replies close to users. CDNs cache by URL, so they work well for REST GET routes and poorly for GraphQL POSTs.
- Code generation
- Tools that read your schema and write TypeScript types for every query automatically. This keeps client code in step with the API.
- Connection
- The standard shape for a cursor-paged list: `edges` (each with a `cursor` and `node`), `pageInfo`, and often `totalCount`. kc-graph's `productConnection` and `orders` use it.
- Context
- An object shared by every resolver during one request, passed as the third resolver argument. In kc-graph it holds the database, loaders, the logged-in user and the pub/sub.
- Context function
- A function Yoga calls once per request to build that request's context. It makes fresh loaders and reads the user from the Authorization header.
- CORS
- Cross-origin resource sharing. A browser sends an OPTIONS request first to ask whether a page may call an API on another site, which is why the /graphql route also accepts OPTIONS.
- CRUD
- Create, read, update, delete: the four basic data operations. REST is simple to use for APIs that only need CRUD on a few resources.
- curl
- A command-line tool for sending HTTP requests. With GraphQL it can POST a query to `/graphql`, and its `-N` flag turns off output buffering so a subscription stream can be watched as it arrives.
- Cursor
- An opaque string marking a place in a list. The client sends the last one it received as `after` to get the next page.
D
- data
- The key in a GraphQL reply that holds the results, shaped exactly like the query. It is missing when a validation error stops the query before it runs.
- DataLoader
- A small library from the GraphQL team that collects separate `load(key)` calls and answers them with one batch function, and caches each key's answer. kc-graph uses it to fix the N+1 problem for products.
- Default resolver
- The resolver GraphQL uses when you didn't write one for a field. It returns the parent's property with the same name as the field, such as `parent.name`.
- Default value
- The value an argument gets when a query leaves it out, written in the schema as `limit: Int = 20`. The resolver then always receives a value.
- Depth limit
- A rule that rejects queries nested too deeply (depth limit) or whose fields add up to too much work (cost limit). The `@escape.tech/graphql-armor` package adds both to Yoga, for example to reject queries deeper than a set number of levels.
- Description
- A string written just before a type or field in the schema, as `"..."` for one line or `"""..."""` for several. Clients see it as documentation, for example in GraphiQL's Docs panel.
- Document cache
- urql's cache. It stores whole replies under their query and variables, and drops a stored reply when a mutation returns a type it contains.
E
- Edge
- One item in a connection, holding the item itself as `node` and its `cursor`. The `node` field is the actual item, such as a `Product` or an `Order`.
- Endpoint
- The single URL where a GraphQL API receives every request, usually `/graphql`. In Yoga it is available as `yoga.graphqlEndpoint`.
- Enum
- A type whose value must be one of a fixed set of names, such as `Category` with COFFEE, MUG and NOTEBOOK. GraphQL rejects any other value.
- Error codes
- Short names in a GraphQLError's `extensions.code` that clients check instead of the message. kc-graph uses NOT_FOUND (no such item), BAD_USER_INPUT (client sent something wrong), UNAUTHENTICATED (nobody logged in, like HTTP 401), FORBIDDEN (wrong role, like HTTP 403), OUT_OF_STOCK (not enough stock) and BAD_STATUS_CHANGE (order can't move to that status).
- Event stream
- A connection that stays open while the server sends one result per event. A client asks for it with `Accept: text/event-stream`.
- Exchange
- In urql, a step every operation passes through in order. `cacheExchange` answers from the cache, and `fetchExchange` sends what's left over HTTP.
- extensions
- The part of a GraphQL error that carries extra details, such as a `code` like NOT_FOUND. Clients check the code instead of the message or HTTP status.
F
- Fastify
- A Node.js web framework with built-in logging, hooks and test support. Yoga can be mounted as one route of a Fastify app, so a GraphQL API like kc-graph gets those features, including tests with `app.inject`.
- Federation
- A way of joining the GraphQL APIs of several services into one combined API. It's mentioned as a next step with microservices.
- Field
- One named piece of data on a type that you can ask for, such as `name` or `items`.
- Field resolver
- A resolver on an object type that computes one field from its parent, such as `Product.price` formatting `priceCents` as "$55.00".
- Field-level authorization
- Checking a user's rights on a single field, not a whole operation. `Order.email` calls `requireStaff` so emails don't leak wherever an order appears.
- Fragment
- A named, reusable selection set, defined with `fragment Name on Type { ... }` and spread into a query with `...Name`.
G
- GraphiQL
- A browser-based editor, served by Yoga at /graphql, for writing and running operations. It suggests fields, underlines mistakes and shows the schema in a Docs panel.
- GraphQL
- A query language for APIs where the client names exactly the fields it wants from a single endpoint. The reply has the same shape as the query.
- graphql package
- The reference GraphQL implementation for JavaScript. Yoga uses it to parse and run queries, and you import `GraphQLError` from it.
- GraphQL Yoga
- A GraphQL server for Node.js made by The Guild. `createYoga` builds one from a schema.
- graphql-ws
- A library that carries GraphQL subscriptions over WebSockets. It is an alternative to server-sent events as a transport for subscriptions.
- GraphQLError
- The error class whose message and `extensions` code reach the client. Other errors are masked as "Unexpected error.".
H
- handleNodeRequestAndResponse
- The Yoga method that bridges Fastify's Node.js request and reply objects to Yoga's web-standard `Request` and `Response`. It lets Fastify still log requests and run hooks.
- HTTP status codes
- Numbers in an HTTP reply saying how it went. GraphQL replies are usually 200 OK even when they hold errors; REST uses 404 (not found) and 401 (not logged in), 403 means forbidden, and 406 Not Acceptable is what the browser gets when GraphiQL is off.
I
- Input type
- An object type used only for arguments, written with `input`, like `AddProductInput` bundling a new product's five values.
- Interface, union and custom scalar
- Three further kinds of GraphQL type: an interface (fields several types share), a union (a value that is one of several types) and a custom scalar such as `DateTime`. They are useful for more advanced schemas, though a simple API can do without them.
- Internal value
- The value your code sees for an enum, set in the resolver map. `Category: { COFFEE: "coffee" }` means `COFFEE` in queries becomes "coffee" in resolvers and SQL.
- Introspection
- A GraphQL API's ability to answer questions about its own schema. GraphiQL uses it for suggestions and docs, and production APIs may turn it off.
J
- JWT
- A signed token the server gives a user at login, which the client sends back on later requests to prove who they are. kc-graph's `login` mutation returns one made with `@fastify/jwt`.
K
- keyFields
- Apollo Client settings that say which fields identify an object in the cache. `Product` has no `id`, so `keyFields: ["sku"]` makes the SKU its key.
L
M
- Masked error
- Yoga hides the real message of an ordinary thrown `Error` and sends clients only "Unexpected error.", logging the details on the server. This stops leaks of SQL or file paths.
- Mutation
- An operation that changes data, written with the word `mutation` and defined on the `Mutation` root type. Mutation fields run one after another.
N
- N+1 problem
- One query for a list of N things, then one more query for each of them. Fifty orders of four items would take 251 SQL queries.
- node:sqlite
- Node's built-in module for SQLite, a database stored in a single file. Its `DatabaseSync` is synchronous, so queries return rows immediately.
- node:test
- Node's built-in test runner. It is used together with `node:assert/strict` to write tests, such as checking the replies of a GraphQL API.
- Non-null
- A type marked with `!`, such as `String!`, which promises the field is never `null`. If a resolver returns null anyway, GraphQL reports an error and nulls the parent.
- Normalized cache
- Apollo's cache. It splits replies into objects and stores each once under its type and key, so updating one object updates every query that shows it.
- Nullable
- A field type without `!`. By default every GraphQL field may be `null`, and a failed nullable field gives `null` for just that field.
O
- Object type
- A type made of named fields, such as `Product` or `Order`. Each field has its own type.
- Offset pagination
- Paging with `limit` (how many) and `offset` (how many to skip). It's simple, but pages shift if rows are added or removed between requests, and large offsets are slow.
- Opaque
- Not meant to be read or built by the client, like a cursor. The client only passes it back, so the server can change what's inside.
- Operation
- One query, mutation or subscription sent in a request.
- Operation name
- An optional name for an operation, such as `OneProduct`. It appears in logs, and is sent as `operationName` when the text holds several operations.
- Over-fetching
- Getting more data than a screen needs, such as every product field when the menu only shows name and price.
P
- Parent
- A resolver's first argument: the value returned by the field one level up. `Product.price` receives the product row as its parent.
- Partial data
- A reply holding both `data` and `errors`, which happens when a nullable field fails and the rest succeeds. Clients should always check `errors`, even when `data` has values.
- Persisted operation
- A query stored on the server and sent by a short id. It can limit an API to approved queries, and may allow cacheable GET requests.
- pipe and filter
- Yoga helpers for narrowing a stream. `filter(test)` keeps events where the test is true, and `pipe(stream, step)` runs a stream through it, so a subscription can filter by `sku`.
- Plugin
- An add-on, installed like an npm package, that gives Yoga extra behavior. Plugins can add depth limits, persisted operations or turn off introspection.
- Prepared statement
- A SQL statement written once with `?` placeholders, whose values are filled in when you run it. It keeps SQL safe from injection.
- Pub/sub
- Code publishes an event on a named channel, and every subscriber to that channel receives it. It connects `updateStock`, which publishes, to subscribers, who receive.
Q
- Query
- Text naming the fields a client wants. It's also the root type whose fields are where every read operation starts.
R
- Redis
- A data store that can share pub/sub channels between several servers. It's mentioned as the fix for in-memory subscriptions on one server.
- Relay
- Meta's GraphQL client, whose connection pattern (edges, nodes, pageInfo) most GraphQL APIs copy for cursor pagination.
- Request
- The web's standard request object that Yoga gives to the context function. `request.headers.get("authorization")` reads a header or returns `null`.
- requestPolicy / fetchPolicy
- Client options that say whether to use the cache. urql's `network-only` skips the cache, and Apollo's `cache-only` never asks the server.
- requireUser / requireStaff
- kc-graph helpers resolvers call first. `requireUser` throws UNAUTHENTICATED if nobody is logged in, and `requireStaff` also throws FORBIDDEN unless the role is staff.
- Resolver
- A function that produces one field's value, called with `parent`, `args`, `context` and `info`. It may be `async`, and GraphQL waits for it.
- Resolver chain
- Resolvers running level by level from the top of a query, each given its parent's result.
- Resolver map
- An object shaped like the schema, with a key per type and a function per field. Yoga reads it to know which function answers each field.
- REST
- The URL-per-resource style of API that GraphQL is compared with, where each URL returns a fixed reply. It's simpler for CRUD and caches well by URL.
- Root type
- `Query`, `Mutation` or `Subscription`: the types where every operation starts.
- Round trip
- A request and its reply crossing the network. Each extra REST call on the order page adds another one.
S
- Scalar
- A single-value type with no fields of its own. GraphQL has five built in: Int, Float, String, Boolean and ID.
- Schema
- The description of every type and field an API offers. It's the contract between server and clients.
- SDL
- Schema Definition Language: the short text language used to describe types, such as `type Product { sku: ID! }`.
- Selection set
- The fields in braces after a field or operation, saying which fields you want. Object-type fields need one; scalar fields can't have one.
- Server-sent events
- One HTTP response that stays open while the server sends events down it, one `data:` line each. Yoga uses it to deliver subscriptions.
- subscribe and resolve
- The two functions of a subscription field's resolver. `subscribe` returns the stream of events, and `resolve` turns each event into the field's value.
- Subscription
- An operation where the client subscribes once and the server pushes a new result each time something happens. It's the third root type.
T
- Tag
- A function placed before a template string, as in urql's and Apollo's `gql`. It receives the string and turns it into a parsed query document.
- Transaction
- A group of database changes that all happen or none do. SQL's `BEGIN` starts it, `COMMIT` saves every change, and `ROLLBACK` undoes them if something fails; `placeOrder` uses one so the order, its lines and the stock change save together.
- TypeScript type stripping
- Node 22.18 and later removes TypeScript types as it runs a `.ts` file, so `node src/server.ts` works without a build step. `npx tsc` still checks the types.
U
- Under-fetching
- Getting too little from one request, so the client must make more. The order page needs one extra REST call per item to get its name.
- urql
- A small GraphQL client library with a document cache, built from a `Client` and a list of exchanges. It suits most apps.
V
- Validation error
- An error raised when a query breaks the schema's rules, such as asking for a field that doesn't exist. The query never runs, and the reply has no `data` key.
- Variable
- A value sent next to a fixed query instead of pasted into its text. It's declared with `$`, like `$sku: ID!`, and sent as JSON under `variables`.