GraphQL Persisted Queries & Query Depth Limiting

Stack: SOFTWARE ARCHITECTURE STACK →Senior (L5)pattern

⚡THE SHORT ANSWER

GraphQL persisted queries and query depth limiting protect production APIs from denial-of-service attacks and severe database overload by restricting client queries to pre-approved cryptographic hashes and rejecting maliciously nested object graphs.

Engineering Handbook & Failure Dynamics

6-Dimensional Architecture Breakdown

⚙️1. Underlying Mechanism

Execution

While GraphQL gives frontend engineers extreme query flexibility, exposing an arbitrary query execution engine to the public internet introduces severe vulnerabilities. An attacker can submit deeply nested circular queries (author { posts { author { posts { ... } } } }) that spawn millions of database joins in a single HTTP POST. In production, teams enforce query depth limits and replace dynamic query strings with Persisted Queries.

🎯2. Appropriate Use Context

Scope

Persisted Queries is a security and performance pattern where GraphQL query strings are extracted during the client build process, hashed into unique identifiers (SHA-256), and stored in an allowlist on the API Gateway; clients only transmit the hash at runtime.

⚠️3. Production Failure Modes

P0 Risk

Deploying raw GraphQL endpoints to production without depth limiting or query complexity validation. Allowing public unauthenticated clients to run arbitrary ad-hoc GraphQL mutations. Relying solely on frontend minification to prevent users from modifying GraphQL queries in browser devtools.

📡4. Diagnostic Signals & Telemetry

Telemetry

deeply nested malicious GraphQL query crashes database, unbounded circular relation query causes server OOM, massive raw GraphQL query payload bandwidth bloat

🛡️5. Prevention & Safeguards

Safeguards

Enable Automatic Persisted Queries (APQ) with CDN caching on HTTP GET requests for high-traffic read queries. Set strict depth limits (typically 5 to 7 levels) and assign pagination multiplier costs to all list resolvers. Disable introspection (__schema / __type) in public production environments to prevent automated schema scraping.

⚖️6. Architectural Trade-offs

Trade-off

Without persisted queries and AST depth analysis, a public GraphQL endpoint acts as an open proxy for un-metered database extraction, allowing malicious actors to exhaust backend CPU threads with a single 2KB payload.

📋

Case Study (TinyCTO In-Field Example)

REAL-WORLD TELEMETRY

Production GraphQL hardening requires a multi-layered defense strategy:

▸
Query Depth Limiting: Before executing a query, the GraphQL engine parses the Abstract Syntax Tree (AST) and calculates the maximum depth. A query exceeding a strict threshold (e.g. depth > 6) is rejected with an HTTP 400 before resolving a single database row.
▸
Query Complexity & Cost Analysis: Each field in the schema is assigned a complexity score (e.g., scalar = 1, paginated list = 1 * limit). If the total computed score exceeds the client's allocated budget (e.g. max cost 1000), the request is aborted.
▸
Strict Persisted Queries (Safe Mode): In native mobile and web production builds, the GraphQL server is placed in 'allowlist-only' mode. Dynamic query strings are strictly forbidden; requests without a known queryId or sha256Hash in Redis/server memory are instantly dropped at the edge.

Interactive Concept Drills

2 Cards

What is the primary security vulnerability of unconstrained production GraphQL endpoints?

Arbitrary nested and circular queries that force massive exponential database joins, causing severe CPU exhaustion and denial of service.

How do Persisted Queries turn GraphQL POST requests into cacheable HTTP GET requests?

By replacing the large query string with a short hash passed as a query param (e.g. `?extensions={"persistedQuery":{"sha256Hash":"..."}}`), allowing CDNs to cache responses.