Search Migration from Solr to Elasticsearch/OpenSearch

1. Why the search migration from Solr is unavoidable

Many Magento shops originally built on Magento 1 or an early Magento 2 version still run Apache Solr as their search technology today. Solr was the default solution for a long time, but was officially replaced by Elasticsearch, now complemented by OpenSearch, with Magento 2.4. For these shops, the search migration away from Solr is no longer optional, it is only a matter of time, because older Magento versions increasingly fall out of the support cycle and stop receiving security updates.

The search migration from Solr to Elasticsearch is technically more demanding than many teams initially assume. It is not just about swapping a configuration line, but a fundamentally different schema model, different query syntax, and a different relevance scoring system. Anyone who underestimates these differences risks a search after migration that technically works but delivers noticeably worse results than the old Solr setup.

This article is aimed at teams facing exactly this search migration. It covers technical preparation, schema mapping, reindex strategy, test procedures, and a concrete rollback plan, so the switch can happen in a controlled way with minimal risk to ongoing operations.

2. Solr end-of-life in Magento: the technical background

Magento supported Solr through a separate module tightly coupled to the Magento architecture of the time. With the introduction of Elasticsearch as the default search engine in Magento 2.1 and the gradual deepening of integration through Magento 2.4, Solr was first supported in parallel, then marked deprecated, and finally removed entirely from the core. Since then there is no official Solr support left, and community extensions that add Solr back run outside the official support envelope.

The technical reason for this switch lies in the architecture: Elasticsearch offers a more modern, RESTful JSON-based API, better horizontal scalability through sharding, and more active development compared to Solr, whose development pace slowed in recent years. For Magento as a platform, that meant betting long-term on the technology with the more active community and the stronger cloud ecosystem. For merchants, it means the search migration away from Solr is not a short-lived trend but a permanent platform decision by Magento itself.

3. Migration checklist: preparation and inventory

Every search migration starts with a complete inventory of the current Solr setup. That includes the list of all attributes indexed in Solr along with their Solr field types, all custom boosting rules, all configured synonym and stopword lists, and every custom extension that interacts directly with the Solr query interface. Without this inventory, the migration quickly becomes incomplete, because legacy customizations get lost unnoticed.

A second important checklist step is documenting current search behavior as a reference point. That includes a list of typical search queries along with their expected top results, to have an objective basis for comparison after the migration. Without such a baseline, the question "is the new search as good as the old one" remains pure subjectivity, which can lead to endless discussions especially during sign-off by non-technical stakeholders.

# Inventory: export current Solr schema fields for reference
curl -s "http://solr-host:8983/solr/magento/schema/fields?wt=json" | jq '.fields[] | {name, type}'

# Inventory: list all custom search-related extensions in the codebase
grep -rl "Solr" app/code/ --include="*.php" | sort

# Document baseline search behavior for later comparison
echo "running shoe,fridge freezer,notebook" | tr ',' '\n' > baseline_queries.txt

4. Schema mapping: transferring Solr fields to Elasticsearch

Solr works with an explicit field schema defined in schema.xml, where every field type (text_general, string, tint, and similar) is explicitly declared. Elasticsearch, by contrast, uses dynamic mapping by default, which automatically infers field types from the first incoming documents, but also supports explicit mappings for precise control. For a clean search migration, every Solr field should be deliberately mapped to an Elasticsearch field type instead of relying on automatic mapping, because misinterpretations under dynamic mapping are hard to correct after the fact.

Text fields with language analysis deserve special attention. Solr's text_general field type with a German stemmer corresponds in Elasticsearch to a text field with an analyzer using a german_stemmer filter. Facetable attributes, often declared as string in Solr, should be mapped as a keyword field in Elasticsearch to enable exact filtering without analysis. This distinction between text and keyword does not exist in this form in Solr and is one of the most common sources of unexpected behavior after the search migration.

{
  "mappings": {
    "properties": {
      "name": { "type": "text", "analyzer": "english_analyzer" },
      "sku": { "type": "keyword" },
      "description": { "type": "text", "analyzer": "english_analyzer" },
      "color": { "type": "keyword" },
      "price": { "type": "scaled_float", "scaling_factor": 100 },
      "visibility": { "type": "integer" },
      "categories": { "type": "keyword" }
    }
  }
}
// Corresponds to Solr schema fields:
// name (text_general) -> text with custom analyzer
// sku (string)         -> keyword (exact match, no analysis)
// color (string, facet)-> keyword
// price (tfloat)       -> scaled_float for exact price comparisons

5. Configuration switch in Magento

After finishing inventory and schema mapping comes the actual switch of the Magento configuration. The search engine key in app/etc/env.php is changed from solr to elasticsearch7, and the associated server parameters (host, port, index prefix) are set through the admin configuration or directly via CLI. Since core Magento support for Solr was removed, this switch cannot be tested incrementally within the same Magento version; it usually requires a Magento upgrade to a version without Solr support to happen in parallel.

For shops still running an older Magento version with Solr support, it is advisable to carry out the search migration in two separate steps: first switching the search engine on a version that supports both engines, to validate the new setup under real load, and only afterward performing the actual Magento upgrade. This approach reduces the risk of having to debug two large changes (search migration and platform upgrade) at the same time.

# Switch the search engine from Solr to Elasticsearch
bin/magento config:set catalog/search/engine elasticsearch7
bin/magento config:set catalog/search/elasticsearch7_server_hostname elasticsearch
bin/magento config:set catalog/search/elasticsearch7_server_port 9200
bin/magento config:set catalog/search/elasticsearch7_index_prefix magento2

# Clear cache and trigger the first full reindex on the new engine
bin/magento cache:flush
bin/magento indexer:reindex catalogsearch_fulltext

6. Reindex strategy and downtime planning

The first full reindex after the search migration builds the entire Elasticsearch index from scratch, which can take significant time on large catalogs. It is advisable to run this initial reindex in a staging environment and measure the actual runtime, to plan a realistic maintenance window for the production switch. In parallel, the old Solr index should not be deleted until the new setup has been finally confirmed, so a quick switch back is possible in case of doubt.

For shops that cannot accept downtime, a blue-green approach makes sense: a second, identical Magento system is switched to Elasticsearch and fully tested, while the production system continues running on Solr. Only after successful validation is traffic routed to the new system via a load balancer switch. This approach increases infrastructure effort during the search migration, but substantially minimizes the risk of visible downtime for end customers.

7. Testing and result parity checking

The baseline of typical search queries documented in section 3 forms the foundation for parity checking after migration. For every reference query, it is compared whether the top results in Elasticsearch largely match those in Solr in order and relevance. Complete identity is not a realistic goal here, because Solr and Elasticsearch use different relevance scoring algorithms (Solr traditionally TF-IDF-based, Elasticsearch BM25 by default), but gross deviations in hit ordering point to a flawed schema mapping or missing boost configuration.

Besides pure result comparison, automated testing belongs to a solid search migration: a test script that runs the baseline queries against both systems in parallel and automatically flags deviations in hit count and top-5 results. Such tests should become part of the staging pipeline and run again before the final production switch, to make sure interim configuration changes have not introduced a regression.

#!/usr/bin/env bash
# parity-test.sh - compare Solr and Elasticsearch results for baseline queries
set -euo pipefail

while read -r query; do
  solr_count=$(curl -s "http://solr-host:8983/solr/magento/select?q=${query}&wt=json" \
    | jq '.response.numFound')
  es_count=$(curl -s -X POST "localhost:9200/magento2_default_catalogsearch_fulltext_1/_search" \
    -H "Content-Type: application/json" \
    -d "{\"query\":{\"match\":{\"name\":\"${query}\"}}}" \
    | jq '.hits.total.value')

  echo "Query: ${query} | Solr: ${solr_count} | Elasticsearch: ${es_count}"
  if [[ "$solr_count" != "$es_count" ]]; then
    echo "  WARNING: result count mismatch, investigate mapping or boosting"
  fi
done < baseline_queries.txt

8. Common pitfalls during migration

The most common pitfall is forgetting custom-configured Solr synonyms and stopword lists. In Solr, these typically live as separate text files (synonyms.txt, stopwords.txt) in the configuration directory and are not automatically carried over by a plain configuration switch. Without explicit transfer into the Elasticsearch analyzer configuration, these customizations disappear silently, resulting in a search migration that works technically but loses years of accumulated relevance tuning.

A second common pitfall is lost custom boosting. Solr setups often contain hand-maintained boost rules for specific categories, brands, or attributes, anchored in custom PHP code or Solr configuration files. These rules have no automatic equivalent in Elasticsearch and must be manually rebuilt as function_score components in the query logic. A third pitfall concerns custom extensions written directly against the Solr client library: these must be fully reimplemented, since the underlying PHP clients for Solr and Elasticsearch offer completely different APIs.

9. Rollback plan for the worst case

Even with careful preparation, every search migration should have a documented rollback plan. The simplest safeguard is to keep the Solr index and its associated infrastructure active and current for at least two weeks after the production switch, instead of decommissioning it immediately. That allows switching back to Solr within minutes in case of serious problems only visible in production, simply by resetting the search engine configuration.

What matters for a working rollback is that the Solr index continues to be kept in sync with product changes during the transition period, not only the Elasticsearch index. Otherwise a rollback delivers a working search, but with stale product data. The rollback plan should also contain clearly defined decision criteria: what error rate, what user complaints, or what performance deviation actually triggers the rollback, instead of having to make that decision spontaneously in an emergency.

# Rollback procedure: revert search engine configuration to Solr
bin/magento config:set catalog/search/engine solr
bin/magento config:set catalog/search/solr_server_hostname solr-host
bin/magento config:set catalog/search/solr_server_port 8983

# Clear cache so the reverted configuration takes effect immediately
bin/magento cache:flush

# Verify the active engine after rollback
bin/magento config:show catalog/search/engine

10. Summary

The search migration from Solr to Elasticsearch or OpenSearch is unavoidable for every Magento shop still running legacy Solr setups, but technically more complex than a plain configuration change. It requires a complete inventory of the existing Solr schema, deliberate field mapping to Elasticsearch types, especially the distinction between text and keyword, and manual reconstruction of synonyms, stopwords, and custom boosting that often grew in Solr over years.

A structured checklist, a documented baseline for result parity tests, and a clearly defined rollback plan substantially reduce the risk of the switch. Anyone who consistently follows these steps instead of treating the search migration as a pure infrastructure swap ends up with a search that is not only technically current, but also matches or exceeds the relevance quality of the old Solr setup.

11. FAQ: Search Migration from Solr to Elasticsearch