Upgrading Search Infrastructure

While upgrading Liferay, consider whether an Elasticsearch upgrade is required. The exact steps for upgrading depend on your existing search engine installation and Liferay version, but you should start by backing up your existing indexes.

When upgrading from Liferay DXP 2025.Q4 or below to Liferay DXP 2026.Q1 or above, additional steps are required. See Upgrading Search for Liferay DXP 2026.Q1+.
See the Search Engine Compatibility Matrix. Whenever possible, run the latest supported Elasticsearch version.
In Liferay DXP 7.4 and all subscription DXP quarterly releases (e.g., 2025.Q1), the Liferay Enterprise Search (LES) applications are bundled and enabled. No additional installation steps are required. See Activating Liferay Enterprise Search for more information.
If you’re already on a supported Elasticsearch version, you can continue using the existing Elasticsearch instance without updating it.
In Liferay DXP 7.4 and all DXP quarterly releases, the Search Tuning (Synonym Sets and Result Rankings) indexes are backed by database tables, and no search-specific upgrade steps are required. If upgrading from Liferay 7.2 or 7.3, the search tuning index data is propagated to Liferay’s database automatically if Liferay is connected to the same Elasticsearch cluster as the pre-upgrade system. If you are setting up a new Elasticsearch instance, you must backup and restore the search tuning indexes, then run a Groovy script to import the index data manually into the new database tables.

Upgrade Steps

Important

Back up the search indexes before proceeding with these steps.

Upgrade Elasticsearch. Make sure your system is at least on the minimum supported Elasticsearch version. If it’s not, move to the latest supported Elasticsearch.
Connect Liferay to Elasticsearch and configure security.
Upgrade Liferay.
Reindex the search indexes and spell check dictionaries.

Don’t forget to reindex the Workflow Metrics indexes.
Test the search experience in the upgraded system to ensure everything is working as expected.

If you’re on a Liferay DXP 7.4 or quarterly version and using the Liferay Enterprise Search applications, no installation steps are required, as they are bundled with Liferay DXP. If you’re on Liferay 7.2 or 7.3, read on to install the applications.

Upgrading Search for Liferay DXP 2026.Q1+

Elasticsearch 7 has reached end-of-life status as of Jan 15, 2026. For Liferay DXP 2026.Q1+, Elasticsearch 8.19+ is required (see the Search Engine Compatibility Matrix for more details). Elasticsearch 8.19+ is supported using a native Elasticsearch 8 Connector. Previous versions that supported Elasticsearch 8 used the Elasticsearch 7 connector and relied on Elasticsearch’s compatibility mode.

With the native Elasticsearch 8 connector comes the following requirements for your upgrade:

Upgrade Elasticsearch to 8.19+ Before Upgrading Liferay: You must upgrade your Elastic stack to at least version 8.19 and adjust your Liferay connector configurations before upgrading Liferay DXP to 2026.Q1+. Liferay DXP cannot be started with an incompatible Elasticsearch version. See Upgrading to Elasticsearch 8 for more information.

Warning

If you connect an existing Liferay DXP installation to a new, empty Elasticsearch 8.19 cluster, some application-driven indexes (e.g., the workflow metrics indexes) are not re-created when you reindex Liferay. Instead, follow one of the recommended approaches for the Elasticsearch upgrade (rolling restart or full cluster restart) to ensure that all indexes are transferred to the new Elasticsearch cluster.
Update Configuration File Names: The Elasticsearch connector configuration entries in System Settings and the deployable .config file names are changed. Adjust these in your Liferay DXP deployment before adding or mounting the files to [Liferay-Home]/configs. This step is mandatory even if you are already running Liferay DXP with Elasticsearch 8.19, and even if you are continuing with identical settings.

Old connector configuration file names (2025.Q4 and below):
- com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.config
- com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConnectionConfiguration-<connectionId>.config
New connector configuration file names (2026.Q1 and later):
- com.liferay.portal.search.elasticsearch8.configuration.ElasticsearchConfiguration.config
- com.liferay.portal.search.elasticsearch8.configuration.ElasticsearchConnectionConfiguration-<connectionId>.config
If you configured Elasticsearch in System Settings (in the Elasticsearch 7 configuration entry) in the pre-upgrade system, you can first export its configuration file. Once you have the .config files, rename them and review the properties. Make sure they are up-to-date and match your environment. See the Elasticsearch Connector Configuration Reference guide.
Test Custom Java Queries: If you are moving from Elasticsearch 7 to 8, API changes are expected. Review any custom OSGi modules using Liferay’s Java search APIs or low-level search engine adapter APIs and determine if adjustments are required for compatibility with the Elasticsearch 8 client APIs.
Test Search Blueprints: If you use custom query elements, paste any Elasticsearch query elements or advanced blueprints configurations (e.g., aggregation, highlight, sort), and test them after upgrading to a new major Elasticsearch version. Refer to the Elasticsearch Release Notes and Breaking Changes documentation.

Upgrading Liferay Enterprise Search on Liferay 7.2 and 7.3

Because LES and its apps are bundled with Liferay 7.4 and later, these steps are only required if upgrading to Liferay 7.2 or 7.3. Follow the basic upgrade steps, then these optional steps:

Install a Kibana version that matches the Elasticsearch version, if you are currently using Kibana and Monitoring.
Install and configure the LES applications applicable to your setup and version. See the LES Compatibility Matrix for details.

Test the Upgraded Search Experience

Manually test the upgraded search experience to ensure the features you depend on work as expected. If something is not working or is behaving differently than you expect, review the Breaking Changes documentation.

LES Applications Renamed after Liferay 7.2

LES Subscribers

These LES apps were renamed in the 7.3 life cycle to better reflect their functionality and to emphasize their identity as LES apps:

Functionality	Old App Name	New App Name	7.2 Configuration File	7.3+ Configuration File
Monitoring the Elasticsearch cluster	Liferay Connector to X-Pack Monitoring [Elastic Stack 6.x]	Liferay Enterprise Search Monitoring	`com.liferay.portal.search.elasticsearch6.xpack.monitoring.web.internal.configuration.XPackMonitoringConfiguration.config`	`com.liferay.portal.search.elasticsearch.monitoring.web.internal.configuration.MonitoringConfiguration.config`
Securing the Elasticsearch cluster	Liferay Connector to X-Pack Security [Elastic Stack 6.x]	Liferay Enterprise Search Security	No action required; this app is not available for DXP 7.4. Its features are integrated into the Elasticsearch connector.
Using machine learning to optimize the search algorithm	Liferay Connector to Elasticsearch Learning to Rank	Liferay Enterprise Search Learning to Rank	No changes.

The widget and configuration names are identical on Liferay 7.3+.

If you’re upgrading from Liferay 7.2, the renaming of apps and configurations has these upgrade impacts:

The LES Monitoring widget is now named Elasticsearch Monitoring. During startup, a module upgrade step runs, renaming the app when Liferay Enterprise Search Monitoring is deployed. No action is required.
The configuration file name changed from com.liferay.portal.search.elasticsearch6.xpack.monitoring.web.internal.configuration.XPackMonitoringConfiguration.config to com.liferay.portal.search.elasticsearch.monitoring.web.internal.configuration.MonitoringConfiguration. The properties are the same as before. During portal startup, a module upgrade step runs, renaming the configuration. No action is required.

The Kibana base path to the monitoring widget changed. You must change the original setting in kibana.yml:

server.basePath: "/o/portal-search-elasticsearch-xpack-monitoring/xpack-monitoring-proxy"

server.basePath: "/o/portal-search-elasticsearch-monitoring/monitoring-proxy"

Importing the Search Tuning Indexes in 7.4 and Quarterly Releases

The following Liferay DXP Search Tuning indexes are in the Elasticsearch cluster:

liferay-[companyId]-search-tuning-rankings
liferay-[companyId]-search-tuning-synonyms

If you were using the search tuning features in the pre-upgrade system, but the search tuning index documents are not present in the post-upgrade cluster, you must first backup and restore the search tuning indexes from the pre-upgrade cluster to the post-upgrade cluster, then run a Groovy script to manually import the index data into the new database tables. This can happen if you are connecting to a new Elasticsearch cluster instead of upgrading the pre-upgrade cluster.

To run the Groovy import script,

Go to the scripting console. Navigate to the Script tab in Control Panel → Server Administration.

Run the following script to import the Result Rankings data into its database table:

import com.liferay.portal.kernel.module.util.SystemBundleUtil
import com.liferay.portal.kernel.util.PortalUtil
import com.liferay.portal.search.tuning.rankings.storage.RankingsDatabaseImporter

import org.osgi.framework.BundleContext
import org.osgi.util.tracker.ServiceTracker

BundleContext bundleContext = SystemBundleUtil.getBundleContext();

ServiceTracker rankingsDatabaseImporterTracker = new ServiceTracker(
    bundleContext, RankingsDatabaseImporter.class.getName(), null)

try {
    rankingsDatabaseImporterTracker.open()

    RankingsDatabaseImporter rankingsDatabaseImporter = (RankingsDatabaseImporter) rankingsDatabaseImporterTracker.getService()

   for (long companyId : PortalUtil.getCompanyIds()) {
      rankingsDatabaseImporter.populateDatabase(companyId);
   }
} finally {
    rankingsDatabaseImporterTracker.close()
}

Run the following script to import the Synonym Sets data into its database table:

import com.liferay.portal.kernel.module.util.SystemBundleUtil
import com.liferay.portal.kernel.util.PortalUtil
import com.liferay.portal.search.tuning.synonyms.storage.SynonymSetsDatabaseImporter;

import org.osgi.framework.BundleContext
import org.osgi.util.tracker.ServiceTracker

BundleContext bundleContext = SystemBundleUtil.getBundleContext();

ServiceTracker synonymSetsDatabaseImporterTracker = new ServiceTracker(
    bundleContext, SynonymSetsDatabaseImporter.class.getName(), null)

try {
    synonymSetsDatabaseImporterTracker.open()

    SynonymSetsDatabaseImporter synonymSetsDatabaseImporter = (SynonymSetsDatabaseImporter) synonymSetsDatabaseImporterTracker.getService()

   for (long companyId : PortalUtil.getCompanyIds()) {
      synonymSetsDatabaseImporter.populateDatabase(companyId);
   }
} finally {
    synonymSetsDatabaseImporterTracker.close()
}

Make sure you test the Synonym Sets and Result Rankings to ensure everything is working as expected.

Resource Type:

Official Documentation

Feature:

Deployment Approach:

Liferay Self-Hosted