Using the Content Search Query API

Overview

The Content Search Query API enables you to perform search queries against the Search Manager (SM) index from your site web application or any Java code. You access the API by retrieving the ExternalSearchService from the HippoServiceRegistry.

Prerequisites

Bloomreach Content with the Content Search addon installed and configured
Access to the HippoServiceRegistry
Java development environment

Obtaining the ExternalSearchService

Retrieve the ExternalSearchService instance using the HippoServiceRegistry:

ExternalSearchService searchService = HippoServiceRegistry.getService(ExternalSearchService.class);

Building and Executing a Query

Use the Fluent API provided by ExternalSearchService to construct and execute a search query. The example below demonstrates how to build a query with filters, field selection, facets, sorting, and pagination:

Future<QueryResponse> future = searchService
  .builder()
  .catalog("your catalog")
  .view("your_view_id")
  .view("another_view_id")
  .query("your query")
  .filterQuery("attribute name", "value to filter on")
  .filterQuery("another attribute name", "another value to filter on")
  .limit(10)
  .offset(0)
  .retrieveField("title")
  .retrieveField("another field")
  .facetField("facet field")
  .sortBy("title", SortType.ASC)
  .build()
  .execute();

Use filterQuery() to add filter queries (fq parameters).
Use retrieveField() to specify which fields to retrieve (fl parameter).
Use view() to set the view ID for the query.

For detailed information about available query parameters and their formats, refer to the parameter documentation.

Filtering on Attributes

You can filter on any attribute indexed in Search Manager. During feed generation, the addon includes certain metadata as top-level attributes. You can configure these in Search Manager and use them as filters in your queries.

Attribute	Description
`xmPrimaryDocType`	The document type name of the indexed document (e.g. `myproject:news`)

Asynchronous Query Execution

The query returns a Future<QueryResponse>, allowing you to execute the query asynchronously. This is useful in the prepareBeforeRender phase to leverage parallel HST component preprocessing.

Integration with CRISP

The addon uses CRISP to communicate with the Search Manager index. CRISP handles caching for search requests. If necessary, you can adjust the resource resolver configuration at:

/hippo:configuration/hippo:modules/crispregistry/hippo:moduleconfig/crisp:resourceresolvercontainer/brSMSearchClient

However, changing the resolver is generally not recommended.

Response Object Model

The API provides domain objects to represent search results:

QueryResponse
SearchResult
Document

These classes allow you to access the result set size, paging information, available facets, and the attributes specified with retrieveField() in your query. All classes are standard Java beans. For further details, refer to the Javadoc.