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 1,000 query strings in memory with a 1-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, cached queries can be sent as GET requests:

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

APQ caching is additive by default — any query can be registered on first use. For deployments where you want to restrict execution to known queries only, use the redis-apq feature flag in combination with infrastructure-level controls (e.g., only pre-seeding the Redis cache before deploy and blocking the registration flow via a reverse proxy).

Warming the Cache

APQ queries are registered automatically on first use — no batch upload API is needed. To warm the cache after a deploy, run your queries once against the live server:

# Warm cache by executing each query once after deploy
for hash in $(cat queries.json | jq -r 'keys[]'); do
    query=$(cat queries.json | jq -r --arg h "$hash" '.[$h]')
    curl -s -X POST $FRAISEQL_URL/graphql \
        -H "Content-Type: application/json" \
        -d "{\"query\": $(echo "$query" | jq -R -s '.'), \
             \"extensions\": {\"persistedQuery\": {\"version\": 1, \"sha256Hash\": \"$hash\"}}}" \
        > /dev/null
done

Metrics

Monitor APQ performance:

Metric	Description
fraiseql_apq_hits_total	Cache hits
fraiseql_apq_misses_total	Cache misses
fraiseql_apq_stored_total	Queries stored
fraiseql_apq_redis_errors_total	Redis backend errors (only present with redis-apq feature)

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])))

# Queries stored over time
rate(fraiseql_apq_stored_total[5m])

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

After deploying, run your queries once against the live server so subsequent requests can use the hash-only path:

.github/workflows/deploy.yml

- name: Warm APQ cache
  run: npm run warm-apq-cache  # script that POSTs each query+hash once to $FRAISEQL_URL/graphql

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

The in-memory APQ store uses an LRU cache with a default capacity of 1,000 query entries. This is not currently configurable via TOML or environment variables — if you need a larger cache, use the redis-apq feature flag (Redis has no fixed capacity limit).

Use Redis for Distributed

Single-instance memory cache doesn’t share across servers. Enable the redis-apq Cargo feature and set REDIS_URL:

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

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 hit/miss counts via the metrics endpoint
curl -s http://localhost:8080/metrics | grep fraiseql_apq

# Test manually: send hash + query to register, then hash-only to verify
curl -s -X POST http://localhost:8080/graphql \
    -H "Content-Type: application/json" \
    -d '{"query":"{__typename}","extensions":{"persistedQuery":{"version":1,"sha256Hash":"ecf4edb46db40b5132295c0291d62fb65d6759a9aeacfe1f108c30a4740c5f71"}}}'

Hash Mismatch

Ensure client and server use the same hashing:

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

GraphQL-Only Feature

APQ (Automatic Persisted Queries) is GraphQL-only. REST endpoints are identified by path, gRPC endpoints by service/method name — neither uses query hashing. APQ configuration has no effect on REST or gRPC transports.

Next Steps

Caching

Caching — Response caching

Performance

Performance — Additional optimizations

Deployment

Deployment — Production configuration