Glossary

Several of these words mean something narrower here than they do in general use. Where that is true, the entry says so.

Billing account

What pays for GraphPilot: it holds the plan, any add-ons and the usage. One billing account can fund several organizations, and plan limits such as the request quota are counted across all of them. Managed in the portal on an organization’s Billing page. See billing.

Bucket

Which partition an entry belongs to: public, private, a named scope’s, or platform (requests GraphPilot itself sent). A response that selected fields from several is keyed on all of them. The bucket is part of what a lookup matches on, so entries in different buckets never meet, and it is chosen when the response is stored. See when a response is cached.

Bypass

A policy expression that, when it matches, sends a request straight to your origin without consulting the cache and without storing the answer. Reported as PASS with CACHE_PASS_BYPASS_POLICY.

Cache key

What identifies one cache entry. It is not the same thing as a surrogate key. See the cache key.

• HTTP: the request method and the path, query string included, such as GET:/products/42?color=blue. A request that carries a body is keyed by a SHA-256 of the body as well, such as POST:/search#<sha256 of the body>. Scheme and hostname are left out unless the service sets cache.http_key.host = "include", which keys by the full URL, such as GET:https://catalog-api.k7m2qp.graphpilot.cloud/products/42.
• GraphQL: the path and the query string without the GraphQL parameters, then a SHA-256 of the query text exactly as sent, plus the operation name and a hash of the variables when present, such as /graphql?locale=de#<sha256>#GetProduct:<variables hash>. The method is not part of it, so POST, GET and QUERY on one route share one entry. Telemetry and the ck: surrogate key carry it without the route. Up to runtime 1.4.0 the key has no route: it starts at the SHA-256.

Caller

The identity behind one request: the person, token or API key it carries. Two callers using the same client can see different data, which is why a private cache entry is partitioned per caller. Compare client.

Client

The application that sends requests to your service: your web app, a mobile app, a partner integration, the gpilot CLI. GraphPilot recognizes a client only if you declare it in a client profile. Compare caller. See telling your clients apart.

Customer

In examples, one of your customers: a tenant of the application you run behind GraphPilot, as in x-customer-id or “one shared entry per customer”. Not a GraphPilot account; that is an organization.

Deployment

One version of a service’s schema and configuration, built and rolled out to the edge. Created with gpilot deploy or from the portal, which lists them under Deployments. See deployments and Deployments in the portal.

Deployment build

The step at the start of a deployment that compiles your schema and configuration into the package the edge runs. It checks both, derives the surrogate key and cache rules from the schema, and reports anything it refused or ignored as diagnostics, which the portal shows under findings.

Discriminator

The value a public or private policy expression resolves to, which partitions an entry inside its bucket. It never reaches your origin or the cached response.

Edge location

One of the points of presence of Fastly’s edge network, which GraphPilot runs on. Each holds its own cache, so a response stored at one is not stored at another. Purges, by contrast, reach all of them. See edge locations.

Effective policy

The caching policy that applies to one response, resolved across everything the operation selected. For @cacheControl this is the minimum maxAge across the selection, and the union of every selected field’s discriminators, which is the narrowest audience all of them allow. See lifetime from the schema.

Empty-list key

A surrogate key of the form ![Typename], tagged on a response whose list of that type came back empty. It exists so that creating the first object of a type can invalidate the cached “there are none” answer. See automatic invalidation.

Entity key

A surrogate key naming one object, such as Product:id:1. Derived from key fields found in the response body, and one of only two kinds a mutation purges automatically.

Freshness lifetime

How long an entry may be served without going back to your origin. Comes from s-maxage or max-age on the origin’s Cache-Control, or from @cacheControl(maxAge:) when the origin sent no Cache-Control header, or one that says nothing about storing or ageing the response (a bare private, public or no-transform; must-revalidate, immutable or a stale-* directive on its own does count). Often called the TTL. See how long an entry lives.

Insights

The portal’s view of your request telemetry: every request, its cache status, reason code, latency and origin details, with filters and charts. Part of every plan; plans differ in list columns, filters and how far back you can look. What is stored is on what Insights needs.

Lean mode

What every service a billing account funds switches to when the account is lean: on Glider (Free), once its included request units for the period are used up; on any plan, while a renewal payment is overdue or when GraphPilot pauses the account. Edge caching is withdrawn: every request goes to your origin and nothing is stored, and no gp-cache header is sent on responses the cache would otherwise have looked up. Authentication, request signing and purging keep running, and request telemetry is not stored. Lean mode keeps the services serving; on Glider, only fair use can lock the account for the rest of the month. See quotas.

Log line

A warning or error GraphPilot writes while handling a request, carrying a stable code such as AUTH_KEY_MATERIAL_UNAVAILABLE. A decision or refusal code (CACHE_STORED, INGRESS_RESERVED_HEADER_DROPPED, GRAPHQL_INVALID_QUERY, …) is not written as a line: it is recorded on the request itself, with the detail the line used to carry (the blocking header or cookie, for example), and listed under Edge codes in the Overview tab of a request’s detail in Insights. When these docs say a code appears “in your logs”, they mean either of the two. Log lines are not shown in the portal; read them through the API’s Service.logs. Both are stored under the same rules as request telemetry (see Insights). See codes.

Organization

The workspace your services, members and API keys belong to. Members are invited to an organization and act in it with a role. One billing account can fund several organizations. See organizations and members.

Origin

The server your service forwards requests to. Its URL is a property of the service, not of the configuration file.

• HTTP: any API that answers over HTTP. Caching follows its Cache-Control, and its Surrogate-Key header names keys.
• GraphQL: a GraphQL API on the paths in request.graphql_paths. Its schema adds lifetimes, scopes and keys through directives.

Only the URL’s scheme, host and port are allowed; without a port, GraphPilot connects to port 443 for https:// and 80 for http://. See TLS to your origin.

Persisted query

An operation the service already knows, sent by the client as a hash instead of a document. Either registered by clients at runtime (APQ) or pushed from a manifest you control. See persisted queries.

Policy expression

The small language used by cache.policy.public, private, vary[].value, bypass, client profiles and conditional response filters. Reads verified claims, headers, cookies and query parameters; returns a string or nothing. See the reference.

Provider

A configured way of verifying one kind of credential, named so a policy expression can address its claims as auth:<name>.<claim>. Two types exist: jwt and api_key. See authentication.

Purge

Removing entries from the cache by naming a surrogate key. A hard purge removes the entry; a soft purge marks it stale so a revalidation serves rather than a miss. Purges reach every edge location.

Selection set expansion

Injecting the fields needed to derive surrogate keys into a query, then stripping them from the response before it reaches the client. It is why clients never have to select id for invalidation to work. See selection set expansion.

Service

One origin behind GraphPilot, with its own hostname, configuration and cache: an origin URL, a service hostname, a configuration and its deployments. An organization can have many.

A GraphQL service deploys with gpilot.toml and a schema.graphql, which the deployment build reads for directives and key fields.

A plain HTTP service deploys with gpilot.toml alone. Without a schema, GraphQL features are off and every path is served as plain HTTP.

Hostname label

The six characters between a service’s subdomain and graphpilot.cloud in its service hostname, such as k7m2qp in checkout-api.k7m2qp.graphpilot.cloud. GraphPilot generates one per organization; it is the same for every service of the organization, never changes, and is never given to another organization. See the hostname label.

Service hostname

The address GraphPilot issues for a service, https://<subdomain>.<label>.graphpilot.cloud, where <label> is the organization’s hostname label. A service created before labels existed keeps https://<subdomain>.graphpilot.cloud, or answers on both while it is moved onto its label. Your clients send their requests there instead of to your origin, and the portal shows it for each service. A custom domain can stand in front of it.

Skip

A response the cache looked for, missed, fetched, and then declined to store, with a CACHE_SKIPPED_* reason. Always reported as PASS, because nothing was stored, whether the request or the response ruled caching out or storing it failed inside GraphPilot. Distinct from a lookup-time pass (CACHE_PASS_*), where the response was neither served from nor written to the cache.

Surrogate key

A label attached to a cache entry so that entries can be removed as a group later. Several kinds exist, and the kind decides whether a mutation purges it automatically. See surrogate keys.

Vary rule

A [[cache.policy.vary]] entry that derives a value and writes it onto the request as a header. Every response is partitioned on it, plain HTTP included, whether or not your origin’s Vary names the header. A rule marked scope_only is the exception: a response your schema decided is partitioned on it only when its scope names it in @vary. A request the expression does not resolve for is stored as the variant without the header. See who shares an entry.