2 HstQuery Filter

After you initialize an HstQuery, you can apply filters to constrain the query results. For details on initializing an HstQuery, see HstQuery Bootstrapping.

Filters are optional. For example, if you want to retrieve the latest 10 news documents from a specific folder, you do not need to use a filter:

// Define the scope (folder) to search for news items
HippoBean scope = request.getRequestContext().getSiteContentBaseBean().getBean(relativePathToFolderX);
try {
    HstQuery hstQuery =
        request.getRequestContext().getQueryManager().createQuery(scope, NewsDocument.class, true);
    hstQuery.setLimit(10);
    hstQuery.addOrderByDescending("example:date");
    HstQueryResult result = hstQuery.execute();
} catch (QueryException e) {
    throw new HstComponentException(
          "Exception occured during creation or execution of HstQuery.", e);
}
copy

In cases where you need to restrict results further—such as retrieving the latest 10 news documents containing a specific word anywhere in the document, or within a particular property like example:title—you must apply a filter to the HstQuery. A filter defines constraints, such as "Return only documents where the lastModifiedBy user equals X" or "Return only documents containing word W".

To create and apply a filter:

String query = ....
// Create a new Filter. The HstQuery acts as a Filter factory.
Filter filter = hstQuery.createFilter();
// Attach the filter to the hstQuery
hstQuery.setFilter(filter);
// Add a 'contains' constraint. "." searches the entire document.
filter.addContains(".", query);
copy

After you set the filter, hstQuery.execute() returns only documents that match the free text search query.

When you use "." as the first argument to addContains() or addNotContains(), the search includes the entire document—covering all child nodes and all properties.

By default, the repository index includes all text from a document, including all properties and all descendant node properties. Searching on "." searches the complete document content.

To search within a single property, use the property name as the first argument:

// Return hits where the title matches the query
filter.addContains("example:title", query);
copy

To search within multiple properties, add multiple constraints to the filter:

// Return hits where both the title AND the summary match the query
filter.addContains("example:title", query);
filter.addContains("example:summary", query);
copy

When you add multiple constraints to a single Filter, they are combined with a logical AND. In the example above, only documents where both example:title and example:summary match the query are returned. For information on combining constraints with OR, see Nesting HstQuery Filters.

You can also search within a property of a descendant node (such as a compound type field):

filter.addContains("example:address/example:street", query);
copy

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

filter.addContains("example:address/@example:street", query);
copy

Both approaches are equivalent.

In summary, you can use addContains() to perform free text searches on:

1. The entire document
2. A specific property of the document
3. A property of a child or descendant node of the document

In addition to addContains(), you can use other constraints with a filter. The opposite of addContains() is addNotContains(). These two methods support free text search. Other filter constraints allow you to test for equality or compare values.

For more information, refer to the Filter interface in the Site Toolkit API.