Persisted GraphQL queries are the recommended way to expose Content Fragment data from AEM to headless front ends, and understanding why matters as much as knowing the syntax.
Why persisted, not ad hoc, queries
AEM's GraphQL endpoint allows ad hoc queries during development, but production traffic should use persisted queries: named, pre-registered query definitions stored on the AEM instance and invoked by name over a simple GET request. This avoids exposing your full Content Fragment schema and query surface to arbitrary client-side requests, and it lets Dispatcher and CDN layers cache GraphQL responses by URL the same way they cache any other GET request.
Organizing persisted queries
- Group persisted queries into configuration folders that map to logical consumers (a specific front end, app, or page type) rather than one flat namespace
- Name queries descriptively and version them explicitly when the shape changes, rather than mutating an existing query that other consumers may depend on
- Keep queries focused — a persisted query that tries to serve every possible consumer's data needs becomes fragile and expensive to run
Caching behavior
Because persisted queries are invoked via GET with the query name in the URL path, standard Dispatcher and CDN caching rules apply exactly as they would to any other page request. This is one of the underrated advantages over a generic POST-based GraphQL endpoint, which is much harder to cache at the edge.
Common pitfalls
- Forgetting to re-deploy or re-register a persisted query after changing a Content Fragment Model, leading to queries that silently return null for new fields
- Over-fetching: requesting fragment fields the front end does not actually render, which increases payload size and reduces effective cache value
- Not setting cache invalidation to fire correctly when the underlying Content Fragment changes — verify this explicitly rather than assuming default replication behavior covers it
Treat persisted queries as a stable API contract with your front-end consumers, with the same versioning discipline you would apply to a REST or GraphQL API in any other system.