Query Cost Analysis and Budgets

Depth Counts Nesting, Money Counts Work

A depth limit says how tall a query can be; it says nothing about how much work it causes. Two documents at depth 3 differ by orders of magnitude: { posts { author { name } } } reads three columns, while the same shape over a list field with an unbounded page size reads thousands of rows and joins them.

Cost analysis replaces the structural guess with an arithmetic model. Every field has a base weight (default 1), a field that resolves from an expensive source overrides it with @cost(weight: N), and when a field returns a list, the cost of its entire sub-selection is multiplied by the list size. The operation's cost is the sum over the whole selection tree.

Walk a real one. shippingEstimate calls a pricing service, so it is weighted; reviews is annotated with an assumed page of 5; products takes a slicing argument:

type Query {
  products(first: Int!): [Product!]! @listSize(slicingArguments: ["first"])
}
type Product {
  id: ID!                                  # weight 1
  name: String!                            # weight 1
  shippingEstimate: Int! @cost(weight: 20) # weight 20 — calls pricing
  reviews: [Review!]! @listSize(assumedSize: 5)
}
type Review { rating: Int! }

The same operation with only id and name selected scores 7. Nothing about depth distinguishes 7 from 97 — argument values, list sizes, and field weights do. That is the point: cost is a proxy for work, so a budget is a proxy for capacity.

Annotating the Schema So Estimates Are Honest

The gateway cannot know list sizes before execution, so it must estimate — and an estimate is only as good as the schema metadata behind it. Three directives carry that metadata:

type Query {
  # size comes from the argument the client actually sends: first: 25 → multiplier 25
  products(first: Int!): [Product!]! @listSize(slicingArguments: ["first"])

  # fixed, predictable size — no pagination argument exists
  bestsellers: [Product!]! @listSize(assumedSize: 5)

  # cursor connection: the slicing args size Connection.edges, not Connection itself
  search(q: String!, first: Int!): ProductConnection!
    @listSize(slicingArguments: ["first"], sizedFields: ["edges"])

  # arbitrary list input: length of the ids argument is the multiplier
  productsByIds(ids: [ID!]!): [Product!]! @listSize(slicingArguments: ["ids"])
}

• slicingArguments is the accurate one: the client's own pagination argument becomes the multiplier, so a query asking for 50 items is scored as 50 items. Without it, every list falls back to a configured default assumed size, and a schema with unpaginated list fields will be both over- and under-estimated.
• sizedFields exists because connection types wrap the list: search(first: 25) should scale edges, not the single connection object.
• @cost(weight: N) replaces the default field weight. Use it where work is genuinely disproportionate — an estimate call, an external API hop, a full-text scan — not to punish fields you merely dislike.

Estimate versus actual is a measurable gap. The only difference between them is list size: the estimated run uses assumed sizes, the actual run uses what the subgraphs returned. Run enforcement in measure mode first and compare the two distributions per operation. If search consistently estimates 300 and returns 40, your default assumed size is wrong, not your budget. Tune @listSize on the outliers, then enforce.

Budgets, Errors, and Rollout

A weight model without a ceiling is just telemetry. The budget is a maximum cost per operation: the gateway statically scores the document before execution, and anything over the limit is rejected without a single subgraph call.

# gateway configuration (Apollo Router-style)
demand_control:
  mode: enforce                # start in measure, flip to enforce after a week
  strategy: static_estimated
  max: 1000                    # per-operation ceiling
  list_size: 10                # fallback for list fields with no @listSize

Rejection must be typed and machine-readable, because the client has to do something with it:

{
  "errors": [{
    "message": "Operation exceeds the cost budget of 1000 (estimated 4820)",
    "extensions": { "code": "COST_ESTIMATED_TOO_EXPENSIVE", "cost": 4820, "maxCost": 1000 }
  }]
}

With a code, the mobile client can fall back to a lighter document or page results differently; without one, it retries the same query in a loop and turns your budget into an outage. Log the operation name alongside the rejection so you know which client shipped an unbounded query.

Three rollout rules keep this from becoming a support ticket generator:

1. Measure before you enforce. A week of cost histograms tells you whether the ceiling is 100 or 10,000, and which operations sit closest to it.
2. Budget per operation, not per field. Field-level limits are trivially bypassed by combining ten moderately priced fields — the total is the only number an attacker cannot split.
3. Watch the rejection rate as a client-quality metric. A spike means a new client release sends an unbounded document; a permanent trickle means some legitimate query needs a cheaper shape or a higher weight annotation.

Budgets compose with the structural guards rather than replacing them: depth limits reject pathological nesting in microseconds, and cost analysis catches the expensive documents that nest perfectly well.