This article covers a Hippo CMS version 7.7. There's an updated version available that covers our most recent release.

2 HstQuery Filter 

After you have bootstrapped the HstQuery, see HstQuery bootstrapping, you might want to apply some filters. This is not always the case, as for example a search like 'give me the latest 10 news documents below some folder' do not need a filter at all, but only HstQuery bootstrapping, e.g.

Query for latest 10 news documents:

// the scope, aka the folder, to search news items below
HippoBean scope = getContentBaseBean(request);
try {
    HstQuery hstQuery = getQueryManager(request).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);
}

However, if you for example want the latest 10 news documents that contain some word in the entire document, or some word in, say, the property "example:title", you need to apply a filter to the hstQuery. A filter can in turn have constraints like gimme only documents where the lastModifiedBy user equals 'someone' or can have free text search constraints like 'gimme only documents that contain some word'

First of all, creating a Filter can be done from a hstQuery:

Creating a new Filter and apply it to the hstQuery:

String query = ....
// create a new Filter
Filter filter = hstQuery.createFilter();
// apply the filter to the hstQuery
hstQuery.setFilter(filter);
// add to the filter a 'query' constraint. "." means to search in the entire document
filter.addContains(".", query);

Now, hstQuery.execute() will only return documents that match the free text search query. Note that "." means to search in the entire document.

In addContains and addNotContains, "." means to search in all the properties and child nodes of the Hippo document

By default, the repository indexes all text of a document: Thus, all its properties and all the properties of all descendant nodes. Searching on "." means searching in the entire document.

You can also search in just a single property, for example

Search for documents that match query in title:

// only return hits that match the query in the title
filter.addContains("example:title", query);

or in multiple properties, for example

Search for documents that match query in title AND in summary:

// only return hits that match the query in the title AND in the summary
filter.addContains("example:title", query);
filter.addContains("example:summary", query);

Adding multiple constraints to a single Filter all get AND-ed. Thus, the code snippet above only returns hits for documents that match the query in the property "example:title" and "example:example". See TODO-LINK 3_Nesting_HstQuery_Filters.html3 Nesting HstQuery Filters on how to OR constraints

Multiple constraints to a single Filter are AND-ed

The previous examples all searched in a property of a document. You can also search in a property of a descendant node (i.e. compound type) of a document. For example:

Search for documents that match query in a property of a compound:

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

Note that instead of the above, you are also allowed to write address/@example:street, thus including an "@" to indicate the property. Both versions are equivalent.

So, up to now, we have seen adding a free text search (addContains) on:

  1. a document

  2. on a property of a document

  3. on the property of a child/descendant node of the document

There are ofcourse more constraints than addContains that you can apply to a Filter. The opposite of addContains is addNotContains. These are the only two constraints that involve free text search. All the other constraints are more like "give me all documents where some property is equal/unequal/less/greater/between to X".

Instead of explaining all the constraints in detail, we'll just copy the constraints Javadocs part of the Filter.

Filter constraints:

/**
 * Adds a fulltext search to this Filter. A fulltext search is a search on the indexed text of the <code>scope</code>. When the
 * <code>scope</code> is just a <code><b>.</b></code>, the search will be done on the entire document. When the <code>scope</code> is
 * for example <code><b>@myproject:title</b></code>, the free text search is done on this property only. You can also point to properties of
 * child nodes, for example a scope like <code><b>myproject:paragraph/@myproject:header</b></code>
 * @param scope the scope to search in. <code>scope = "."</code> means searching in the entire node/document. <code>scope = "example:title"</code> only
 * searches in the property "example:title". <code>scope</code> is also allowed to be a path to a property in a descendant node, for example  <code>scope = "address/example:street"</code>. The
 * latter is equivalent to  <code>scope = "address/@example:street"</code>
 * @param fullTextSearch the text to search on
 * @throws FilterException when <code>scope</code> or <code>fullTextSearch</code> is <code>null</code>
 */
void addContains(String scope, String fullTextSearch) throws FilterException ;

/**
 * The negated version of {@link #addContains(String, String)}
 * @see {@link #addContains(String, String)}
 * @param scope the scope to search in. <code>scope = "."</code> means searching in the entire node/document. <code>scope = "example:title"</code> only
 * searches in the property "example:title". <code>scope</code> is also allowed to be a path to a property in a descendant node, for example  <code>scope = "address/example:street"</code>. The
 * latter is equivalent to  <code>scope = "address/@example:street"</code>
 * @param fullTextSearch the text to search on
 * @throws FilterException when <code>scope</code> or <code>fullTextSearch</code> is <code>null</code>
 */
void addNotContains(String scope, String fullTextSearch) throws FilterException ;

/**
 * Adds a constraint that the value <code>fieldAttributeName</code> is between <code>value1</code> and <code>value2</code>
 * @param fieldAttributeName the name of the attribute, eg "example:date"
 * @param value1 object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @param value2 object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code>, <code>value1</code> or <code>value2</code> are invalid types/values or one of them is <code>null</code>
 */
void addBetween(String fieldAttributeName, Object value1, Object value2) throws FilterException ;

/**
 * Adds a constraint that the value <code>fieldAttributeName</code> is NOT between <code>value1</code> and <code>value2</code>
 * @param fieldAttributeName the name of the attribute, eg "example:date"
 * @param value1 object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @param value2 object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code>, <code>value1</code> or <code>value2</code> are invalid types/values or one of them is <code>null</code>
 */
void addNotBetween(String fieldAttributeName, Object value1, Object value2) throws FilterException ;

/**
 * Adds a constraint that the value <code>fieldAttributeName</code> is equal to <code>value</code>
 * @param fieldAttributeName the name of the attribute, eg "example:author"
 * @param value object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code> or <code>value</code> is of invalid type/value or is <code>null</code>
 */
void addEqualTo(String fieldAttributeName, Object value) throws FilterException ;

    /**
 * Adds a constraint that the value <code>fieldAttributeName</code> is NOT equal to <code>value</code>
 * @param fieldAttributeName the name of the attribute, eg "example:author"
 * @param value object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code> or  <code>value</code> is of invalid type/value or is <code>null</code>
 */
void addNotEqualTo(String fieldAttributeName, Object value) throws FilterException ;

/**
 * Adds a constraint that the value <code>fieldAttributeName</code> is greater than or equal to <code>value</code>
 * @param fieldAttributeName the name of the attribute, eg "example:date"
 * @param value object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code> or  <code>value</code> is of invalid type/value or is <code>null</code>
 */
void addGreaterOrEqualThan(String fieldAttributeName, Object value) throws FilterException ;

/**
 * Adds a constraint that the value <code>fieldAttributeName</code> is greater than <code>value</code>
 * @param fieldAttributeName the name of the attribute, eg "example:date"
 * @param value object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code> or  <code>value</code> is of invalid type/value or is <code>null</code>
 */
void addGreaterThan(String fieldAttributeName, Object value) throws FilterException ;

/**
 * Adds a constraint that the value <code>fieldAttributeName</code> is less than or equal to <code>value</code>
 * @param fieldAttributeName the name of the attribute, eg "example:date"
 * @param value object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code> or  <code>value</code> is of invalid type/value or is <code>null</code>
 */
void addLessOrEqualThan(String fieldAttributeName, Object value) throws FilterException ;

/**
 * Adds a constraint that the value <code>fieldAttributeName</code> is less than <code>value</code>
 * @param fieldAttributeName the name of the attribute, eg "example:date"
 * @param value object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code> or  <code>value</code> is of invalid type/value or is <code>null</code>
 */
void addLessThan(String fieldAttributeName, Object value) throws FilterException ;

/**
 * <b>Try to not use this method as it blows up searches. This is Lucene (inverted indexes) related</b>
 * Set a constraint that <code>fieldAttributeName</code> matches *<code>value</code>* where * is a <b>any</b> pattern
 * @param fieldAttributeName the name of the attribute, eg "example:author"
 * @param value object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code> or  <code>value</code> is of invalid type/value or is <code>null</code>
 */
void addLike(String fieldAttributeName, Object value) throws FilterException ;

/**
 * <b>Try to not use this method as it blows up searches. This is Lucene (inverted indexes) related</b>
 * Set a constraint that <code>fieldAttributeName</code> does not matche *<code>value</code>* where * is a <b>any</b> pattern
 * @param fieldAttributeName the name of the attribute, eg "example:author"
 * @param value object that must be of type String, Boolean, Long, Double, {@link Calendar} or {@link Date}
 * @throws FilterException when <code>fieldAttributeName</code> or  <code>value</code> is of invalid type/value or is <code>null</code>
 *
 */
void addNotLike(String fieldAttributeName, Object value) throws FilterException ;

/**
 * Add a constraint that the result <b>does</b> have the property <code>fieldAttributeName</code>, regardless its value
 * @param fieldAttributeName the name of the attribute, eg "example:author"
 * @throws FilterException when <code>fieldAttributeName</code> is <code>null</code>
 */
void addNotNull(String fieldAttributeName) throws FilterException ;

/**
 * Add a constraint that the result <b>does NOT</b> have the property <code>fieldAttributeName</code>
 * @param fieldAttributeName the name of the attribute, eg "example:author"
 * @throws FilterException when <code>fieldAttributeName</code> is <code>null</code>
 */
void addIsNull(String fieldAttributeName) throws FilterException ;

/**
 * Adds the xpath <code>jcrExpression</code> as constraint. See jsr-170 spec for the xpath format
 * @param jcrExpression
 */
void addJCRExpression(String jcrExpression);