Facets - Elasticsearch

November 11, 2022

The Elasticsearch search provider version 2.1.0 enables you to use facets on search results with Elasticsearch as a search provider in Digital Experience Manager. This section provides an overview of the facets on search results feature, its configuration and details on usage.

If you are a developer and want to create your own facet type, see Developing a custom facet type.

Faceted search enhances standard search techniques with a facet navigation system and enables users to narrow down search results by applying one or more filters depending on how you classify facets for your content. In Digital Experience Manager, content can be classified by their fields or more complex aspects. For example, field facets can be content types, tags, keywords or values of a specific content field.


The facets feature requires the following:

  • Digital Experience Manager or later
  • Elasticsearch Front-End Search - Enterprise Distribution 2.1.0 or later

The Elasticsearch Front-End Search 2.1.0 package delivers a new module: Search provider - Elasticsearch - Facets (search-provider-elasticsearch-facet), which adds an implementation of a field facet to your DX powered websites. For details on the Elasticsearch Front-End Search package, see Installation requirements.

To use facets on search results, the Elasticsearch provider must be set as your DX search provider. You must also setup Elasticsearch using the steps in the Setup section.
The Search provider - Elasticsearch - Facets (search-provider-elasticsearch-facet) module must be enabled on your site. This will add the components and views required by the field facet feature in your search results.

Enabling fields for facets

Out-of-the box, the following system fields are available for faceting:

  • Content type
  • Creator
  • Last contributor
  • Last publisher
  • Keywords
  • Tags

You can enable additionional fields for faceting by editing the org.jahia.services.search.provider.elasticsearch.cfg configuration file, which is located in the digital-factory-data/karaf/etc folder. Add the node subtypes by providing these fields under their primary type:

  • org.jahia.services.search.provider.elasticsearch.content.mappedNodeTypes
  • org.jahia.services.search.provider.elasticsearch.file.mappedNodeTypes

Note that changes in the configuration are applied by DX automatically. However, if you add new fields to the configuration, you must reindex the content. Refer to the Elasticsearch setup section for information on manually reindexing content.

Adding facets in Edit or Studio mode

This section describes how to add the Content type facet to your search results page using components provided by the search-provider-elasticsearch-facet module. The module must be enabled on your site for components to be available.
In the DX Edit or Studio modes, you add the Field facet (Elasticsearch) component to your search results page, for example, to the right-side of the page.




The Field facet (Elasticsearch) component accepts the following properties:

  • Title
    An optional component title.
  • Field
    The facet field that you would like to use. In the example, the field is Content type.
  • Maximum number of result groups
    The maximum number of different facet values that will be retrieved. The default value is 10, which means that the 10 facet values with the highest facet value count will be retrieved.
  • Label renderer
    The renderer that is responsible for rendering a user-friendly label for the facet values. In the example, the renderer is contentType.
  • Sort by label (alphabetically)
    Whether to sort facet values alphabetically by label when they display in the search results page. By default, this option is not enabled and the facet values are sorted in descending order.

The following image shows fields for the Field facet (Elasticsearch) component in Edit mode.


After saving the component and publishing changes on the search results page, your users can use the new content type facet when performing searches. If a search returns results that match your field facet, the Field facet (Elasticsearch) component displays the facet values on the page. Users can narrow down the search result by selecting one or more facet values.

The following example of a search on the Digitall demo site shows facet results for the Content type facet. The component displays the number of search hits for each content type. In the example, news and events content are configured and indexed as main resource types. For more details, see the Main Resource types section.


Users can select a facet value to narrow down the results for a specific content type. The following image shows filtered search results with the News entry facet value selected.


When multiple field facet components display on the search results page, each component is responsible for displaying its own facet values. The following image shows facet results for two components on the search results page: Content type and the Event type property of event contents.


The search applies multiple filters when multiple facet components are selected, depending on facet values. When multiple facet values are selected the AND filter applies, meaning that results will match all selected facet values. The example below shows search results where the Event facet value of the Content type component and Show facet value of the Event type component are both selected.


Configuring the display of components

The section shows advanced usage of the views and label renderers for the field facet component, delivered with the search-provider-elasticsearch-facet module.

Setting the view display for components

Out-of-the-box, the Field facet (Elasticsearch) component provides two views for displaying facet values:

  • default
    Facet values are rendered as buttons
  • checkboxes
    Facet values are rendered as checkboxes with labels

To change the component view:

  1. Open the Edit engine for a field facet component.
  2. Select the Layout tab.
  3. Activate the View.
  4. Select the desired view type in the combo box
  5. Save and publish your changes.

The following image shows a rendering of the two views:


If you require a custom view for your project, you can easily implement it in your module.

Applying the label renderer to a facet

The renderer for a field facet displays a user-friendly label for facet values, rather than the name that displays in code.

The renderers are implemented using DX’s ChoiceListInitializer (or ModuleChoiceListInitializer if it is implemented in a module) and are available in Edit mode when selecting the label renderer for the field facet. A specific renderer should be chosen based on the type of the field that faceting is performed on.
The Content type facet uses the special contentType renderer.

The resourceBundle renderer is used for the event type field defined as follows:

[jnt:event] > jnt:content, jmix:editorialContent, mix:title, jmix:structuredContent
 - eventsType (string, choicelist[resourceBundle]) facetable  < meeting,consumerShow,roadShow,conference,show,pressConference

The label renderers can support advanced markup, such as rendering of an image. For example, the flagcountry label renderer can display a country name and its flag. Faceting on a country field is defined as:

[jnt:job] > jnt:content, mix:title, jmix:editorialContent, jmix:structuredContent
 - country (string, choicelist[country,flag]) facetable

The flagcountry label renderer displays the label as:


Developing a custom facet type

For information on facet type development, see Developing a custom facet type.