Understanding Liferay DXP's compatibility with Elasticsearch

Introduction

Last updated: February 13, 2025.

The Search Product Team often receives questions about Liferay DXP's compatibility with Elasticsearch. This seemingly simple question belies surprising complexity: it depends on multiple factors, some of which are external dependencies for Liferay.

The answer to your simple compatibility question is usually dependent on a combination of these sub-questions:

  1. Which Major version of Elasticsearch (e.g., 7.x, 8.x) is my version of Liferay DXP compatible with?
  2. What is the Minor version range of Elasticsearch (e.g., 7.16-7.17) I can run my cluster on to connect with my version of Liferay DXP?
  3. What is the minimum DXP Update Version/Quarterly Release Version or Patch Level (e.g., 7.4 U120, DXP 2024.Q2 or 7.2 SP3/FP8) I need to connect to these Elasticsearch versions?
  4. Is it mandatory to install the connector from Marketplace (and if so, which version---e.g., 3.0.0, 3.0.1, or 3.1.0) or can I use the default bundled connector?

This article is meant to demystify these underlying compatibility questions without getting too lost in the technical details. After reading this, you will better understand why keeping things simple while simultaneously providing compatibility with a wide range of Elasticsearch versions is a challenging endeavor.

Environment

  • Liferay DXP 7.0-7.4 and DXP Quarterly Releases (latest versions/patch levels**)
  • Liferay PaaS and Self-Hosted

Target Audience

  • Liferay DXP Administrators and DevOps Engineers
  • Support Engineers
  • Consultants/Sales Engineers

Table of Contents

Source of Compatibility Information

The Search Engine Compatibility Matrix can help answer your questions about compatibility with Elasticsearch.

General take-away: Before installing a new connector from Marketplace or moving to a newer DXP release, always consult with these resources to see if the Elasticsearch compatibility has changed.

What Influences the Compatibility

  1. Liferay DXP version and patch level: determines the list of available Elasticsearch connectors and thus, the supported major versions
  2. Liferay Elasticsearch connector version (if it is installed from Marketplace)
  3. Elasticsearch client version: determines the minimum compatible minor version
  4. Elasticsearch client type (e.g., Transport or HTTP client)
  5. Compatibility tests: to test compatibility with newer minor version(s), which might be different than the client version
  6. Product needs: dictates what minimum (minor) version of the client the connector must use to provide the required capabilities and features

Please continue reading if you are interested in the details of these factors including how they affect Fix Pack/Service Pack and Marketplace releases.


Liferay DXP Version and Patch Level

Each Liferay DXP version is bundled with a connector to Elasticsearch that is compatible with a specific Elasticsearch Major version:

  • Liferay DXP 7.3-7.4 / DXP Quarterly Releases => Elasticsearch 7 and 8*
  • Liferay DXP 7.1-7.2 => Elasticsearch 6
  • Liferay DXP 7.0 => Elasticsearch 2

(Note: Elastic uses version codes with three numbers, e.g., 8.17.2: Major 8, Minor 17, Maintenance 2.)

A connector is made up of Java OSGi bundles with several purposes:

  • Implement Liferay’s indexing & search APIs
  • Translate generic documents and queries to the actual search engine dialect
  • Provide other (low-level) Liferay search framework capabilities to communicate with Elasticsearch
  • Send and receive data
  • Leverage other Elasticsearch features.

As these bundled connectors evolve and receive bug fixes and other changes throughout the product life of the given DXP version, the compatible Elasticsearch minor versions may shift. For example, Liferay DXP 7.4 Update 5 was compatible with Elasticsearch 7.14.x, but at the time of writing, the latest** release (Liferay DXP 7.4 U132 / DXP 2025.Q1) is compatible with 7.17.x and 8.x* due to modifications introduced in interim releases. The technical reasons will be explained in later sections.

Take-away: Before moving to a newer quarterly release/patch level, always consult with the Release Notes/Important Changes of the version you are planning to install and the Search Engine Compatibility Matrix to find related information regarding Elasticsearch compatibility.

* The Elasticsearch 8.x compatibility is provided through the bundled Elasticsearch 7 connector and the REST API Compatibility of Elasticsearch 8.

Liferay Elasticsearch Connector Version (Marketplace)

(Referred to as “Elasticsearch connector” from now on.)

To add support for newer major Elasticsearch versions for released DXP versions, Liferay released new connectors through Marketplace in the past. These connectors can be used as drop-in replacements for the out-of-the-box (bundled) connectors:

Most of the time, the last released connector on Marketplace for one DXP version becomes the out-of-the-box bundled connector in the next DXP version. For example, DXP 7.3 and 7.4 come with the Liferay Connector to Elasticsearch 7 bundled, and this connector is available for Liferay 7.1 and 7.2 on Marketplace.

Connectors can be downloaded from Marketplace as apps (distributed as LPKG files) that you can deploy onto Liferay DXP. Each marketplace app has its own version where the major version determines which Liferay DXP version they are compatible with as follows:

DXP Version Connector App Name Connector App Marketplace Version
DXP 7.0 Liferay Connector to Elasticsearch 6 1.x
DXP 7.1 Liferay Connector to Elasticsearch 7 2.x
DXP 7.2 Liferay Connector to Elasticsearch 7 3.x

 

To deliver bug fixes and other updates, Liferay released new versions of these apps. As the Elasticsearch connectors depend on Liferay DXP's Java APIs that can change in Fix Packs/Service Packs, a given version of the connector app usually requires a minimum specific Liferay DXP version. (See a few past releases below.)

Connector App Name Connector App Marketplace Version Required DXP Patch Level
Liferay Connector to Elasticsearch 6 1.0.0 DXP 7.0 FP42+
Liferay Connector to Elasticsearch 6 1.0.1 DXP 7.0 FP70+
Liferay Connector to Elasticsearch 6 1.1.0 DXP 7.0 FP79+
Liferay Connector to Elasticsearch 6 1.2.0 DXP 7.0 FP96+
Liferay Connector to Elasticsearch 7 2.0.0 DXP 7.1 SP5+/FP20+
Liferay Connector to Elasticsearch 7 3.0.0 DXP 7.2 SP1+/FP2+ through FP4
Liferay Connector to Elasticsearch 7 3.0.1 DXP 7.2 SP2+/FP5+
Liferay Connector to Elasticsearch 7 3.1.0 DXP 7.2 SP3+/FP8+
Liferay Connector to Elasticsearch 7 3.2.0 DXP 7.2 FP9+

 

Despite the efforts to keep the compatibility as wide as possible (so a given app version stays compatible with a series of patch levels on a DXP version), there are changes that require us to bump the minimum patch level.

Take-away: We do our best to document any "breaking changes" at multiple locations. Before installing a new connector from Marketplace or moving to a newer patch level, always consult with the Release Notes/Important Changes of the Fix Pack you are currently using (or planning to install), the Search Engine Compatibility Matrix, and also check the Marketplace page of the app to see if the Elasticsearch compatibility has changed.


Elasticsearch Client Version and Type

This is the most important factor.

The connectors use different Elasticsearch Java clients. These clients correspond to a given Elasticsearch release, so the connectors use client versions like 6.5.0, 6.8.16, 7.9.0 and 7.17.26. These versions determine the minimum compatible minor version of Elasticsearch, say, 7.17.

Besides the version, there is another client attribute that influences the compatibility: the client type.

Liferay's Elasticsearch connectors use two types of Java clients and each defines the compatibility with higher minor Elasticsearch versions differently:

DXP Version DXP 7.0-7.2 DXP 7.3-7.4 & DXP Quarterly Releases
Client Type Transport Client (2.x, 6.x, 7.x) REST Client (7.x)
Client Compatibility From the Elastic's documentation:
The client must have the same major version (e.g. 2.x, or 5.x) as the nodes in the cluster. Clients may connect to clusters which have a different minor version (e.g. 2.3.x) but it is possible that new functionality may not be supported. Ideally, the client should have the same version as the cluster.
From the Elastic's documentation:
The High Level Client is guaranteed to be able to communicate with any Elasticsearch node running on the same major version and greater or equal minor version. It doesn’t need to be in the same minor version as the Elasticsearch nodes it communicates with, as it is forward compatible meaning that it supports communicating with later versions of Elasticsearch than the one it was developed for.*

* The connector is using primarily the High Level REST Client, however, there are some currently unimplemented features that DXP needs so the implementation obtains the Low Level REST Client from the High Level client to build the necessary JSON for the requests. Regarding the Low Level Client, Elastic's documentation states that "it is compatible with all Elasticsearch versions".

Take-away:
As you can see, the client version used by the connector determines the major and the minimum compatible minor version of Elasticsearch in all cases. The REST client allows us to define a more flexible compatibility with newer minor releases of Elasticsearch in DXP 7.3 and beyond.


The Transport Client is more strict, requiring us to perform a series of tests to mark a newer minor version as compatible.


The exercise for you is the same: before moving to a new DXP patch level or installing a new version of the connector from Marketplace, always check the compatibility matrix to make sure you don't miss an important detail so you can run your DXP-Elasticsearch stack using compatible versions.

Note: Liferay DXP running a connector whose client is using newer minor version (e.g., 7.9.0) may still be able to connect to older minor versions of Elasticsearch (e.g., 7.4.0) without issues, however these combinations are not tested by Liferay.


Compatibility Tests

The Search team conducts ad-hoc testing of the Elasticsearch connectors with newer minor releases of Elasticsearch. These minor releases sometimes introduce breaking changes at the low-level Java API (which can affect applications using the Transport Client in older versions of Liferay). When this happens, it requires to update the client library version and the implementation inside the connector.

Take-away: in short, these test iterations help us determine the highest compatible minor versions of Elasticsearch, which are reflected in the compatibility matrix. In addition to the Search Engine Compatibility Matrix, read the Elasticsearch Connectors: Technical Data Sheet article. This article provides more detail about the client, compatible Elasticsearch (minor) versions for each Liferay DXP version, and the available Marketplace connectors.


Product Needs

To add support for new functionalities like Cross-Cluster Replication (CCR) or to fix complex issues and vulnerabilities, sometimes it requires to introduce changes to the Liferay's Java Search APIs and framework which are part of the core Liferay DXP distribution. As the connectors depend on these capabilities and APIs, newer DXP releases may require you to install a newer connector version from Marketplace, if the connector you need is not bundled on that DXP version.

In a similar way, newer Elasticsearch minor versions, new features (like support for CCR which requires 6.7+), vulnerabilities and issues (like LPS-120240) may require to bump the client version inside the connector, which again, shifts the range of the minimum compatible Elasticsearch version.

Take-away: We try to keep these types of changes to a minimum, but there are situations when it's unavoidable. Therefore consulting with the above-mentioned resources before updating your stack is a very important step.

Related Resources


* Elastic, Elasticsearch, and X-Pack are trademarks of Elasticsearch BV, registered in the U.S. and in other countries.

** At the time of writing. Please refer to the Search Engine Compatibility Matrix for up-to-date information.

¿Fue útil este artículo?
Usuarios a los que les pareció útil: 1 de 1