AEM custom search results: building a search page with QueryBuilder
CIRCUIT’s focus on practical AEM engineering makes a search page a natural extension of the platform. Adobe Experience Manager’s QueryBuilder servlet converts structured request parameters into JCR (Java Content Repository) queries and returns JSON that a JavaScript client or server-side template can turn into paginated results. The aim is not to reproduce every feature of a public search engine, but to provide a dependable route from a visitor’s query to content they can use.
For Australian organisations, that route must work across English-language sites, distributed publishing teams in Sydney, Melbourne, Brisbane and Perth, and visitors using phones on variable regional connections. It should also reflect local conventions such as Australian English, Australian dollar pricing and the Australian Privacy Act. The strongest implementation therefore combines query design with editorial governance, accessible interfaces and performance measurement.
QueryBuilder as the search foundation
QueryBuilder is a sensible foundation when the result set already lives in AEM. A request to /bin/querybuilder.json can combine full-text terms with constraints such as repository path, content type, language, tag or date. The endpoint returns properties and metadata rather than a finished page, giving the team control over card design, excerpts, analytics and navigation while avoiding brittle repository queries in browser code.
The key is to distinguish filtering from ranking. A visitor may ask for “annual report”, while the site also needs to restrict results to a brand, audience or approved publication state. Full-text predicates should narrow the set, but relevance can be improved through titles, summaries, tags and carefully ordered metadata. Fixed constraints belong in server-controlled parameters; free text should remain an input, never a fragment of executable query syntax.
Search quality also needs an evaluation loop. Teams can compare zero-result rates, successful selections and abandoned searches, then test changes against representative queries. Operational research resources from ISORC 2015 offer wider context for analytical decision-making and optimisation, while CIRCUIT recordings can supply the AEM-specific implementation detail developers need.
A content model that supports discovery
Start by defining a stable content model rather than mapping every possible page property into the index. A useful result typically needs a title, summary or description, canonical URL, content type, publication date, language, audience or region, and relevant taxonomy. Keep this list small and consistent across article, campaign and asset templates, with explicit values for booleans and dates so predicates do not depend on inconsistent authoring.
Local requirements belong in the same model. Australian sites often display prices in AUD, state whether GST is included, and use date formats such as 12 Mar 2025 alongside Australian English spelling. Geographic facets can cover Sydney, Melbourne, Brisbane, Adelaide and Perth, while language may include Australian English as a governed value rather than a free-text tag. These conventions make filters predictable for both users and search code.
Tagging should follow a controlled vocabulary owned by editors, not a pile of near-duplicate keywords. Reuse tags across pages and assets, record synonyms where visitors are likely to use them, and expose the approved terms in filters. If the search must include PDFs, images or videos, define the relationship between the asset and its parent page so one item does not appear several times with different titles and descriptions.
Creating the search request and result page
The request layer should accept a small, whitelisted set of inputs: the search phrase, page number, page size, selected filters and sort choice. Map those values to known QueryBuilder parameters with an explicit property, property.value, property.operation and orderby contract. Validate allowed filters on the server, cap the page size, reject oversized terms and preserve the current query in the URL so results can be bookmarked and shared without losing state.
Rendering can happen in the browser through a controlled fetch or in an AEM component that calls the service and passes data to Sightly. The former supports immediate facet updates; the latter can simplify delivery and make the first result set more robust for crawlers or clients without JavaScript. Either way, use a consistent response object for hits, total results, elapsed time, facets and pagination, and never let the interface infer missing metadata from an arbitrary node property.
The interface must work with a keyboard, a screen reader and a touch screen. Give the search field a visible label, place results in a logical region, announce result counts after searching and keep the active filter clear to assistive technology. On a narrow screen, preserve the query, filters and sort controls while allowing result cards to stack cleanly. Compressed assets and modest initial payloads matter for regional Australian mobile networks and for visitors searching while travelling.
Security, permissions and publishing governance
Search must not become an accidental way to expose restricted content. Repository ACLs, unpublished nodes, draft branches and inherited permissions all affect what should be visible, so test the endpoint as anonymous, authenticated and privileged users. Do not assume that hiding an item in the interface provides protection, and do not use an unrestricted service account to bypass checks without applying a separate, auditable authorisation model.
Publishing governance also determines how quickly search reflects editorial changes. Workflows can approve content before it enters the published branch, while scheduled publication and unpublishing need corresponding index behaviour. The CIRCUIT article on automated publishing approvals shows how AEM workflows can reduce manual handoffs; the same discipline should define when a result becomes eligible and how quickly it disappears.
Logs need a privacy review as well. Search phrases can contain names, locations or other personal information, and retaining them indefinitely may create unnecessary risk under the Privacy Act and Australian Privacy Principles, where applicable. Store only what the team needs, restrict access to aggregated or operational data, set a deletion period and avoid placing sensitive queries in general analytics tools. Any accompanying email alert or subscription flow should also follow the Australian Spam Act and provide clear consent.
Practical recommendations for reliable AEM search
At production scale, response time depends on repository size, index coverage, predicate selectivity and the amount of data returned to the client. Bound the number of hits, use pagination, ensure relevant properties are indexed and remove broad predicates that force traversal. For organisations analysing content across larger repositories, large-scale content analytics explores how AEM and Apache Spark can support that broader analytical workload without turning every search request into a batch job.
Instrumentation should separate search demand from editorial quality. Capture latency, result counts, selected facets, zero-result queries, click-through and downstream conversions, then connect those signals to the content model. Sample or redact sensitive terms, and give editors a manageable view of missing metadata and popular unanswered queries. Changes to ranking, synonyms or schema can then be assessed against actual behaviour instead of anecdote.
The following practices create a dependable baseline for teams preparing a production search page:
- Define a signed-off content model and controlled vocabulary before enabling facets.
- Keep query parameters whitelisted, validate filters server-side, and enforce sensible limits on phrase length and page size.
- Verify permissions with anonymous, authenticated and privileged sessions; test unpublished, expired and moved content.
- Use progressive enhancement, accessible focus management and clear result-count announcements for keyboard and screen-reader users.
- Measure zero-result searches, latency, clicks and conversions with privacy-safe logging, then review the findings regularly.
- Test representative queries, indexes, pagination and fallback behaviour after every major AEM upgrade or template change.
Custom AEM search works best when the query contract, content model and publishing rules are designed together. That gives developers a stable API, editors dependable metadata and visitors results that respect both relevance and access boundaries.
Explore the CIRCUIT AEM recordings, choose a session that matches your architecture, and then build the first QueryBuilder component against a small, representative content set. Validate it with Australian users, real search phrases and production-like permissions before expanding the catalogue.