Facets - Elasticsearch

  Written by The Jahia Team
   Estimated reading time:

The Elasticsearch search provider version 2.1.0 introduces the ability to use facets on search results when using the Elasticsearch as a search provider in the 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 develop your own facet type, the corresponding documentation is available here.


Faceted search is a way to adjust or improve the standard search techniques with a facet navigation system, allowing users to narrow down search results by applying single or multiple filters based on the faceted classification of the content. In the scope of Digital Experience Manager, content can be classified by their fields or more complex aspects. An example of a field facet could be for example content type, 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 Web sites.
Please, refer to the section Installation requirements for the details of Elasticsearch Front-End Search package itself.


In order to use facets on search results, the Elasticsearch provider should be set as DX search provider and the setup has to be done, according to the steps, listed in the Setup section.
The module Search provider - Elasticsearch - Facets (search-provider-elasticsearch-facet) must be enabled on your site. This will bring components and views, required to use the field facet feature in your search results.


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

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

Additional fields for facets can be “enabled” by configuring the so-called mapped node subtypes for content and files:

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

in the configuration file named org.jahia.services.search.provider.elasticsearch.cfg, which is located under digital-factory-data/karaf/etc folder.
Note, please, the changes in the configuration are picked up by DX automatically, but adding new fields into the configuration will require re-indexing of the content. Please, refer to the section Elasticsearch setup for how to trigger content re-indexing manually.


Here we describe how to add Content type facet to your search results page using components, provided by the search-provider-elasticsearch-facet module (it must be enabled on your site for components to be available).
In the DX Edit or Studio modes, you can change your search results page and add the Field facet (Elasticsearch) component into your search page, e.g. into the right-side area.




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

  • Title: an optional component title.
  • Field: here you need to choose the facet field, you would like to use. In our example it is, the Content type.
  • Maximum number of result groups: the maximum number of different facet values, which will be retrieved. Default value is 10, which means the 10 facet values with the highest facet value count will be retrieved.
  • Label renderer: choose from the list of available renderers the one, which should be responsible for rendering a user-friendly label for the facet values. In our example, it will be the contentType renderer.
  • Sort by label (alphabetically): activate this checkbox if you would like your facet values to be sorted alphabetically by label when displayed in the search results page. By default, this option is not enabled and thus the facet values are sorted by count descending.

The following screenshot shows the fields of the Field facet (Elasticsearch) component in the edit UI:


After saving the component and publishing the changes on the search results page, your users can benefit from the created content type facet when performing searches.

If the search “hits” results, which are matching your field facet, the Field facet (Elasticsearch) component will show the facet values in the page and allow users to narrow down the result by “activating” one or multiple facet values.

Here is an example of a search on a Digitall demo site which shows facet results for the Content type facet (in this case, we also have configured news and events content to be  indexed as main resource types: see section Main Resource types for details):


The component displays content types of the search hits and their counts. By activating a facet value, users can narrow down the results for specific content type. The following screenshot shows the “filtered” search results, where News entry facet value was activated:


In case of multiple field facet components on the search results page, each of them is responsible for displaying its own facet values if applicable. The following screenshot shows facet results for two components on the search results page, one is the content type and the other is a facet on the event type property of event contents:


The search narrow down in case of multiple facet components applies multiple “filters”, depending on the facet values, activated. If multiple facet values are activated, they apply an “AND” filter, i.e. the results will match all activated facet values. The example below shows the narrowed down search, where the Event facet value of the Content type component and Show facet value of the Event type component are activated together:


Advanced usage

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


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

  • default view, where facet values are rendered as “buttons”
  • checkboxes view, where values are rendered as checkboxes with labels.

You can switch the component view by opening the Edit engine on your field facet components, switching to Layout tab, activating the View, selecting the desired view type in the combo box, saving your changes and publishing them. The following is a rendering for the two views, provided by default:


If a custom view is needed for your project, you could, of course, implement it easily in your module.

Label renderer

The renderer for a field facet is responsible for displaying a user-friendly label for facet values, which usually have “technical” nature.

The renderers are implemented using DX’s ChoiceListInitializer (or ModuleChoiceListInitializer if implemented in a module) and all of them are available in the Edit UI when selecting label renderer for the field facet.
Specific renderer should be chosen based on the type of the field, faceting is done on.
The Content type facet uses the special contentType renderer. The resourceBundle renderer is used for the event type field defined as follow:

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

The renderers could be quite complex, including not just simple rendering, but rather an advanced markup, like an image. An example of such a renderer is the flagcountry. If configuring and doing faceting on a country field, defined as:

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

The rendering with the flagcountry label renderer will be as shown below:


Develop your own facet type

The documentation regarding facet type development is available here.