GraphQL glossary

Plain-English definitions of the GraphQL terms you meet when you run an API in production, from schema and resolvers to federation, caching, and security.

Alias

A client-supplied name for a field in the response. Aliases let one query request the same field more than once with different arguments, and rename fields to avoid collisions. Because they multiply how often a field runs, unbounded aliasing is also a common abuse vector.

API gateway

A single entry point that fronts one or more backend services, centralizing cross-cutting concerns like authentication, rate limiting, and routing. In GraphQL, a federated gateway is a specialized API gateway that also composes a supergraph.

Argument

A named input passed to a field or directive to parameterize what it returns, for example an id or a pagination cursor. Arguments are declared in the schema with a type and may carry default values.

Automatic Persisted Queries (APQ)

A handshake that lets clients use persisted queries without registering them ahead of time. The client first sends a hash of the query; if the server does not recognize it, the client resends the full query once so the server can store it. After that, requests carry only the hash, which shrinks payloads.

Backend for Frontend (BFF)

A backend service tailored to one client, such as a web or mobile app, that shapes and aggregates data for that client's needs. GraphQL is a common way to build a BFF because clients select exactly the fields they want.

Batching (DataLoader)

A technique that collects the many small data lookups made within one request and resolves them together, instead of one query per item. It is the standard fix for the N+1 problem and is usually implemented with a DataLoader-style layer.

Cache hit and cache miss

A cache hit is a request answered directly from cache; a cache miss is one the cache cannot serve, so it falls through to the origin. The balance between the two is the main signal of how well a cache is working.

Cache hit rate (CHR)

The share of requests served from cache rather than the origin, usually expressed as a percentage. A higher rate means more traffic is absorbed before it reaches your servers. See whether caching is actually helping.

Cache invalidation

Removing or refreshing cached responses once the underlying data changes, so clients do not see stale results. For GraphQL this is hard because one endpoint serves many shapes of data, so tying invalidation to the types or entities a response depends on is more precise than time based expiry. See edge caching.

Cache key

The identifier a cache uses to decide whether two requests can share a result. For GraphQL the key is built from the operation, its variables, and relevant context, not the URL. See query normalization.

Complexity analysis

Estimating how expensive a query will be before it runs, by weighting fields, nesting, and list multipliers. The estimate lets you reject queries over a budget and rate limit by cost rather than by request count. See security at the edge.

Content delivery network (CDN)

A network of servers spread across regions that cache and serve content close to users, cutting the distance each request travels. Traditional CDNs key on method, host, URL, and sometimes headers, so plain GraphQL, where almost everything is a POST to one endpoint, gains little from default URL-based caching without a GraphQL-aware layer (though GET-based persisted queries can make it more CDN-friendly). See edge caching.

Denial of service (DoS and DDoS)

An attack that overwhelms a service so it cannot serve legitimate users. In GraphQL a single deeply nested or expensive query can act as a denial of service, which is why depth and cost limits matter. See security at the edge.

Deprecation

Marking a schema field or enum value as obsolete with the @deprecated directive and a reason, so clients are warned to migrate while the field keeps working. Deprecating instead of removing avoids breaking existing clients.

Directive

An annotation in a schema or query, written with an @ prefix such as @deprecated or @include, that changes how a field or type is validated, executed, or composed.

Distributed tracing

Following a single request as it moves through services and resolvers, recording timing at each step. For GraphQL, per-resolver traces reveal slow fields and N+1 patterns that endpoint metrics hide. See observability.

Edge (edge network)

The layer of servers positioned close to users, away from your central origin. Running caching and security at the edge means requests are handled near the client and far from your core infrastructure. See edge caching.

Edge caching

Storing GraphQL responses on servers close to your users so repeat reads are served without reaching the origin. Because GraphQL is usually a POST to one endpoint, edge caching needs a GraphQL-aware layer that keys on the operation and variables. See how GraphPilot caches at the edge.

Endpoint

The single URL a GraphQL API is served from, which every operation is sent to, typically by POST. Because one endpoint handles all queries, perimeter tools that key on the URL cannot tell requests apart.

Enum

A type whose value must be one of a fixed set of named options, for example an OrderStatus of PENDING, SHIPPED, or DELIVERED. Enums document and constrain the allowed values in the schema.

Federation

An approach to building one GraphQL API, a supergraph, out of multiple independently owned services called subgraphs. Each subgraph declares how its types relate to others, and a gateway composes them into a single API.

Field

A unit of data you can request on a type. Fields can take arguments and return scalars or other types, and each field is backed by a resolver that produces its value.

Fragment

A reusable selection of fields that can be spread into multiple queries to reduce duplication. Inline fragments also let a query select fields conditionally based on a concrete type within an interface or union.

Gateway

The entry point in a federated setup that receives client queries, plans how to fetch each part from the relevant subgraphs, and composes a single response. It is where cross-cutting concerns like caching and security are best applied.

GraphQL

A query language and runtime for APIs in which the client specifies exactly which fields it needs and receives a matching response from a single endpoint. It is defined by a typed schema and is transport agnostic, though it most often runs over HTTP.

GraphQL CDN

A CDN that understands GraphQL, so it caches responses keyed by the operation and variables instead of by URL. Better ones also invalidate per type or entity when data changes, rather than relying on TTL alone. It brings CDN-style edge caching to an API where ordinary CDNs are blind. See edge caching.

GraphQL over HTTP

The conventions for sending GraphQL operations over HTTP, typically a POST with a JSON body, though safe read-only queries can use GET. Because most clients use POST to one endpoint, URL based caching does not work without a GraphQL-aware layer.

Interface

An abstract type that defines a set of fields other types must implement. A field can return an interface, letting clients select the common fields and then use fragments for type-specific ones.

Introspection

A built-in capability that lets a client query the schema itself to discover its types and fields. It powers tooling like autocomplete, but in production it also helps attackers map your API, so teams often restrict it. See should I disable introspection?

Latency

The time between a client sending a request and receiving a response. Serving cached reads close to users lowers latency without changing your resolvers. See edge caching.

List type

A type modifier, written [Type], indicating a field returns an ordered collection. Lists multiply the work behind a query, so list fields are usually paginated and weighted in complexity analysis.

Mutation

An operation that changes server-side data, such as creating or updating a record, and returns a result. Mutations are the write counterpart to queries, and a mutation's top-level fields run serially, one after another, rather than in parallel.

N+1 problem

A performance pitfall where resolving a list triggers one extra data fetch per item, turning a single request into many round trips. It is typically solved with batching. See why is my API slow even when my database is fast?

Normalized cache

A client-side cache that splits responses into individual objects identified by a stable key, typically __typename plus id (since id alone can collide across types) or a configured key, so the same entity is stored once and updates everywhere. Used by libraries like Apollo Client and urql, it is separate from server-side or edge caching.

Nullability

Whether a field may return null. A trailing ! marks a field non-null, meaning the server guarantees a value; otherwise null is allowed. Nullability also affects how errors propagate through a response.

Operation

A single executable request against a GraphQL API: a query, mutation, or subscription, optionally with a name and variables. Naming operations improves logging, caching, and per-operation monitoring.

Origin

Your own GraphQL server, the source of truth behind any cache or proxy. The point of edge caching is to keep repeat reads from reaching the origin, so it only handles requests that genuinely need fresh data.

Partial query caching

Caching individual parts of a response, such as specific types or fields, instead of only whole responses. It raises the cache hit rate because a query can be partly served from cache even when some fields still have to be fetched fresh. See edge caching.

Payload

The body of a GraphQL request or response: the query, variables, and operation name going in, and the data and errors coming back. Trimming oversized payloads is a common performance win.

Persisted query

A query whose text is registered ahead of time and referenced by an id, so clients send the id instead of the full document. This shrinks requests and, when the allowlist is enforced, blocks arbitrary queries.

Point of presence (PoP)

A location in an edge network where servers handle nearby traffic. The more points of presence a network has, the closer it can sit to users, which is what keeps edge-served responses fast.

Purging

Actively removing entries from a cache so the next request is served fresh, rather than waiting for them to expire. Precise purging targets only the entries affected by a change. See cache invalidation.

Query

A read-only operation that fetches data. The shape of the query mirrors the shape of the response, and the client requests only the fields it needs.

Query normalization

Rewriting equivalent queries into one canonical form before building a cache key, so requests that differ only in formatting, whitespace, or field order share the same cached result. It raises the cache hit rate by collapsing differences that do not change the response, while keeping meaningful ones like aliases and arguments distinct.

Rate limiting

Capping how much a client can request over time. For GraphQL, limiting by query cost rather than by request count is more effective, since one heavy query can outweigh many cheap ones. See edge security.

Resolver

A function that produces the value for a single field, fetching from a database, another service, or a computation. The set of resolvers executed for a request determines most of its cost.

Reverse proxy

A server that sits in front of your origin and handles incoming requests on its behalf, often adding caching, security, or routing. A GraphQL edge proxy is a reverse proxy that understands GraphQL.

Scalar

A leaf value type that holds concrete data rather than other fields, such as Int, Float, String, Boolean, and ID. Schemas can also define custom scalars like DateTime.

Schema

The typed contract of a GraphQL API: every type, field, and operation it exposes. The schema is the single source of truth that clients query against and that tooling validates against. GraphPilot is schema-driven.

Schema Definition Language (SDL)

The human-readable syntax for writing a GraphQL schema, declaring types, fields, and directives in plain text. SDL is the common format for sharing and versioning a schema.

Schema registry

A central store that holds the canonical versions of your schema, or subgraphs, and validates changes against what is live. It is how teams catch breaking changes before they ship. See preventing breaking changes.

Schema stitching

An older way to combine multiple GraphQL schemas by merging them at the gateway, which then holds the rules for how types relate. Federation has largely replaced it for large, multi-team graphs.

Stale-while-revalidate (SWR)

A caching strategy that serves a slightly stale cached response immediately while fetching a fresh one in the background. Clients get a fast answer and the cache updates itself without anyone waiting on the origin. See edge caching.

Subgraph

An individual GraphQL service that contributes part of a federated graph, owned by one team. Each subgraph publishes its own schema and declares how its types connect to others.

Subscription

An operation that streams data to the client over a long-lived connection, pushing updates as events happen rather than on request. Subscriptions power live features such as notifications and activity feeds.

Supergraph

The single composed schema that a gateway builds from all subgraphs, presenting one unified API to clients even though many services back it.

Time to live (TTL)

How long a cached response is treated as fresh before it expires. A short TTL keeps data current but lowers the cache hit rate; pairing TTLs with invalidation lets you cache for longer without serving stale data.

Union

An abstract type that can be one of several object types which need not share any fields. Clients use inline fragments to select fields per possible type.

Variables

Typed values supplied separately from the query text so the same operation can run with different inputs. Keeping operations static this way improves caching and security.

Web Application Firewall (WAF)

A filter that inspects HTTP traffic to block common attacks. Modern WAFs can inspect request bodies and JSON, but without understanding the GraphQL query itself (its cost, aliases, fragment structure, and which fields it touches) they detect GraphQL-specific abuse only weakly, which is why GraphQL needs query-aware security.