AEM Query Builder API: A Basic Guide for Developers

he Adobe Experience Manager (AEM) Query Builder API is a powerful tool designed to simplify content retrieval from the JCR repository. Whether you’re building dynamic listings, integrating custom components, or conducting audits, mastering Query Builder can significantly improve your development workflow and performance outcomes.

What is the Query Builder API?

At its core, the Query Builder API allows developers to construct search queries using predicate-based key-value pairs. Unlike raw XPath or JCR-SQL2, Query Builder offers a more intuitive, extensible, and environment-friendly approach.

Queries are passed as a Map<String, String> to the QueryBuilder service, which returns a SearchResult with matched nodes.

Core Components of a Query

• path: Base location for the search

• type: Node type to search (e.g., cq:Page, dam:Asset)

• property / property.value: Filters by node properties

• orderby / orderby.sort: Sorts results

• p.limit / p.offset: Pagination support

Basic Example

A query to retrieve all pages of type article under /content/mysite/en:

{

  "path": "/content/mysite/en",

  "type": "cq:Page",

  "1_property": "jcr:content/sling:resourceType",

  "1_property.value": "mysite/components/page/article",

  "orderby": "@jcr:content/jcr:lastModified",

  "orderby.sort": "desc",

  "p.limit": "10"

}

Use in a Sling Servlet

@SlingServlet(paths = "/bin/custom/articleQuery")

public class ArticleQueryServlet extends SlingAllMethodsServlet {

    @Reference

    private QueryBuilder builder;

    protected void doGet(SlingHttpServletRequest request, SlingHttpServletResponse response)

            throws ServletException, IOException {

        Map<String, String> map = new HashMap<>();

        map.put("path", "/content/mysite/en");

        map.put("type", "cq:Page");

        map.put("1_property", "jcr:content/sling:resourceType");

        map.put("1_property.value", "mysite/components/page/article");

        map.put("orderby", "@jcr:content/jcr:lastModified");

        map.put("orderby.sort", "desc");

        Session session = request.getResourceResolver().adaptTo(Session.class);

        Query query = builder.createQuery(PredicateGroup.create(map), session);

        SearchResult result = query.getResult();

        // Example response

        for (Hit hit : result.getHits()) {

            response.getWriter().write(hit.getPath() + "\n");

        }

    }

}

Debugging and Optimization Tools

• Query Builder Debugger: http://localhost:4502/libs/cq/search/content/querydebug.html Useful for testing queries, inspecting results, and generating JCR-SQL2 equivalents.

• Log Query Execution Time: Enable DEBUG log level on com.day.cq.search to monitor query performance.

  
  

Best Practices

• Use Indexing: Ensure frequently queried properties are indexed via Oak indexes.

• Use Pagination: Set p.limit and p.offset to avoid loading thousands of nodes.

• Avoid Deep Tree Traversals: Narrow your path scope and use property constraints.

• Validate in Lower Environments: Test query performance in staging before deploying to production.

  
  

Common Use Cases

• Search content pages or assets with specific metadata

• Generate tag-based filtering for listings

• Audit content types or template usage across large repositories

• Automate site governance scripts

By investing time in the AEM Query Builder API, teams can significantly improve the scalability, traceability, and speed of their content-heavy applications.