Add Constraints to a Query using the Fluent Search API

Info: This feature is available in Bloomreach Content (formerly Hippo CMS) version 11.1.0 and later.

Overview

This page explains how to add constraints to a search query using the Fluent Search API.

When to Use Constraints

The Fluent Search API in the delivery tier (HST) provides a fluent interface for building search queries. Use constraints when you need to filter search results based on specific criteria that are not available through query builder bootstrapping. For example, you may want to:

Retrieve the latest 10 news documents containing a specific word anywhere in the document.
Search for a word within a specific property, such as example:title.

Implementation

Add Constraints with HstQueryBuilder

To add constraints, use the where method in the query builder. The following example demonstrates how to search for documents containing a query string anywhere in the document:

String query = ....

HippoBean scope = RequestContextProvider.get()
                    .getSiteContentBaseBean()
                    .getBean(relativePathToFolderX);
final HstQuery hstQuery = HstQueryBuilder.create(scope)
        .ofTypes(NewsDocument.class)
        // create and set a constraint,
        // meaning to do full text search by query in the documents.
        .where(constraint(".").contains(query))
        .limit(10)
        .orderByDescending("example:date")
        .build();

HstQueryResult result = hstQuery.execute();

In this example, hstQuery.execute() returns documents that match the free text search specified by query.

Note: You do not need to check for null values in constraints. If query is null, the constraint is automatically skipped.

The repository indexes all text in a document, including all properties and properties of descendant nodes. To perform a full-text search across the entire document, use the relative XPath "." as shown:

.where(constraint(".").contains(query))

Search in a Single Property

To search within a specific property, specify the property name:

        // SNIP
        // only return hits that match the query in the title
        .where(constraint("example:title").contains(query))
        // SNIP

This constraint returns documents where the example:title property matches the query string.

Search in Multiple Properties (AND)

To require that a query matches in multiple properties, combine constraints with a logical AND:

        // SNIP
        // only return hits that match the query in the title AND in the summary
        .where(
                and(
                        constraint("example:title").contains(query),
                        constraint("example:summary").contains(query)
                )
         )
         // SNIP

This example returns documents where both example:title and example:summary contain the query string.

Search in Multiple Properties (OR)

To match documents where the query appears in either of two properties, use a logical OR:

        // SNIP
        // only return hits that match the query in the title OR in the summary
        .where(
                or(
                        constraint("example:title").contains(query),
                        constraint("example:summary").contains(query)
                )
         )
         // SNIP

This constraint returns documents where either example:title or example:summary matches the query.

Search in Properties of Descendant Nodes

To search within a property of a descendant node (such as a compound type field), specify the path:

        // SNIP
        .where(constraint("example:address/example:street").contains(query))
        // SNIP

Alternatively, you can specify the property using the @ symbol:

example:address/@example:street

Both approaches are equivalent.

Additional Constraint Methods

Besides contains(...), you can apply other constraints:

notContains(...) — Excludes documents containing the specified text.
Equality and comparison constraints — Filter based on exact values or value ranges.

contains(...) and notContains(...) are the only constraints that perform free-text search. Other constraints handle equality or comparison.

Note: Import static methods such as constraint(String) from org.hippoecm.hst.content.beans.query.builder.ConstraintBuilder to use them directly in your code:
import static org.hippoecm.hst.content.beans.query.builder.ConstraintBuilder.constraint;
import static org.hippoecm.hst.content.beans.query.builder.ConstraintBuilder.and;
import static org.hippoecm.hst.content.beans.query.builder.ConstraintBuilder.or;