DocumentaçãoCommerceCommerce na nuvem

Configurar o serviço Elasticsearch

Última atualização: 2 de setembro de 2026

Criado para:

  • Admin
  • Desenvolvedor

O Elasticsearch é um produto de código aberto que permite que você colete dados de qualquer origem, qualquer formato e pesquise e visualize-os em tempo real.

WARNING
O Elasticsearch 7 e posterior não é compatível com o Adobe Commerce na infraestrutura em nuvem. O Adobe Commerce 2.4.4 e posterior é compatível com o serviço OpenSearch.

Para o Adobe Commerce versão 2.4.4 e posterior, consulte Configurar o serviço OpenSearch.

  • O Elasticsearch faz pesquisas rápidas e avançadas em produtos do catálogo de produtos
  • Os analisadores do Elasticsearch são compatíveis com vários idiomas
  • Suporta palavras de interrupção e sinônimos
  • A indexação não afeta os clientes até que a operação de reindexação seja concluída
TIP
A Adobe recomenda que você sempre configure o Elasticsearch para seu projeto de infraestrutura do Adobe Commerce na nuvem, mesmo que planeje configurar uma ferramenta de pesquisa de terceiros para seu aplicativo do Adobe Commerce. A configuração do Elasticsearch fornece uma opção de fallback caso a ferramenta de pesquisa de terceiros falhe.

Use as instruções a seguir para a configuração do serviço em ambientes Pro Integration e Starter, incluindo a ramificação master.

NOTE
Para alterar a configuração do serviço em ambientes de Produção e Preparo Profissionais, Envie um tíquete de Suporte da Adobe Commerce. Para obter os requisitos de agendamento e as orientações de disponibilidade do cliente, consulte o Suporte a serviços profissionais em Configurar serviços.

Para habilitar o Elasticsearch:

  1. Para projetos Iniciais, adicione o serviço elasticsearch ao arquivo .magento/services.yaml com a versão do Elasticsearch e o espaço em disco alocado em MB.

    code language-yaml 
    elasticsearch:
    type: elasticsearch:<version>
    disk: 1024

    Para projetos Pro, você deve enviar um tíquete de Suporte do Adobe Commerce para alterar a versão do Elasticsearch nos ambientes de preparo e produção.

  2. Definir a propriedade relationships no arquivo .magento.app.yaml.

    code language-yaml 
    relationships:
    elasticsearch: "elasticsearch:elasticsearch"

  3. Adicionar, confirmar e enviar alterações de código.

    code language-bash 
    git add .magento/services.yaml .magento.app.yaml && git commit -m "Enable Elasticsearch" && git push origin <branch-name>

    Para obter informações sobre como essas alterações afetam seus ambientes, consulte Serviços.

  4. Depois que o processo de implantação for concluído, use o SSH para fazer logon no ambiente remoto.

    code language-bash 
    magento-cloud ssh

  5. Reindexe o índice de pesquisa do catálogo.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  6. Limpe o cache.

    code language-bash 
    bin/magento cache:clean
TIP
Após a configuração inicial do serviço, você pode alterar a versão do software de um serviço instalado atualizando os arquivos de configuração services.yaml e .magento.app.yaml. Consulte Alterar versão de serviço para obter orientação sobre como atualizar ou rebaixar um serviço. Este método de autoatendimento não se aplica a ambientes de Preparo ou Produção Pro — consulte Suporte a serviços Pro em Configurar serviços.

Compatibilidade de software do Elasticsearch

Ao instalar ou atualizar seu projeto Adobe Commerce na infraestrutura em nuvem, sempre verifique a compatibilidade entre a versão do serviço Elasticsearch e o cliente Elasticsearch PHP para Adobe Commerce.

  • Primeira configuração-Confirme se a versão do Elasticsearch especificada no arquivo services.yaml é compatível com o cliente Elasticsearch PHP configurado para Adobe Commerce.

  • Atualização de projeto-Verifique se o cliente PHP do Elasticsearch na nova versão do aplicativo é compatível com a versão do serviço Elasticsearch instalada na infraestrutura em nuvem.

O suporte à versão do serviço e à compatibilidade do Adobe Commerce na infraestrutura em nuvem é determinado pelas versões implantadas na infraestrutura em nuvem e, às vezes, difere das versões compatíveis com implantações locais do Adobe Commerce. Consulte Versões de serviço.

Para verificar a compatibilidade do software Elasticsearch:

  1. Na estação de trabalho local, altere para o diretório do projeto.

  2. Mostrar os detalhes do Elasticsearch para o ambiente ativo.

    code language-bash 
    magento-cloud relationships --property=elasticsearch

  3. Como alternativa, você pode usar o SSH para fazer logon no ambiente remoto.

    code language-bash 
    magento-cloud ssh

  4. Verifique a versão do pacote do Composer para elasticsearch/elasticsearch.

    code language-bash 
    composer show elasticsearch/elasticsearch

    Na resposta, verifique a versão instalada na propriedade versions.

    code language-none 
    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

    Além disso, você pode encontrar a versão do cliente Elasticsearch PHP no arquivo composer.lock no diretório raiz do ambiente.

  5. Na linha de comando, recupere os detalhes de conexão do serviço Elasticsearch.

    code language-bash 
    vendor/bin/ece-tools env:config:show services

    Na resposta, localize o endereço IP do endpoint de serviço do Elasticsearch:

    code language-none 
    | 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                                                                 |
+------------------------------------------+----------------------------------------------------------------------+

  6. Recupere o serviço Elasticsearch instalado version:number do ponto de extremidade de serviço.

    code language-bash 
    curl -XGET <elasticsearch-service-endpoint-ip-address>:9200/
    code language-json 
    {
   "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"
}

  7. Verifique a compatibilidade da versão entre o serviço Elasticsearch e o cliente PHP.

    Se as versões forem incompatíveis, faça uma das seguintes atualizações na configuração do seu ambiente:

    • Altere o cliente Elasticsearch PHP para uma versão compatível com a versão do serviço Elasticsearch.

      code language-bash 
      composer require "elasticsearch/elasticsearch:~<version>"

    • Altere a versão do serviço Elasticsearch no arquivo services.yaml para uma versão que seja compatível com o cliente PHP Elasticsearch.

      Para obter os requisitos de agendamento de atualização de serviço do Pro e orientação de disponibilidade para o cliente, consulte Suporte a serviços do Pro em Configurar serviços.

Reiniciar o serviço Elasticsearch

Se precisar reiniciar o serviço Elasticsearch, contate o suporte da Adobe Commerce.

Configuração de pesquisa adicional

  • Por padrão, a configuração de pesquisa para ambientes em nuvem é gerada novamente sempre que você implanta. Você pode usar a variável de implantação SEARCH_CONFIGURATION para manter configurações de pesquisa personalizadas entre implantações. Consulte Implantar variáveis.

  • Depois de configurar o serviço Elasticsearch para o seu projeto, use a interface do Administrador para testar a conexão do Elasticsearch e personalizar as configurações do Elasticsearch para o Adobe Commerce.

Adicionar plug-ins do Elasticsearch

Como opção, você pode adicionar plug-ins para o Elasticsearch adicionando a seção configuration:plugins ao serviço Elasticsearch no arquivo .magento/services.yaml. Por exemplo, o código a seguir habilita os plug-ins de análise ICU e Análise fonética.

elasticsearch:
    type: elasticsearch:<service-version>
    disk: 1024
    configuration:
        plugins:
            - analysis-icu
            - analysis-phonetic

Se você usar o plug-in de terceiros do Elastic Suite, deverá atualizar o pacote ece-tools para a versão 2002.0.19 ou posterior.
Ao configurar o Elastic Suite, adicione as definições de configuração à variável de implantação ELASTICSUITE_CONFIGURATION. Essa configuração salva as configurações nas implantações.

Remover plug-ins do Elasticsearch

Remover as entradas de plug-in de elasticsearch: em .magento/services.yaml não as desinstala ou desabilita conforme o esperado. Você deve reindexar os dados do Elasticsearch. Esse comportamento é intencional para evitar possível perda ou corrupção de dados que dependem desses plug-ins.

Para remover os plug-ins do Elasticsearch:

  1. Remova as entradas de plug-in do Elasticsearch do seu arquivo .magento/services.yaml.

  2. Adicionar, confirmar e enviar por push as alterações de código.

    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>

  3. Confirme as .magento/services.yaml alterações no repositório de nuvem.

  4. Reindexe o índice de pesquisa do catálogo.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  5. Limpe o cache.

    code language-bash 
    bin/magento cache:clean
TIP
Para obter detalhes sobre como usar ou solucionar problemas do plug-in do Elastic Suite com o Adobe Commerce, consulte a documentação do Elastic Suite.
recommendation-more-help
commerce-on-cloud-help-cloud-guide