Custom Facet - Liferay Official Documentation

Submit Feedback

The Custom Facet is unique among the out-of-the-box search facets. Rather than always grouping results by a single static field (like the modified date or the asset type), you can choose an available aggregation type and specify which field to group results by. With the custom facet you can create an entirely new facet to suit your needs. For example, you can create a facet for the Create Date field and specify your own date ranges, creating a facet similar in functionality to the Modified Facet.

For examples, including using the nested fields of objects and web content structures, see the Custom Facet Examples article.

Important

Finding the right fields and their types in the index is important when using the Custom Facet. See Exploring Indexed Fields for more details.

Click Add () at the top of the page.
Locate the Custom Facet and drag it to the collection of facets on the left. The Custom Facet is found under the Search section of widgets.
Click Options () → Configuration.

Note

Before Liferay DXP 2025.Q1/Portal GA132, the Configuration option appeared in the widget’s top-right corner.

The Custom Facet’s configuration options are described below.
When finished, click Save.

Important

In Liferay DXP 2024.Q4+/Portal GA129+, the available settings in the Custom Facet were changed and reordered to allow for more customizations. Range and Date Range aggregation types are now supported, and more out-of-the-box display templates are available. The latest available changes appear here. If you are on an older version, your configuration may lack some options or appear in a different order.

Aggregation Settings

Aggregation Type: Choose the type of aggregation: Terms, Date Range, or Range. If you choose one of the ranges, a new section appears in the configuration: Ranges Configuration. See Configuring Ranges for more information.

Aggregation Field: Enter the name of the indexed field to aggregate results by. This must be a non-analyzed keyword field. See Exploring Indexed Fields for more information.

Display Settings

Display Template: Choose between Default, Checkbox Layout, Compact Layout, Label Layout, and Radio Button Layout. See Using Search Widget Display Templates for more information.

Custom Heading: Enter the heading to display for this facet. If not set, the aggregated field name appears.

Custom Parameter Name: Specify a URL parameter name for selected values. If not set, the aggregated field name is used.

Max Terms: Set the maximum number of facet terms to display, regardless of how many matching terms are found for the facet. This is only available if using the terms aggregation type.

Frequency Threshold: Set the minimum frequency required for terms to appear in the list of facet terms. For example, if the frequency threshold of a facet is set to 3, terms with two matching results don’t appear in the term result list.

Order By: For Liferay 7.4 U60+/GA60+, you can choose the facet term sorting strategy: order by Term Frequency in ascending or descending (default) order, or by Value in ascending or descending order. In the case of a Range or Date Range aggregation type, you can choose to order the facet terms by the order the ranges are defined in the configuration form. The default sorting orders facet terms from most matches to least.

Display Frequencies: Choose whether to display the term frequencies.

Advanced Configuration

Federated Search Key: Enter the key of an alternate Search this widget is participating on. If not set, this widget participates on the default search. This value is typically the name of an application-defined index.

Configuring Ranges

Liferay DXP 2024.Q4+/Portal GA129+

If you choose a date range or range aggregation type, a section called Ranges Configuration appears in the configuration form. This is where you set the different ranges that comprise the facet terms. Each range value is enclosed in square brackets (e.g., [past-hour TO *] or [0 TO 50]).

The checkbox setting Show Input Ranges enables or disables adding custom ranges in the facet.

Date Ranges

Date range aggregations are for use with date fields. You can find date fields in the mappings:

"createDate" : {
 "format" : "yyyyMMddHHmmss",
 "type" : "date"
}

By default, the available time ranges are for the last 1 hour, 24 hours, 1 week, 1 month, or 1 year. The from values in these ranges are supported by special aliases to simplify the expressions: past-hour, past-24-hours, past-week, past-month, and past-year. All the default time ranges end in * as the to value, which evaluates to the current time, now.

You can create date ranges with these aliases or the search engine’s supported date math syntax:

Tip

Results matching the from value are included in the facet term, but results matching to to value are excluded.

Ranges

Range aggregations operate on numeric data and allow the user to create facets based on arbitrary ranges. For example, a Commerce Product has a base price field that’s indexed with the type double: