Search Configuration Reference

Search in Liferay DXP can be configured in lots of ways. Once you understand the concept of configuration scope, you’ll understand where to find a certain configuration screen.

  • Many search configurations affect the system scope (e.g., re-indexing actions and configuring the search engine connector).

  • Search tuning configurations affect the virtual instance.

  • Creating new Search Pages affects search at the site scope.

  • Configuring the search widgets is widget-scoped configuration, but some can also be thought of as page-scoped configuration.

So the term Configuring Search is very broad, as it addresses all the available scopes. This is a high level overview of what search behavior is configurable out of the box, and importantly, where to find search configuration options.

Widget Scoped Search Configuration

Several search widgets are available to place on Pages. Each one has its own configuration options.

Each widget's configuration will be unique.

Search Widgets

For dedicated coverage of the search widgets, see Search Pages and Widgets.

Search Results: Configure how search results are displayed. Read Displaying Search Results for more information.

Search Bar: Configure the behavior of how search keywords are processed. See Configuring the Search Bar for more information.

Search Facets: Configure each facet’s behavior and URL parameters. See Facets for more information.

Search Options: This is a special case, where configuring this widget defines page scoped behavior. Add the Search Option widget to a page and define two booleans for the Search Page:

  • Allow Empty Searches: By default, failure to enter a keyword returns no results. Enabling this ensure that all results are returned when no keyword is entered in the Search Bar.

  • Basic Facet Selection: By default, facet counts are recalculated after each facet selection. Enable this to turn off facet recounting.

Search Suggestions: Suggest better queries and spell check queries. See the Suggestions Configuration Reference for more information.

Search Insights: Add this to the Search Page to inspect the full query string that’s constructed by the back-end search code when the User enters a keyword. Only useful for testing and development. See Search Insights for more information.

Custom Filter: Add a widget to the page for each of the filters you’d like applied to the search results. Let search page users see and manipulate the filters or make them invisible and/or immutable. See Filtering Search Results for more information.

Sort: Let Users reorder the search results based on the value of certain keyword fields in the index. For example, show results in alphabetic order of the Title field. The default order is determined by the search engine’s Relevance calculation. See Sorting Search Results for more information.

Low Level Search Options: Configure the search widgets to participate in a search that’s aimed at an index other than the Company Index. The company index is where the Liferay DXP assets index their data, so many installations will not need this widget. See Understanding Low Level Search Options for more information.

Similar Results: Display similar search results to an asset being displayed on a page. See Similar Results for more information.

[Liferay Enterprise Search] Elasticsearch Monitoring: Liferay Enterprise Search subscribers can access Elastic’s Kibana monitoring tool inside a widget placed on a Liferay DXP Page. See Monitoring Elasticsearch for more information.

Site Scoped Search Configuration

By the strict definition of Site Scoped Configuration, search doesn’t have any. However, Search Pages influence Site-specific search behavior. Commonly, Search Pages contain search widgets configured to search for all content within a particular Site.

Configure the scope of a search.

There are some important configuration nuances to be aware of when using the Search widgets:

If the header Search Bar (the search bar embedded in the default theme) uses the Search Bar widget, its configuration always requires a destination page to be set, where Users are redirected to complete their search activity, interacting with the other Search widgets (Results, Facets, Suggestions etc.). Search destination pages are ordinary pages holding the Search widgets. You can have as many pages with Search widgets across the Site as you want.

The Search Bar widget is instanceable, so one page can contain multiple Search Bar widgets configured differently. All Search Bar instances must point to a Search Page within the Site to be effective.


If the destination Search Page has a Search Bar widget instance in addition to a theme-embedded header Search Bar (like Liferay’s default theme), the configurations of the header Search Bar take precedence over the page’s widget instance.

Conversely, searching from a Search Bar widget instance on other pages honors their configurations, even if they differ from the header Search Bar configuration.

See Configuring the Search Bar for more information.

Instance Scoped Search Configuration

Search does not have any Instance scoped entries in the Instance Settings panel. However, there are entries for configuring the instance-wide default widget template for many search widgets. Just enter the Site ID where the template is defined (often this will be the Global site’s ID, found in its Site Settings panel) and the Widget Template ID, found in the Site Menu → Design → Widget Templates.

The only instance scoped configurations for search are the entries in the Global Menu → Applications → Search Tuning:

Result Rankings: Customize search results manually by hiding, pinning, and adding results for specific aliases. See Result Rankings for more information.

Synonyms: Create synonym sets so that synonymous search terms are matched and scored like an exact match to the search term. See Synonym Sets for more information.

System Scoped Search Configuration

System scoped search configurations are primarily found in System Settings.

  1. In the Global Menu, go to Control PanelConfigurationSystem Settings.

  2. Click the Search category under the Platform section.

    Alternatively, search for search.

There are numerous system scoped entries for search in System Settings.

System Settings can also be configured via OSGi configuration file. The file names re included here.

Category Facet Field

7.4 U47+ and GA47+

Configuration File:

The Category Facet Field entry contains one setting: Category Facet Field. This setting specifies the indexed field to use when creating aggregations in the Category Facet. The default value is assetCategoryIds. You must instead use assetVocabularyCategoryIds to enable selecting which vocabularies and categories to display in the Category Facet widget. Learn more in the Category Facet documentation.

Default Keyword Query

Configuration File:

The Default Keyword Query entry contains one setting:

disabledEntryClassNames: The DefaultKeywordQueryContributor code automatically adds description, userName, and title fields to the keyword search query. Specify the entry class names DefaultKeywordQueryContributor should ignore.

Default Search Result Permission Filter

Configuration File:

The Default Search Result Permission Filter entry allows configuration of post-filtering permission checking (database permission checking that occurs after the results are returned from the search index). Read Final Permissions Checking for more information on these settings:

  • permissionFilteredSearchResultAccurateCountThreshold

  • searchQueryResultWindowLimit

Index Status Manager

Configuration File:

The Index Status Manager entry has one setting:

indexReadOnly: Enable this to suspend all indexing operations and writes to the search engine. Searches return only the documents already indexed. This is useful for speeding up large data imports, but it should be disabled and a full re-index executed once the import is finished.

Indexer Writer Helper

Configuration File:

The Index Writer Helper entry contains one entry:

indexCommitImmediately: When true (the default), each write request forces the search engine to refresh the index reader, potentially flushing transactions to disk. This may negatively impact search engine performance. The default behavior is to commit immediately for index writing on individual assets (e.g. add blog, update blog) but delay commits for bulk index writing operations (e.g. index all users, index all form entries) until all entries have been sent to the search engine. Setting this to false changes the behavior for individual index operations, and may cause applications like Asset Publisher to exhibit a delayed response when showing newly added content. See the Elasticsearch documentation for more information.

Indexer Registry

Configuration File:

Configure the buffering of index requests:

buffered: Enable (the default) or disable the buffering of indexing requests.

bufferedExecutionMode: Allow administrators to select a different IndexerRequestBufferExecutor, used to execute a IndexerRequest. One implementation of the executor is provided out of the box (DEFAULT). When a new IndexerRequestBufferExecutor implementation is deployed, one of the required properties is a buffered.execution.mode. This value can then be used in place of DEFAULT.

maximumBufferSize: If buffering is enabled, set the Maximum Buffer Size so that any additional indexing requests are executed immediately.

minimumBufferAvailabilityPercentage: When the capacity of the buffer has only the specified percent of space left, the existing requests in the buffer are executed in one batch and removed from the buffer.

Index Query Preprocessor

Configuration File:

This entry has one repeatable property (use array syntax if you’re defining via OSGi configuration file):

fieldNamePatterns: Fields with names matching the patterns set here are treated as non-analyzed keyword fields. Instead of scored full text queries, matching is performed by non-scored wildcard queries. This is a resource intensive operation that degrades search engine performance as indexes grow larger. For substring matching, relying on the ngram tokenizer usually performs better.


Configuration File:

This entry contains only one property:

indexingBatchSizes: Set the number of documents (the default value is 1000) indexed per batch for model types that support batch indexing. For models with large documents, decreasing this value may improve stability when executing a full re-index.

Engine Helper

Configuration File:

This entry has one repeatable property (use array syntax if you’re defining via OSGi configuration file):

excludedEntryClassNames: Exclude an asset type from being searched in the catchall query constructed for the Search application. For example, fields of the Organization asset must be indexed to be searchable from the Users and Organizations application, but should not be searched in the Search application. Thus, Organizations are added to excludedEntryClassNames.

Permission Checker

Configuration File:

This entry has one configuration option in Liferay DXP 7.3:

permissionTermsLimit: Limits the number of permission search clauses added to the search query before this level of permission checking is aborted. Permission checking then relies solely on the final permission filtering described in the Default Search Result Permission Filter section.

Title Field Query Builder

Configuration File:

Configure how search responds to matches on the Title field of a document.

exactMatchBoost: Give an additional boost when searched keywords exactly match the title field of a document.

maxExpansions: Limit the number of documents to return when matching searched keywords to the title field as a phrase prefix. See Elasticsearch’s Match Phrase Query documentation for more information.

Cross-Cluster Replication

You’ll only see this entry if you have deployed the Cross-Cluster Replication module, which is available with a Liferay Enterprise Search subscription. These configuration properties are covered in the dedicated Cross-Cluster Replication documentation.

Elasticsearch Monitoring

Configuration File:

You can use the Elasticsearch Monitoring configuration if you have deployed the Liferay Enterprise Search Monitoring module, available with a Liferay Enterprise Search subscription. These configuration properties are covered in the dedicated Monitoring Elasticsearch documentation.

Elasticsearch 7

Configuration File:

Configure the connection between Liferay and Elasticsearch 7. See Configuring the Connector for detailed coverage of these properties.

Elasticsearch Connections

Configuration File:[connectionId].config

Liferay 7.3 can connect to multiple Elasticsearch clusters. Connections are defined in the Elasticsearch Connections entry. This feature can be used in conjunction with the Low Level Search Options and Search Results widgets to show results from third-party systems using Elasticsearch clusters. It’s also demonstrated in the Cross-Cluster Replication documentation.

Learning to Rank

Configuration File:

You can use the Learning to Rank configuration if you have deployed the Liferay Enterprise Search Learning to Rank module, available with a Liferay Enterprise Search subscription. These configuration properties are covered in the dedicated Learning to Rank documentation.

Search Web

Configuration File:

This entry contains one property:

classicSearchPortletInFrontPage: Revert the default search experience from using the new Search Widgets to the deprecated classic Search Portlet that was standard in past releases.


Configuration File:

This entry has one repeatable property (use array syntax if you’re defining via OSGi configuration file):

synyonymFilterNames: Set the synonym filter names to apply. These filters must be defined in the Elasticsearch Index Settings. See Creating New Synonym Language Filters.

Search Administration

In Control PanelConfigurationSearch there are three administrative UIs: Connections, Index Actions, and Field Mappings.

See the dedicated Search Administration and Tuning documentation for more details.


Information about the search engine connection(s) is displayed here. For example,

  • Search Engine Vendor: Elasticsearch

  • Client Version: 7.17.1

  • Active Connections: 1

  • Health: Green

  • Connection ID: _REMOTE_

  • Connection Type: Read/Write

  • Cluster Name: LiferayElasticsearchCluster

  • Nodes: 1

  • Node Name: lr-es

  • Node Version: 7.15.1

Index Actions

In Index Actions, re-index at one of these levels:

  • All indexable assets

  • An individual indexable asset

  • All spell check indexes

Field Mappings

Portal Properties

Portal properties are system scoped as well. The Lucene Search portal properties configure low level search behavior. Review the properties and their descriptions and determine if they apply to your search requirements.