Set up Elasticsearch service
Elasticsearch is an open-source product that enables you to take data from any source, any format, and search and visualize it in real time.
For Adobe Commerce version 2.4.4 and later, see Set up OpenSearch service.
- Elasticsearch performs quick and advanced searches on products in the product catalog
- Elasticsearch Analyzers support multiple languages
- Supports stop words and synonyms
- Indexing does not impact customers until the reindex operation completes
Use the following instructions for service setup on Pro Integration environments and Starter environments, including the master
branch.
To enable Elasticsearch:
-
For Starter projects, add the
elasticsearch
service to the.magento/services.yaml
file with the Elasticsearch version and allocated disk space in MB.code language-yaml elasticsearch: type: elasticsearch:<version> disk: 1024
For Pro projects, you must submit an Adobe Commerce Support ticket to change the Elasticsearch version in the Staging and Production environments.
-
Set the
relationships
property in the.magento.app.yaml
file.code language-yaml relationships: elasticsearch: "elasticsearch:elasticsearch"
-
Add, commit, and push code changes.
code language-bash git add .magento/services.yaml .magento.app.yaml && git commit -m "Enable Elasticsearch" && git push origin <branch-name>
For information on how these changes affect your environments, see Services.
-
After the deployment process completes, use SSH to log in to the remote environment.
code language-bash magento-cloud ssh
-
Reindex the Catalog Search index.
code language-bash bin/magento indexer:reindex catalogsearch_fulltext
-
Clean the cache.
code language-bash bin/magento cache:clean
services.yaml
and .magento.app.yaml
configuration files. See Change service version for guidance on upgrading or downgrading a service.Elasticsearch software compatibility
When you install or upgrade your Adobe Commerce on cloud infrastructure project, always check for compatibility between the Elasticsearch service version and the Elasticsearch PHP client for Adobe Commerce.
-
First time setup–Confirm that the Elasticsearch version specified in the
services.yaml
file is compatible with the Elasticsearch PHP client configured for Adobe Commerce. -
Project upgrade–Verify that the Elasticsearch PHP client in the new application version is compatible with the Elasticsearch service version installed on the cloud infrastructure.
Service version and compatibility support for Adobe Commerce on cloud infrastructure is determined by versions deployed on the cloud infrastructure, and sometimes differ from versions supported by Adobe Commerce on-premises deployments. See Service versions.
To check Elasticsearch software compatibility:
-
On your local workstation, change to your project directory.
-
Show the Elasticsearch details for the active environment.
code language-bash magento-cloud relationships --property=elasticsearch
-
Alternatively, you can use SSH to log in to the remote environment.
code language-bash magento-cloud ssh
-
Check the Composer package version for
elasticsearch/elasticsearch
.code language-bash composer show elasticsearch/elasticsearch
In the response, check the installed version in the
versions
property.code language-terminal name : elasticsearch/elasticsearch descrip. : PHP Client for Elasticsearch keywords : client, elasticsearch, search versions : * v7.17.1 type : library license : Apache License 2.0 (Apache-2.0) (OSI approved) https://spdx.org/licenses/Apache-2.0.html#licenseText license : GNU Lesser General Public License v2.1 only (LGPL-2.1-only) (OSI approved) https://spdx.org/licenses/LGPL-2.1-only.html#licenseText homepage : source : [git] git@github.com:elastic/elasticsearch-php.git f1b8918f411b837ce5f6325e829a73518fd50367 dist : [zip] https://api.github.com/repos/elastic/elasticsearch-php/zipball/f1b8918f411b837ce5f6325e829a73518fd50367 f1b8918f411b837ce5f6325e829a73518fd50367 path : ~/vendor/elasticsearch/elasticsearch names : elasticsearch/elasticsearch
Also, you can find the Elasticsearch PHP client version in the
composer.lock
file in the environment root directory. -
From the command line, retrieve the Elasticsearch service connection details.
code language-bash vendor/bin/ece-tools env:config:show services
In the response, find the IP address for the Elasticsearch service endpoint:
code language-terminal | elasticsearch: | +------------------------------------------+----------------------------------------------------------------------+ | username | null | | scheme | http | | service | elasticsearch | | fragment | null | | ip | 169.254.220.11 | | hostname | dzggu33f75wi3sd24lgwtoupxm.elasticsearch.service._.magentosite.cloud | | public | false | | cluster | fo3qdoxtla4j4-master-7rqtwti | | host | elasticsearch.internal | | rel | elasticsearch | | query | | | path | null | | password | null | | type | elasticsearch:6.5 | | port | 9200 | +------------------------------------------+----------------------------------------------------------------------+
-
Retrieve the installed Elasticsearch service
version:number
from the service endpoint.code language-bash curl -XGET <elasticsearch-service-endpoint-ip-address>:9200/
code language-terminal { "name" : "-AqGi9D", "cluster_name" : "elasticsearch", "cluster_uuid" : "_yze6-ywSEW1MaAF8ZPWyQ", "version" : { "number" : "6.5.4", "build_flavor" : "default", "build_type" : "deb", "build_hash" : "82a8aa7", "build_date" : "2019-01-23T12:07:18.760675Z", "build_snapshot" : false, "lucene_version" : "7.5.0", "minimum_wire_compatibility_version" : "5.6.0", "minimum_index_compatibility_version" : "5.0.0" }, " tagline" : "You Know, for Search" }
-
Check version compatibility between the Elasticsearch service and the PHP client.
If the versions are incompatible, make one of the following updates to your environment configuration:
-
Change the Elasticsearch PHP client to a version that is compatible with the Elasticsearch service version.
code language-bash composer require "elasticsearch/elasticsearch:~<version>"
-
Change the Elasticsearch service version in the
services.yaml
file to a version that is compatible with the Elasticsearch PHP client.
-
Staging
and Production
environments only..magento.app.yaml
and services.yaml
files, and state the PHP version in the ticket. For self-service changes to PHP version, extensions, or environment settings, see PHP settings in Application configuration.Restart the Elasticsearch service
If you need to restart the Elasticsearch service, you must contact Adobe Commerce support.
Additional search configuration
-
By default, the search configuration for Cloud environments regenerates each time you deploy. You can use the
SEARCH_CONFIGURATION
deploy variable to retain custom search settings between deployments. See Deploy variables. -
After you set up the Elasticsearch service for your project, use the Admin UI to test the Elasticsearch connection and customize Elasticsearch settings for Adobe Commerce.
Add plugins for Elasticsearch
Optionally, you can add plugins for Elasticsearch by adding the configuration:plugins
section to the Elasticsearch service in the .magento/services.yaml
file. For example, the following code enables the ICU analysis and Phonetic analysis plugins.
elasticsearch:
type: elasticsearch:<service-version>
disk: 1024
configuration:
plugins:
- analysis-icu
- analysis-phonetic
If you use the Elastic Suite third-party plugin, you must update the ece-tools
package to version 2002.0.19 or later.
When setting up Elastic Suite, add the configuration settings to the ELASTICSUITE_CONFIGURATION
deploy variable. This configuration saves the settings across deployments.
Remove plugins for Elasticsearch
Removing the plugin entries from elasticsearch:
in .magento/services.yaml
does not uninstall or disable them as you might expect. You must reindex your Elasticsearch data. This behavior is intentional to prevent possible loss or corruption of data that depends on these plugins.
To remove Elasticsearch plugins:
-
Remove the Elasticsearch plugin entries from your
.magento/services.yaml
file. -
Add, commit, and push your code changes.
code language-bash git add .magento/services.yaml
code language-bash git commit -m "Remove Elasticsearch plugin"
code language-bash git push origin <branch-name>
-
Commit the
.magento/services.yaml
changes to your Cloud repo. -
Reindex the Catalog Search index.
code language-bash bin/magento indexer:reindex catalogsearch_fulltext
-
Clean the cache.
code language-bash bin/magento cache:clean
Troubleshooting
See the following Adobe Commerce Support articles for help with troubleshooting Elasticsearch problems: