Automatic Persisted Queries

Automatic Persisted Queries (APQ) reduce bandwidth and improve latency by caching query strings on the server.

Note

APQ is implemented and enabled by default. No configuration is required — the server caches query strings in memory automatically. To use Redis instead of in-memory storage (required for multi-instance deployments), add the redis-apq feature flag to your deployment image.

How APQ Works

Instead of sending the full query text on every request, clients send a query hash:

First Request: The client sends the query along with its hash. The server caches the query and returns data.

Subsequent Requests: The client sends only the hash (much smaller). The server looks up the query from cache and returns data.

Before and After

Without APQ, every request carries the full query string:

# Without APQ — full query on every request (~1.2 KB body)
curl -s -X POST https://api.example.com/graphql \
    -H "Content-Type: application/json" \
    -d '{
        "query": "query GetUserProfile($id: ID!) { user(id: $id) { id name email createdAt orders(last: 5) { id total status } } }",
        "variables": { "id": "user-123" }
    }'

With APQ, after the first request only the 64-byte hash is sent:

# With APQ — hash only (~120 byte body, 90%+ smaller)
curl -s -X POST https://api.example.com/graphql \
    -H "Content-Type: application/json" \
    -d '{
        "extensions": {
            "persistedQuery": {
                "version": 1,
                "sha256Hash": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd"
            }
        },
        "variables": { "id": "user-123" }
    }'

# Response (same data, no query overhead):
# { "data": { "user": { "id": "user-123", "name": "Alice", ... } } }

Configuration

APQ is enabled by default with an in-memory LRU cache. No TOML configuration is required for single-instance deployments.

Single Instance (default)

No configuration needed. The server caches up to 10,000 query strings in memory with a 24-hour TTL.

To disable APQ (e.g., in testing), set the environment variable:

FRAISEQL_APQ_ENABLED=false fraiseql run

Multi-Instance (Redis required)

For deployments behind a load balancer, use the Redis backend via the redis-apq Cargo feature. Set REDIS_URL in your environment — FraiseQL picks it up automatically when the feature is enabled:

REDIS_URL=redis://your-redis:6379 fraiseql run

Caution

In multi-instance deployments without Redis, a client hitting instance A may cache a query that instance B has never seen, causing spurious PersistedQueryNotFound errors on retries. Always use the redis-apq feature when running behind a load balancer.

Client Implementation

Request Format

APQ uses extensions to send the query hash:

{
    "extensions": {
        "persistedQuery": {
            "version": 1,
            "sha256Hash": "abc123def456..."
        }
    },
    "variables": {
        "id": "user-123"
    }
}

Flow

1. First request: Client sends hash only (no query string)
2. Cache miss: Server returns PersistedQueryNotFound error
3. Retry with query: Client sends hash + full query string
4. Cached: Server caches query, returns data
5. Subsequent requests: Client sends hash only, server uses cache

Client Code

Apollo Client

import { ApolloClient, InMemoryCache } from '@apollo/client';
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
import { createHttpLink } from '@apollo/client/link/http';
import { sha256 } from 'crypto-hash';

const httpLink = createHttpLink({ uri: '/graphql' });
const persistedQueriesLink = createPersistedQueryLink({ sha256 });

const client = new ApolloClient({
    cache: new InMemoryCache(),
    link: persistedQueriesLink.concat(httpLink)
});

urql

import { createClient, fetchExchange } from 'urql';
import { persistedExchange } from '@urql/exchange-persisted';

const client = createClient({
    url: '/graphql',
    exchanges: [
        persistedExchange({
            preferGetForPersistedQueries: true
        }),
        fetchExchange
    ]
});

Vanilla JS

const sha256 = require('crypto-js/sha256');

async function executeQuery(query, variables) {
    const hash = sha256(query).toString();

    // Try with hash only
    let response = await fetch('/graphql', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            extensions: {
                persistedQuery: { version: 1, sha256Hash: hash }
            },
            variables
        })
    });

    let result = await response.json();

    // If not found, send with full query
    if (result.errors?.[0]?.message === 'PersistedQueryNotFound') {
        response = await fetch('/graphql', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                query,
                extensions: {
                    persistedQuery: { version: 1, sha256Hash: hash }
                },
                variables
            })
        });
        result = await response.json();
    }

    return result;
}

Manual Testing with curl

You can test the full APQ flow manually to verify your configuration:

# Step 1: Attempt hash-only request (expect PersistedQueryNotFound)
curl -s -X POST http://localhost:8080/graphql \
    -H "Content-Type: application/json" \
    -d '{
        "extensions": {
            "persistedQuery": {
                "version": 1,
                "sha256Hash": "ecf4edb46db40b5132295c0291d62fb65d6759a9aeacfe1f108c30a4740c5f71"
            }
        }
    }'
# Response: {"errors":[{"message":"PersistedQueryNotFound","extensions":{"code":"PERSISTED_QUERY_NOT_FOUND"}}]}

# Step 2: Send hash + query to register it
curl -s -X POST http://localhost:8080/graphql \
    -H "Content-Type: application/json" \
    -d '{
        "query": "{ __typename }",
        "extensions": {
            "persistedQuery": {
                "version": 1,
                "sha256Hash": "ecf4edb46db40b5132295c0291d62fb65d6759a9aeacfe1f108c30a4740c5f71"
            }
        }
    }'
# Response: {"data":{"__typename":"Query"}}

# Step 3: Now hash-only works (query is cached)
curl -s -X POST http://localhost:8080/graphql \
    -H "Content-Type: application/json" \
    -d '{
        "extensions": {
            "persistedQuery": {
                "version": 1,
                "sha256Hash": "ecf4edb46db40b5132295c0291d62fb65d6759a9aeacfe1f108c30a4740c5f71"
            }
        }
    }'
# Response: {"data":{"__typename":"Query"}}

GET Requests

With APQ, you can use GET requests for cached queries:

[fraiseql.apq]
enabled = true
allow_get = true

GET /graphql?extensions={"persistedQuery":{"version":1,"sha256Hash":"abc123"}}&variables={"id":"123"}

Tip

GET requests enable HTTP caching (CDN, browser), bookmarkable URLs, and reduced server load. This is particularly useful for frequently-executed read queries.

Security Considerations

Note

APQ hashes do not expose query structure. A SHA-256 hash is a one-way digest — an observer who intercepts the hash cannot reconstruct the original query text. This is safe to transmit over unencrypted channels, though TLS is still recommended for your variables and response data.

Hash Verification

FraiseQL verifies that the query matches the hash when both are sent together:

{
    "query": "{ users { id } }",
    "extensions": {
        "persistedQuery": {
            "version": 1,
            "sha256Hash": "wrong-hash-value-here"
        }
    }
}

Response:

{
    "errors": [{
        "message": "Provided sha does not match query",
        "extensions": { "code": "BAD_USER_INPUT" }
    }]
}

Query Allowlisting

For maximum security, only allow prepopulated queries:

[fraiseql.apq]
enabled = true
require_prepopulated = true  # Reject queries not in cache

Caution

Setting require_prepopulated = true prevents arbitrary queries in production, but means you must pre-register all queries before deploying changes. Build this into your CI/CD pipeline.

Prepopulating the Cache

For production, prepopulate the APQ cache at build time:

Extract Queries

extract-queries.js

const fs = require('fs');
const crypto = require('crypto');
const glob = require('glob');

const queries = {};

// Find all GraphQL queries in source
glob.sync('src/**/*.graphql').forEach(file => {
    const query = fs.readFileSync(file, 'utf8');
    const hash = crypto.createHash('sha256').update(query).digest('hex');
    queries[hash] = query;
});

fs.writeFileSync('queries.json', JSON.stringify(queries, null, 2));

Upload to Server

# Upload extracted queries
fraiseql apq upload --file queries.json

CLI Commands

APQ cache management is handled via the REST API at /api/v1/apq/ when the server is running. See CLI Reference for full command reference. There is no fraiseql apq CLI subcommand — use the REST API directly.

Metrics

Monitor APQ performance:

Metric	Description
fraiseql_apq_hits_total	Cache hits
fraiseql_apq_misses_total	Cache misses
fraiseql_apq_cache_size	Current cache size
fraiseql_apq_bytes_saved	Bandwidth saved

Grafana Dashboard

# APQ hit rate
sum(rate(fraiseql_apq_hits_total[5m])) /
(sum(rate(fraiseql_apq_hits_total[5m])) + sum(rate(fraiseql_apq_misses_total[5m])))

# Bandwidth saved (MB/s)
sum(rate(fraiseql_apq_bytes_saved[5m])) / 1024 / 1024

Benefits

Bandwidth Reduction

Typical GraphQL queries are 1–10 KB. Hashes are 64 bytes.

Query Size	With APQ	Savings
1 KB	64 B	94%
5 KB	64 B	99%
10 KB	64 B	99%

Additional Benefits

• Less data to transmit — Faster parsing after first request
• CDN caching — With GET requests enabled
• Mobile — Reduced cellular data usage and better battery life

Best Practices

Warm the Cache in CI/CD

.github/workflows/deploy.yml

- name: Extract and upload queries
  run: |
    npm run extract-queries
    fraiseql apq upload --file queries.json

Monitor Hit Rate

Target greater than 90% hit rate in production:

fraiseql_apq_hits_total / (fraiseql_apq_hits_total + fraiseql_apq_misses_total) > 0.9

Size the Cache

# Estimate: unique queries x 2 (for safety margin)
[fraiseql.apq]
cache_size = 10000  # For ~5000 unique queries

Use Redis for Distributed

Single-instance memory cache doesn’t share across servers:

# Production with multiple instances
[fraiseql.apq]
backend = "redis"
redis_url = "${REDIS_URL}"

Troubleshooting

Low Hit Rate

1. Check client is sending hashes correctly
2. Verify cache TTL isn’t too short
3. Check for query variations (different whitespace, variable names)

Cache Not Working

# Check APQ status
fraiseql apq status

# Test a query
fraiseql apq lookup --hash "abc123..."

Hash Mismatch

Ensure client and server use the same hashing:

• Algorithm: SHA-256
• Input: Query string with normalized whitespace
• Output: Hex-encoded lowercase

Next Steps

Caching

Caching — Response caching

Performance

Performance — Additional optimizations

Deployment

Deployment — Production configuration