1 HstQuery Bootstrapping

Accessing the HstQueryManager

You can obtain an HstQueryManager from the current request context. The method you use depends on your execution context.

In an HstComponent

When working within an HstComponent that extends BaseHstComponent, retrieve the HstQueryManager from the request context:

public class LatestItems extends BaseComponent {
    @Override
    public void doBeforeRender(HstRequest request, HstResponse response) {
        final HstRequestContext context = request.getRequestContext();
        final HstQueryManager hstQueryManager = context.getQueryManager();

        [...]
    }
}

In a JAX-RS Service Resource

If you are in a JAX-RS resource that extends org.hippoecm.hst.jaxrs.services.AbstractResource, use the following approach:

@Path("/products/")
public class ProductPlainResource extends AbstractResource {
    @GET
    @Path("/{productType}/")
    public List<ProductRepresentation> getProductResources(....) {
        final HstRequestContext requestContext = RequestContextProvider.get();
        final HstQueryManager hstQueryManager = context.getQueryManager();

        [...]
    }
}

Without an HstRequestContext

If no HstRequestContext is available (for example, in background processes or integrations outside of HTTP requests), you can obtain an HstQueryManager via the Spring Component Manager:

Repository repo = HstServices.getComponentManager().getComponent(Repository.class.getName());
Credentials creds = HstServices.getComponentManager().getComponent(Credentials.class.getName() + ".default");
ContentBeansTool cbt = HstServices.getComponentManager().getComponent(ContentBeansTool.class.getName());

Session session = null;
try {
    session = repo.login(creds);
    HstQueryManager queryManager = cbt.createQueryManager(session);
} finally {
    if (session != null) session.logout();
}

Creating a New HstQuery

After obtaining the HstQueryManager, you can create a new HstQuery in several ways. The most common method is shown below. For additional options, refer to the Javadocs at org/hippoecm/hst/content/beans/query/HstQueryManager in the Site Toolkit API.

The createQuery method signature:

/**
* Creates a query, with scope HippoBean and Filter for types of filterBean. If
* includeSubTypes is <code>true</code>, the result may also contain
* HippoBean's whose primarytype is a subtype of the filterBean type.
*
* @param scope
* @param filterBean
* @param includeSubTypes
* @return a new <code>{@link HstQuery}</code> with scope & filter
* @throws QueryException
*/
HstQuery createQuery(HippoBean scope, Class<? extends HippoBean> filterBean,
                     boolean includeSubTypes) throws QueryException;

Parameters:

HippoBean scope: Defines the subtree in the repository to search. A HippoBean represents a JCR Node, which marks a location in the content tree. The scope determines where the query will search for documents.
Note: Some HstQueryManager methods accept a JCR Node directly instead of a HippoBean, such as HstQuery createQuery(Node node, Class<? extends HippoBean> filterBean, boolean includeSubTypes).
Class<? extends HippoBean> filterBean: Filters results to only include beans of this type. If includeSubTypes is true, subtypes are also included.
includeSubTypes: If true, results include subtypes of the specified filterBean.

Example: Creating an HstQuery in an HstComponent that extends BaseHstComponent:

HippoBean scope = request.getRequestContext().getSiteContentBaseBean();
try {
    // Create a query to search below 'scope' for beans of type BaseDocument or its subtypes
    HstQuery hstQuery = request.getRequestContext().getQueryManager().createQuery(scope, BaseDocument.class, true);

    [...]
} catch (QueryException e) {
    throw new HstComponentException("Exception occurred during creation of HstQuery.", e);
}

Setting Limit and Offset

Always set a limit on your query. If you do not specify a limit, the HST framework defaults to a limit of 1000. For best performance, set the limit to the number of items you want to display (for example, your page size). Use the offset to paginate results.

For example, to display the third page with a page size of 10:

hstQuery.setLimit(pageSize);
hstQuery.setOffset(pageSize * (currentPage - 1));

When you set a limit (for example, 10), HstQueryResult#getSize() returns at most 10. To determine the total number of results (for example, for pagination), use getTotalSize(), which returns the total number of hits.

Always Set a Limit

If you do not set a limit, HST applies a default limit of 1000. This value is high and may cause slower queries. For optimal performance, always set a limit appropriate to your use case, and use an offset if needed.

Sorting Results

You can sort HstQuery results by one or more properties, in either ascending or descending order. The sort order is determined by the sequence in which you add properties to the query. Sorting is only supported on properties that are stored directly on the document. You cannot sort by properties that are part of a compound type within the document.

Example: Sorting and ordering

// Sort results by "example:date" in descending order (newest first)
hstQuery.addOrderByDescending("example:date");

// For results with the same "example:date", sort ascending by "example:title"
hstQuery.addOrderByAscendingCaseInsensitive("example:title");

// For results with the same date and title, sort descending by "hippostdpubwf:publicationDate"
hstQuery.addOrderByDescending("hippostdpubwf:publicationDate");

// Continue as needed

Sorting is only possible on properties that exist directly on the document.
See Sorting search results in a query can only be done on direct properties of Documents for more details.

Including or Excluding Additional Scopes

An HstQuery can search across multiple scopes or exclude specific scopes. Use addScopes to include additional scopes and excludeScopes to remove scopes from the search.

API for including or excluding scopes:

/**
 * Add scopes to search in.
 * If a scope is already excluded, it is removed from the excluded list.
 * @param scopes
 */
void addScopes(List<HippoBean> scopes);

/**
 * Add scopes to search in.
 * If a scope is already excluded, it is removed from the excluded list.
 * @param scopes
 */
void addScopes(Node[] scopes);

/**
 * Add scopes to exclude from search.
 * If a scope is already included, it is removed from the included list.
 * @param scopes
 */
void excludeScopes(List<HippoBean> scopes);

/**
 * Add scopes to exclude from search.
 * If a scope is already included, it is removed from the included list.
 * @param scopes
 */
void excludeScopes(Node[] scopes);

Example: Searching the entire site content and assets, and excluding comments:

HippoBean siteScope = getSiteContentBaseBean(request);
// To search in assets, use a generic filter such as HippoDocument.class, or specify all relevant bean classes
HstQuery hstQuery = queryManager.createQuery(siteScope, HippoDocument.class, true);

// Add extra scopes (e.g., assets)
List<HippoBean> extraScopes = new ArrayList<HippoBean>();
extraScopes.add(getAssetBaseBean(request));
hstQuery.addScopes(extraScopes);

// Exclude specific scopes (e.g., comments)
List<HippoBean> excludeScopes = new ArrayList<HippoBean>();
HippoBean commentsScope = siteScope.getBean("comments", HippoFolderBean.class);
excludeScopes.add(commentsScope);
hstQuery.excludeScopes(excludeScopes);