title: Automatic Persisted Queries (APQ) Specification description: - Reduced Bandwidth: Send 64-character hash instead of multi-kilobyte queries keywords: ["format", "compliance", "protocol", "specification", "standard"] tags: ["documentation", "reference"]
Automatic Persisted Queries (APQ) Specification¶
Status: Stable Version: 1.0 Last Updated: 2026-01-11
Overview¶
Automatic Persisted Queries (APQ) is a protocol for optimizing GraphQL requests by allowing clients to send only a stable hash instead of the full query string. FraiseQL provides comprehensive APQ support with three distinct security modes and multiple storage backends for the query hash→query string mapping.
Key Benefits¶
- Reduced Bandwidth: Send 64-character hash instead of multi-kilobyte queries
- Query Allowlisting: Enforce only pre-approved queries in production
- Query String Storage: Persistent hash→query mapping across restarts and instances
- Security: Cryptographic validation of query integrity
- Production Safety: Prevent arbitrary query injection attacks
- Compatible with Query Result Caching: Works seamlessly with optional response caching layer (see Caching Specification)
Architecture¶
<!-- Code example in TEXT -->
Client
↓
APQ Request (hash ± optional query for registration)
↓
FraiseQL Router
├─ [Mode Enforcement] Check if arbitrary queries allowed
├─ [Hash Validation] Extract and validate SHA-256 hash
├─ [Query Resolution] Look up query string in APQ store
│ ├─ If registration: Store hash→query mapping for future use
│ └─ Get full query string from storage
├─ [Query Result Cache Lookup] (Optional) Try cached result
├─ [GraphQL Execution] Parse, validate, execute query with variables
└─ [Store Result Cache] (Optional) Cache query result if enabled
↓
Return Result (from cache or freshly computed)
Important: APQ vs Query Result Caching¶
APQ (this specification): Stores the hash → query string mapping. Clients send only the 64-character hash instead of the full query string, reducing bandwidth. The server looks up the full query before execution.
Query Result Caching (separate feature, see Caching Specification): Optionally caches the computed results of queries to avoid re-execution. This is a completely separate feature that works alongside APQ.
How they work together:
- Client sends: APQ hash + variables
- Server looks up query string from hash
- Server checks query result cache with (query + variables)
- If cache hit → return cached result (fastest path, no execution)
- If cache miss → execute query with variables → optionally cache result
This spec focuses on APQ (steps 1-2). See the Caching Specification for query result caching (steps 3-5).
Security Modes¶
FraiseQL supports three APQ security modes, allowing you to balance flexibility with security based on your deployment environment.
OPTIONAL Mode (Default)¶
Configuration:
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_mode="optional"
)
Behavior:
- ✅ Accepts both persisted query hashes and full query strings
- ✅ Allows new query registration (hash + query) on first request; the query must
hash to
sha256Hash(see Hash Mismatch below) - ✅ Automatically stores queries for future hash-only requests
- ✅ Useful for development and gradual client migration
Request Examples:
First request - register and execute:
<!-- Code example in JSON -->
{
"extensions": {
"persistedQuery": {
"version": 1,
"sha256Hash": "e4c7e8f5a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7"
}
},
"query": "query { users { id name } }"
}
Subsequent request - hash only:
<!-- Code example in JSON -->
{
"extensions": {
"persistedQuery": {
"version": 1,
"sha256Hash": "e4c7e8f5a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7"
}
}
}
Use Cases:
- Development environments
- Client SDKs during initial rollout
- Mixed deployment scenarios (some clients updated, others not)
REQUIRED Mode¶
Configuration:
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_mode="required"
)
Behavior:
- ✅ Only runs persisted queries the server already knows: loaded from
apq_queries_dirat startup, registered by the operator (register_queries/store_persisted_query), or already in thepostgresqlbackend's table - ❌ Rejects all arbitrary (non-hash) queries
- ❌ Clients cannot register queries: a request with a hash the server doesn't know
and the query text is refused (
PERSISTED_QUERY_NOT_IN_LIST), and nothing is stored - ✅ A query text sent with a hash must hash to it (see Hash Mismatch below), so a known hash always runs the text the server stored
- ✅ Prevents query injection attacks and unauthorised GraphQL exploration
- ❌
POST /graphql/rust(whenenable_rust_endpoint=True) takes query text only, so it refuses every request withARBITRARY_QUERY_NOT_ALLOWED
Request Examples:
Hash-only request (runs if the hash is registered):
<!-- Code example in JSON -->
{
"extensions": {
"persistedQuery": {
"version": 1,
"sha256Hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
}
}
}
An unknown hash gets the usual PERSISTED_QUERY_NOT_FOUND. An Apollo client then
sends the hash with the query text once; in required mode that request gets:
<!-- Code example in JSON -->
{
"errors": [
{
"message": "PersistedQueryNotInList",
"extensions": {
"code": "PERSISTED_QUERY_NOT_IN_LIST",
"details": "This server only runs pre-registered persisted queries (apq_mode='required'); this hash is not registered."
}
}
]
}
The code is neither PERSISTED_QUERY_NOT_FOUND (the client would send the text again)
nor PERSISTED_QUERY_NOT_SUPPORTED (the client would stop sending hashes).
Arbitrary query (REJECTED):
<!-- Code example in JSON -->
{
"query": "query { __schema { types { name } } }"
}
Response to Rejected Request:
<!-- Code example in JSON -->
{
"errors": [
{
"message": "Persisted queries required. Arbitrary queries are not allowed.",
"extensions": {
"code": "ARBITRARY_QUERY_NOT_ALLOWED",
"details": "Configure your client to use Automatic Persisted Queries (APQ) or register queries at build time."
}
}
]
}
Use Cases:
- Production environments
- Regulated industries (compliance/audit requirements)
- High-security deployments
- Preventing introspection-based attacks
DISABLED Mode¶
Configuration:
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_mode="disabled"
)
Behavior:
- ✅ Accepts only full query strings (regular GraphQL requests)
- ❌ Completely ignores APQ extensions
- ❌ Queries with APQ hashes are treated as regular requests
- ✅ Useful when APQ infrastructure is not needed
Request Examples:
Regular query (processed normally):
<!-- Code example in JSON -->
{
"query": "query { articles { id title content } }"
}
APQ request with hash (treated as regular, hash ignored):
<!-- Code example in JSON -->
{
"extensions": {
"persistedQuery": {
"version": 1,
"sha256Hash": "..."
}
},
"query": "query { articles { id title content } }"
}
APQ hash-only request (FAILS - no query):
<!-- Code example in JSON -->
{
"extensions": {
"persistedQuery": {
"version": 1,
"sha256Hash": "..."
}
}
}
Response to Hash-Only Request:
<!-- Code example in JSON -->
{
"errors": [
{
"message": "No query provided",
"extensions": {"code": "GRAPHQL_PARSE_FAILED"}
}
]
}
Use Cases:
- Backward compatibility during migration
- Environments without APQ infrastructure
- Explicit opt-out of APQ features
Query Hash Generation¶
FraiseQL uses SHA-256 hashing for deterministic query identification and security validation.
Hash Algorithm¶
<!-- Code example in Python -->
import hashlib
def compute_query_hash(query: str) -> str:
"""Compute SHA-256 hash of a GraphQL query."""
return hashlib.sha256(query.encode("utf-8")).hexdigest()
Properties:
- Algorithm: SHA-256 (FIPS 180-4 standard)
- Output Length: 64 hexadecimal characters (256 bits)
- Deterministic: Same query → same hash
- Collision Resistant: Different queries produce different hashes (cryptographically guaranteed)
- Case Sensitive:
{ user { id } }≠{ user { ID } } - Whitespace Sensitive:
{user{id}}≠{ user { id } }
Variable-Aware Hashing (Security Critical)¶
When variables are present in requests, they must be included in the response cache key to prevent data leakage between requests with different variables.
<!-- Code example in Python -->
import json
def compute_response_cache_key(
query_hash: str,
variables: dict[str, Any] | None = None,
) -> str:
"""Compute response cache key including variables for security."""
if not variables or variables == {}:
return query_hash
# Normalize variables: sort keys for consistent hashing
var_json = json.dumps(variables, sort_keys=True, separators=(",", ":"))
combined = f"{query_hash}:{var_json}"
return hashlib.sha256(combined.encode()).hexdigest()
Security Example: Preventing Data Leakage¶
Scenario: Cached response from User A's request leaks to User B
<!-- Code example in Python -->
# User A requests: query getUser($userId: ID!) with userId: "alice-123"
query_hash = "e4c7e8f5a1b2c3d4..."
variables_a = {"userId": "alice-123"}
cache_key_a = compute_response_cache_key(query_hash, variables_a)
# User B requests: same query with userId: "bob-456"
variables_b = {"userId": "bob-456"}
cache_key_b = compute_response_cache_key(query_hash, variables_b)
# CRITICAL: Different cache keys prevent data leakage!
assert cache_key_a != cache_key_b
# Result: cache_key_a = "hash:{"userId":"alice-123"}" (SHA-256)
# Result: cache_key_b = "hash:{"userId":"bob-456"}" (SHA-256)
Without variable-aware cache keys, both users would receive the same cached response containing Alice's data.
Computing Hashes in Clients¶
JavaScript/Apollo Client:
<!-- Code example in JAVASCRIPT -->
import crypto from 'crypto';
function computeAPQHash(query) {
return crypto
.createHash('sha256')
.update(query)
.digest('hex');
}
const hash = computeAPQHash(query);
Python Client:
<!-- Code example in Python -->
import hashlib
def compute_apq_hash(query: str) -> str:
return hashlib.sha256(query.encode()).hexdigest()
APQ Query Storage Backends¶
FraiseQL provides three storage backend options for the hash→query string mapping: in-memory (development), database (production), and pluggable custom backends. These store the association between query hashes and their full GraphQL query strings.
Memory Backend (Development)¶
Configuration:
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_storage_backend="memory", # Default for local development
)
Characteristics:
- ✅ No external dependencies - uses Python dict
- ✅ Fast - < 1µs lookups
- ✅ Simple - zero configuration
- ❌ Non-persistent - queries lost on process restart
- ❌ Non-scalable - single process only
- ❌ No cluster support - each pod has separate storage
Data Storage:
<!-- Code example in Python -->
# In-process dictionary: hash → query string mapping
_query_storage = {
"e4c7e8f5...": "query { users { id name } }",
"a1b2c3d4...": "query { products { id price } }",
}
Purpose:
- Maps query hashes to full GraphQL query strings
- Enables clients to send only hash in subsequent requests
- No tenant isolation needed (queries are not sensitive data; they're the schema contract)
Use Cases:
- Local development
- CI/CD pipelines
- Single-instance deployments
- Testing environments
Database Backend (Production)¶
Configuration:
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_storage_backend="postgresql",
apq_backend_config={
"table_prefix": "apq_",
"auto_create_tables": True,
"connection_timeout": 30,
}
)
Note: the
postgresqlbackend opens its own small connection pool todatabase_url(orapq_backend_config["database_url"]) on the first APQ request, and creates its tables if they don't exist (auto_create_tables, default on). Persisted queries survive a restart and are shared by every instance using that database. Its methods are synchronous (one indexed query each; a persisted query's text is kept in process once read), so the/graphqlroute calls them in a worker thread: a slow or unavailable database doesn't stall the event loop. Up topool_max_sizelookups run at once; the others wait for a connection, at mostconnection_timeoutseconds.
apq_backend_config keys: database_url (default: the app's database_url),
table_prefix (default "apq_", may include a schema: "myschema.apq_"),
auto_create_tables (default True), connection_timeout (seconds, default 30) and
pool_max_size (default 4).
Database Tables:
apq_queries Table¶
<!-- Code example in SQL -->
CREATE TABLE apq_queries (
hash VARCHAR(64) PRIMARY KEY,
query TEXT NOT NULL,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
-- Index for efficient storage
CREATE INDEX idx_apq_queries_created ON apq_queries (created_at);
Columns:
hash: SHA-256 hash (64 chars) - unique identifierquery: Full GraphQL query string - text field for storagecreated_at: Registration timestamp (UTC)updated_at: Last access timestamp (UTC)
Purpose: Stores the hash→query string mapping for all registered persisted queries. This is NOT a response cache, but a lookup table that persists across restarts and instances.
Characteristics:
- ✅ Persistent - survives process restarts
- ✅ Scalable - shared across multiple instances
- ✅ Cluster-ready - all pods use same database
- ✅ Observable - can query storage via SQL
- ⚠️ Latency - 10-50ms lookups (vs < 1µs in-memory)
- ⚠️ Dependencies - requires compatible database (PostgreSQL 13+, or other supported databases)
Performance:
- Query lookup: ~15-30ms (cold cache), < 2ms (warm)
- Memory usage: Minimal (queries stored in database, not process memory)
Use Cases:
- Production deployments
- Multi-instance/cluster setups
- Long-running services (> 24 hours)
- High-availability requirements
Maintenance:
Monitor storage usage (PostgreSQL example):
<!-- Code example in SQL -->
-- Check APQ query table size
SELECT
pg_size_pretty(pg_total_relation_size('apq_queries')) as table_size,
count(*) as query_count
FROM apq_queries;
Clean up unused queries (optional):
<!-- Code example in SQL -->
-- View queries by registration date
SELECT hash, created_at, length(query) as query_size
FROM apq_queries
ORDER BY created_at DESC;
-- Delete very old queries if needed (careful: clients may still reference)
DELETE FROM apq_queries
WHERE created_at < CURRENT_TIMESTAMP - INTERVAL '30 days';
Custom Backend (Pluggable)¶
For specialized use cases (Redis, DynamoDB, custom cache), implement a custom backend:
Configuration:
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_storage_backend="custom",
apq_backend_config={
"backend_class": "myapp.storage.RedisAPQBackend",
"redis_url": "redis://localhost:6379/0",
"ttl": 3600, # 1 hour
}
)
Custom Backend Interface:
Custom backends must implement the APQ storage interface with the following methods:
get_persisted_query(hash_value)→ query string or Nonestore_persisted_query(hash_value, query)→ None; raiseValueErrorwhenhash_valueis not the SHA-256 ofquery(fraiseql.storage.apq_store.check_query_hashdoes it), as the built-in backends doregister_queries(queries)→ dict mapping hash to queryget_storage_stats()→ dict with backend statistics
The methods are synchronous. A backend whose methods do blocking I/O (a database, a
network cache) sets the class attribute blocking_io = True, and the /graphql route
then calls them in a worker thread (asyncio.to_thread) instead of on the event loop;
such a backend must be thread-safe. The default, False, calls them on the event loop.
Example Use Cases:
- Redis backend for distributed systems
- DynamoDB for AWS deployments
- Memcached for lightweight caching
- Custom database backends
Backend Discovery:
- FraiseQL dynamically imports backend class via reflection
- Class must be importable from full path (module.ClassName)
- Receives the
apq_backend_configdict as the constructor's first argument - Also receives
response_ttl=(apq_response_cache_ttl) anddatabase_url=(the app'sdatabase_url) if the constructor has a parameter of that name;**kwargsgets neither - A subclass of
MemoryAPQBackendthat keeps its__init__(response_ttl=None)gets onlyresponse_ttl=, and a constructor without parameters is called without arguments
Query Registration Workflow¶
Build-Time Registration (Recommended for Production)¶
Pre-register all queries at application startup for zero-latency registration:
File Structure:
<!-- Code example in TEXT -->
src/
├── graphql/
│ ├── queries/
│ │ ├── user.graphql
│ │ ├── products.graphql
│ │ └── orders.graphql
│ └── mutations/
│ ├── createUser.graphql
│ └── updateProduct.graphql
Configuration:
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_mode="required",
apq_storage_backend="postgresql",
apq_queries_dir="./src/graphql", # Operations registered as persisted queries
)
Behavior:
- At startup, the app fails (
FileNotFoundError) ifapq_queries_dirdoesn't exist - When the first APQ request creates the APQ backend, FraiseQL scans
apq_queries_dirrecursively for.graphqland.gqlfiles - Splits each file into its operations (
query,mutation,subscription) - Stores each operation under the SHA-256 of its text as written in the file, without surrounding whitespace (for a file with one operation: the whole file, stripped)
- Ready to serve hash-only APQ requests (in
requiredmode: only these, plus what the backend already holds)
The hash is the SHA-256 of the exact text the client sends, so the files must hold
each operation the way your client's build emits it. A fragment is kept with the
operation written before it in the same file; put each operation in its own file,
followed by the fragments it uses. In disabled mode the directory isn't read.
Benefits:
- ✅ Zero registration latency (pre-loaded)
- ✅ Deterministic hashes (reproducible builds)
- ✅ Enforces "known queries only" in production
- ✅ Enables build-time optimization
Runtime Registration (Dynamic)¶
Allow clients to register new queries on first request:
Configuration:
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_mode="optional", # Allows registration
apq_storage_backend="postgresql",
# No apq_queries_dir - start empty
)
Registration Flow:
First request (register):
<!-- Code example in JSON -->
POST /graphql HTTP/1.1
{
"extensions": {
"persistedQuery": {
"version": 1,
"sha256Hash": "e4c7e8f5a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7"
}
},
"query": "query GetUser($id: ID!) { user(id: $id) { id name email } }",
"variables": {"id": "user-123"}
}
Server processes:
- Extracts hash:
e4c7e8f5... - Stores query in backend:
e4c7e8f5... → "query GetUser..." - Executes request normally
- Stores response in cache (if enabled)
- Returns response
Subsequent requests (cached):
<!-- Code example in JSON -->
POST /graphql HTTP/1.1
{
"extensions": {
"persistedQuery": {
"version": 1,
"sha256Hash": "e4c7e8f5a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7"
}
},
"variables": {"id": "user-456"}
}
Server processes:
- Extracts hash:
e4c7e8f5... - Looks up query in backend: Found!
- Tries response cache with variables hash
- If cache miss, executes query
- Stores response in cache
- Returns response
Benefits:
- ✅ Client-driven optimization
- ✅ Gradual adoption (mixed deployment)
- ✅ Flexible (no pre-registration needed)
- ⚠️ First request slower (registration + execution)
Query Result Caching Integration (Optional Feature)¶
APQ can optionally work with Query Result Caching (a separate feature described in the Caching Specification). Query result caching provides a fast path that bypasses GraphQL execution entirely for previously computed results. This section describes how APQ integrates with query result caching when enabled.
Architecture¶
Two-Layer System:
<!-- Code example in TEXT -->
Request
↓
Layer 1: Response Cache (JSON passthrough)
├─ Hit: Return pre-computed JSON response directly (fastest!)
└─ Miss: Continue to query execution
↓
Layer 2: GraphQL Execution
├─ Parse query
├─ Validate
├─ Execute through Rust pipeline
└─ Compute response
↓
Store in Response Cache
↓
Return Response
Performance Impact:
- Response cache hit: ~1-50ms (depending on backend)
- Cache miss: Normal execution time (100-500ms+)
- Overall improvement: 5-20x throughput increase (with 60-80% hit rate)
Configuration¶
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_mode="optional",
apq_storage_backend="postgresql",
)
Note: Query result caching is not a FraiseQLConfig setting; it is configured separately from APQ. See the Caching Specification for complete configuration options including TTL, backends, and complexity-aware settings.
Cache Key Generation (Query Result Caching)¶
When query result caching is enabled, the cache key includes:
- Query hash (SHA-256 of normalized query)
- Variables (normalized, sorted JSON)
- Tenant ID (for multi-tenant isolation)
- Complexity tier (for complexity-aware TTL)
Key Construction:
<!-- Code example in TEXT -->
cache_key = sha256(query_hash + ":" + sorted_variables_json + ":" + tenant_id + ":" + complexity)
Security Property:
Each unique combination of (query + variables + tenant) produces a different cache key. This prevents data leakage:
- Request A: query hash + variables
{"userId": "alice"}→ cache key A - Request B: query hash + variables
{"userId": "bob"}→ cache key B - Result: Different cache keys, no data leakage between users
Storing Query Results (Query Result Caching)¶
When query result caching is enabled:
Automatic Flow:
- GraphQL query executes normally
- Result computed
- If no errors and result has data:
- Filter result by requested fields (defense in depth)
- Include tenant_id for multi-tenant isolation
- Store in cache backend with TTL
- Subsequent requests with same query + variables hit cache (no execution needed)
Field Selection Filtering (Defense in Depth)¶
Both APQ and Query Result Caching implement field selection filtering as a security measure. When processing a persisted query request, FraiseQL automatically filters the response to include only the fields requested in the original query.
Where Applied:
- APQ responses (even if hash-only request) - before returning to client
- Query result cache entries (before caching) - prevent over-caching of sensitive data
Process:
- Parse query's selection set (which fields were requested)
- Identify requested fields from GraphQL AST
- Remove non-requested fields from response
- Return filtered response to client or cache
Example:
Query: query GetUser { user { id name } } (only id and name requested)
Response before filtering:
<!-- Code example in JSON -->
{"data": {"user": {"id": "123", "name": "Alice", "email": "alice@example.com", "ssn": "123-45-6789"}}}
Response after field selection filtering:
<!-- Code example in JSON -->
{"data": {"user": {"id": "123", "name": "Alice"}}}
Benefits:
- Even if database response includes sensitive fields (email, SSN, etc.), only requested fields are returned
- Prevents accidental data leakage via responses
- Applied consistently whether using APQ or not
- Query result cache entries are also filtered, preventing over-caching of sensitive data
Query Result Cache Invalidation¶
Query result cache invalidation is managed by the query result caching system. See the Caching Specification for details on:
- TTL-based automatic expiration
- Complexity-aware TTL policies
- Manual cache invalidation
- graphql-cascade integration for mutation-based invalidation
Production Configuration Examples¶
Development Environment¶
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://localhost/fraiseql_db",
apq_mode="optional", # Allow registration
apq_storage_backend="memory", # Fast, no persistence needed
apq_cache_responses=True, # Optimization
)
A cached response is served for apq_response_cache_ttl seconds after it was stored
(default 600; 0 means it does not expire), then the query runs again and its new
response is stored.
A response is cached when an APQ request runs a query (never a mutation or a
subscription) without errors, whichever execution path built it. The key is the
query's hash, its variables, the tenant (tenant_id in the request context) and, for
an authenticated request, the user's id (user_id, id or sub of
context["user"]): a user is only served their own cached responses. An authenticated
request whose user has no such id is not cached. Anonymous requests share entries
(hash, variables and tenant).
Environment Variables:
<!-- Code example in BASH -->
FRAISEQL_DATABASE_URL=postgresql://localhost/fraiseql_db
FRAISEQL_APQ_MODE=optional
FRAISEQL_APQ_STORAGE_BACKEND=memory
FRAISEQL_APQ_CACHE_RESPONSES=true
Staging Environment¶
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://pg-staging/fraiseql_db",
apq_mode="optional", # Allow client registration
apq_storage_backend="postgresql", # Persistent
apq_cache_responses=True,
apq_backend_config={
"auto_create_tables": True,
}
)
Production Environment¶
<!-- Code example in Python -->
config = FraiseQLConfig(
database_url="postgresql://pg-prod-1/fraiseql_db",
apq_mode="required", # Only persisted queries
apq_storage_backend="postgresql", # Persistent, shared
apq_cache_responses=True,
apq_queries_dir="./dist/graphql", # Pre-built queries
apq_backend_config={
"table_prefix": "apq_",
"auto_create_tables": False, # Pre-created for safety
"connection_timeout": 30,
}
)
Environment Variables:
<!-- Code example in BASH -->
# Production APQ configuration
FRAISEQL_APQ_MODE=required
FRAISEQL_APQ_STORAGE_BACKEND=postgresql
FRAISEQL_APQ_CACHE_RESPONSES=true
FRAISEQL_APQ_QUERIES_DIR=/app/dist/graphql
Metrics and Monitoring¶
FraiseQL provides comprehensive metrics for APQ operations.
Key Metrics¶
Query Cache Metrics (persisted query lookup):
query_cache_hits: Number of successful hash lookupsquery_cache_misses: Hashes not found (PERSISTED_QUERY_NOT_FOUND errors)query_cache_hit_rate: Percentage of successful lookups (0.0 to 1.0)
Response Cache Metrics (JSON passthrough cache):
response_cache_hits: Number of cached responses returnedresponse_cache_misses: Cache misses requiring executionresponse_cache_hit_rate: Percentage of responses from cacheresponse_cache_stores: New responses cached
Storage Metrics:
stored_queries_count: Total persisted queriescached_responses_count: Total cached responsestotal_storage_bytes: Approximate storage size
Performance Metrics:
avg_query_parse_time_ms: Average time to parse queriescache_lookup_time_ms: Time to look up in backend
Monitoring Integration¶
Prometheus Metrics (exported automatically):
<!-- Code example in PROMETHEUS -->
fraiseql_apq_query_cache_hits_total
fraiseql_apq_query_cache_misses_total
fraiseql_apq_response_cache_hits_total
fraiseql_apq_response_cache_misses_total
fraiseql_apq_stored_queries_count
fraiseql_apq_response_cache_size_bytes
Health Check Endpoint:
<!-- Code example in Python -->
# GET /health includes APQ metrics
{
"status": "healthy",
"apq": {
"query_cache_hit_rate": 0.85,
"response_cache_hit_rate": 0.72,
"stored_queries_count": 342,
"cached_responses_count": 15234
}
}
Dashboard Recommendations¶
- Cache Hit Rates
- Monitor trend over time
- Target: > 70% response cache hit rate
-
Low hit rate indicates:
- Too many unique queries (APQ not effective)
- Queries executed infrequently
- TTL too short
-
Error Rates
- Monitor PERSISTED_QUERY_NOT_FOUND errors
-
Sudden spike indicates:
- Client misconfiguration
- Query hash mismatch
- Backend storage issue
-
Storage Usage
- Monitor stored_queries_count trend
- Monitor response cache size
-
Set alerts for runaway storage growth
-
Performance
- p99 query cache lookup: < 10ms
- p99 response cache hit: < 50ms
- p99 response cache miss + execution: 100-500ms+
Troubleshooting¶
PERSISTED_QUERY_NOT_FOUND Error¶
Symptom: Clients receive "PersistedQueryNotFound" errors
Causes:
- Query hash mismatch between client and server
- Query not registered
- Storage backend lost data (memory backend restart)
- Whitespace differences in query string
Solutions:
- Verify hash matches: recompute SHA-256 of query string
- In
optionalmode, send query with hash to register; inrequiredmode, register it on the server - Use persistent backend (PostgreSQL) instead of memory
- Ensure query strings are identical (whitespace sensitive!)
Response Cache Misses (Low Hit Rate)¶
Symptom: Response cache hit rate < 50%
Causes:
- Each query executes with different variables (unique cache keys)
- Response caching disabled
- Queries have errors (not cached)
Solutions:
- Verify queries are reused with same variables (use APQ registration metrics)
- Enable with
apq_cache_responses=true - Check for errors in responses (not cached by design)
ARBITRARY_QUERY_NOT_ALLOWED Error¶
Symptom: Clients in required mode send queries without hashes
Causes:
- Client not configured for APQ
- Client APQ support disabled
Solutions:
- Configure client for APQ (Apollo Client, Relay, etc.)
- Enable APQ in client SDK
Hash Mismatch (provided sha does not match query)¶
Symptom: a request carrying both sha256Hash and query gets HTTP 400 with
provided sha does not match query (code BAD_REQUEST, as Apollo Server answers)
Cause: the SHA-256 of the query text is not sha256Hash. In optional and
required mode such a request is refused and nothing is stored, so no client can store
a text under the hash of another query. (disabled mode ignores the extension and
stores nothing.)
Solution: hash the exact text you send (UTF-8, SHA-256, lowercase hex).
PERSISTED_QUERY_NOT_IN_LIST Error¶
Symptom: In required mode, a client sends a hash with its query text and gets
PersistedQueryNotInList
Cause: the hash is not registered on the server; required mode doesn't let
clients register queries.
Solution: register the operation on the server (put it in apq_queries_dir, or call
register_queries at startup), with the exact text the client hashes.
Backend Storage Issues (Database)¶
Symptom: Queries stored but not retrievable
Causes:
- Table not created (auto_create_tables=false but table missing)
- Permission denied on apq_queries or apq_responses table
- Disk full
- Connection pool exhausted
Solutions:
- Create tables manually (see Schema section above)
- Grant permissions (example for PostgreSQL):
GRANT ALL ON apq_* TO fraiseql_user - Check disk space (example for PostgreSQL):
SELECT pg_database_size('fraiseql_db') - Increase connection pool size
Memory Backend Queries Lost After Restart¶
Symptom: Hash-only requests fail after pod restart
Causes:
- Using memory backend in production
- Queries not pre-registered
Solutions:
- Pre-register queries with
apq_queries_dir(see Build-Time Registration) - Use a persistent backend: `apq_storage_backend="postgresql"
Security Considerations¶
Query Allowlisting Security¶
APQ in required mode provides defense-in-depth against:
Introspection Attacks:
- Arbitrary queries rejected in required mode
- Cannot execute
{ __schema { ... } }queries - Prevents schema inference by malicious actors
Injection Attacks:
- Only pre-approved queries execute
- Prevents dynamic query construction
- Cannot execute unexpected operations
DoS Attacks:
- Complex query expressions blocked
- Only pre-registered queries allowed
- Prevents algorithmic complexity attacks
Variable Handling¶
Security: Variables are included in response cache keys
<!-- Code example in Python -->
# User A
query_hash = "abc123..."
variables = {"userId": "alice"}
cache_key_a = sha256(f"{query_hash}:{json.dumps(variables)}")
# User B (different variables)
variables = {"userId": "bob"}
cache_key_b = sha256(f"{query_hash}:{json.dumps(variables)}")
# assert cache_key_a != cache_key_b ✅ Prevents data leakage
Multi-Tenant Isolation¶
Tenant ID in Cache Keys:
<!-- Code example in Python -->
# Query hash: e4c7e8f5...
# Tenant A: caches response with tenant_id="tenant-123"
# Tenant B: caches response with tenant_id="tenant-456"
# Never mixed
Sensitive Data in Error Responses¶
Safe:
<!-- Code example in JSON -->
{
"errors": [{
"message": "PersistedQueryNotFound",
"extensions": {"code": "PERSISTED_QUERY_NOT_FOUND"}
}]
}
Unsafe (avoid):
<!-- Code example in JSON -->
{
"errors": [{
"message": "Query 'SELECT * FROM users' not found",
"extensions": {"provided_query": "SELECT * FROM users"}
}]
}
Migration Guide: From Arbitrary Queries to APQ¶
Preparation (Week 1)¶
- Enable APQ in
optionalmode (accept both) - Deploy client-side APQ support
- Monitor metrics (should see 0% response cache hits initially)
- Create
graphql/directory with.graphqlfiles
Adoption (Week 2-3)¶
- Deploy production build with APQ-enabled clients
- Monitor query registration (new hashes appearing)
- Verify response cache hit rate increases
- Pre-register high-frequency queries
Enforcement (Week 4)¶
- Switch to
requiredmode on staging - Test that only registered queries execute. With the
postgresqlbackend, every hash clients registered while inoptionalmode is still inapq_queriesand keeps running: empty the table (or use a newtable_prefix) and register only the approved operations - Verify client handles ARBITRARY_QUERY_NOT_ALLOWED
- Plan rollout schedule
Production Rollout (Week 5)¶
- Switch to
requiredmode in production - Enable APQ in all client builds
- Monitor error rate (should be 0 if done correctly)
- Maintain
optionalmode for legacy clients temporarily
Optimization (Ongoing)¶
- Monitor response cache hit rate
- Adjust TTL based on usage patterns
- Gradually migrate legacy clients
- Remove deprecated endpoints
Client Integration Examples¶
Apollo Client (JavaScript)¶
<!-- Code example in JAVASCRIPT -->
import { ApolloClient, InMemoryCache } from '@apollo/client';
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
import { HttpLink } from '@apollo/client/link/http';
import sha256 from 'crypto-js/sha256';
const client = new ApolloClient({
link: createPersistedQueryLink({
useGETForHashedQueries: true,
sha256: (query) => sha256(query).toString(),
}).concat(
new HttpLink({
uri: 'https://api.example.com/graphql',
credentials: 'include',
})
),
cache: new InMemoryCache(),
});
Relay (JavaScript)¶
<!-- Code example in JAVASCRIPT -->
import { createRelayNetworkLayer } from 'react-relay-network-layer/lib/index.js';
const network = createRelayNetworkLayer(
[
{
url: () => Promise.resolve('https://api.example.com/graphql'),
init: () => ({
credentials: 'include',
}),
apq: {
sha256Hash: (query) => crypto.createHash('sha256').update(query).digest('hex'),
},
},
],
{ disableBatching: false }
);
Python Client¶
Python GraphQL clients (e.g., gql, sgqlc) support APQ through transport options:
<!-- Code example in TEXT -->
transport = HttpTransport(
url='https://api.example.com/graphql',
apq_enabled=True,
)
client = Client(transport=transport)
The client library automatically:
- Computes SHA-256 hash of each query
- Sends hash-only requests
- Falls back to hash + query on first request (registration)
- Caches registered queries locally
Conclusion¶
Automatic Persisted Queries (APQ) in FraiseQL provides a bandwidth optimization mechanism by storing hash→query string mappings. APQ allows clients to send only a 64-character hash instead of multi-kilobyte query strings, while improving security through query allowlisting in production.
APQ is a standalone feature separate from Query Result Caching, though they work well together:
- APQ (this spec) = Reduce request size by sending hash instead of query string
- Query Result Caching (see Caching Spec) = Optionally avoid execution by caching results
Key Takeaways:
- ✅ APQ Storage:
- Development:
optionalmode + memory backend - Staging:
optionalmode + database backend - Production:
requiredmode + database backend + pre-registered queries - ✅ Query Result Caching (separate feature):
- Enable for 5-20x throughput improvement
- Complexity-aware TTL for smart cache duration
- Automatic invalidation via graphql-cascade
- See Caching Specification for details
- ✅ Security: Variable-inclusive cache keys prevent data leakage between requests
- ✅ Monitoring: Track APQ query registration and query result cache hit rates separately