Upgrading from Enterprise Search 7.11 and earlier

Enterprise Search 7.12 brings changes to the underlying indexing and querying mechanisms, for significant improvements in ingestion times, storage requirements, and search relevance. None of these improvements affect the publicly available APIs and interfaces: all enhancements are found under the hood.

Enterprise Search packages and focuses the power of Elasticsearch for the most common and demanding search use cases. It is designed to give you the tools to easily deploy quality search experiences without the initial configuration and trial-and-error stages of deployment. For that to occur, Enterprise Search relies on advanced application logic, optimized analysis and query pipelines, as well as simplified public APIs specific to the requirements of typical search use cases.

With the 7.12 release comes significant improvements to the application logic layer, and underlying data models. These changes are applied transparently: APIs and UIs operate in the exact same way, but the revamped internals provide meaningful enhancements:

For example, using a real-world deployment, benchmarking data shows significant gains in a number of key areas. Using the Enron Email Dataset, we can draw the following comparison between older versions and Enterprise Search 7.12 (and beyond):

Given the significant underlying changes, upgrading from Enterprise Search 7.11 or earlier requires a migration at upgrade time. There are a few key items to consider when preparing for the upgrade:

To upgrade your Enterprise Search deployment to 8.12 on Elastic Cloud:

This will kick off the automated migration process to 8.12.

Once 8.12 is up, validate that your Enterprise Search data is available: do any performance, functional, or other tests that you might need.

You can then purge the old indices to free up storage space. Once the obsolete indices are removed, you can return your Elasticsearch instance sizes to their original configuration if you had increased them for the migration.

If the upgrade fails, it can be safely retried using the steps above. Check FAQ and troubleshooting for solving common upgrade problems.

Once you’ve ensured that you have the additional storage space required in your deployment, you can follow any of the options in Upgrading self-managed deployments.

The migration process will start automatically when 8.12 loads.

After upgrading, validate that your Enterprise Search data is available. You can then purge the old indices to free up storage space.

If the upgrade fails, it can be safely retried by restarting any of your 8.12 instances. The upgrade process is coordinated between instances to ensure that only one instance will trigger the migration process. Check FAQ and troubleshooting for solving common upgrade problems.

In order to benefit from the significant storage improvements after upgrading, you must remove the now obsoletely structured search indices. Worry not: this process is straightforward.

Step 1 - Once you have successfully upgraded your deployment, verify that you are able to log into the Enterprise Search experience and access either the Workplace Search or App Search dashboards. Also verify that indexing and search are working as they did before the upgrade.

Step 2 - Find your Elasticsearch endpoint and credentials. In the following steps, ELASTICSEARCH_URL is a combination of your Elasticsearch host and credentials (e.g., ELASTICSEARCH_URL=http://elastic:changeme@localhost:9200).

Step 3 - List the obsolete indices.

curl "$ELASTICSEARCH_URL/_cat/indices/.ent-search-engine-*,.ent-search-document-backend-*,-.ent-search-engine-documents-*?v&s=index"

Prior to 7.12+, engine documents were stored in three indices per engine:

Step 4 - List the new indices and compare document counts to verify the migration completed successfully

curl "$ELASTICSEARCH_URL/_cat/indices/.ent-search-engine-documents-*?v&s=index"

In 7.12+, the three engine document indices were combined into one:

Step 5 - Delete each obsolete index. Be sure to take a snapshot before completing this step as it cannot be undone. Also be careful not to delete the new 7.12+ indices, which match the format: .ent-search-engine-documents-*

curl "$ELASTICSEARCH_URL/.ent-search-engine-$ENGINE_ID" -X DELETE
curl "$ELASTICSEARCH_URL/.ent-search-document-backend-$ENGINE_ID" -X DELETE
curl "$ELASTICSEARCH_URL/.ent-search-document-backend-$ENGINE_ID-document_type_id-external_id-unique-constraint" -X DELETE

If you have more than a hundred engines or additional indices on your Elasticsearch cluster, during the upgrade your shard count may approach the maximum per-node set in Elasticsearch.

Step 1 - Determine how many additional shards the upgrade process will require: take the number of App Search engines plus Workplace Search content sources, multiply that by 4 (two shards x one replica), and divide the result by the number of Elasticsearch data nodes.

Step 2 - Check your Elasticsearch _cat allocation API to determine the current number of shards per data node:

curl -XGET "$ELASTICSEARCH_URL/_cat/allocation?v"

Step 3 - Check the Elasticsearch cluster.max_shards_per_node setting. (If you haven’t customized this setting, it defaults to 1000 shards per data node):

# If you have previously customized the setting using dynamic cluster settings
curl -XGET "$ELASTICSEARCH_URL/_cluster/settings"

# If you have previously customized the setting from the elasticsearch.yml file
curl -XGET "$ELASTICSEARCH_URL/_nodes/settings"

Step 4 - If adding the number of additional shards (Step 1) to the current number of shards (Step 2) exceeds the max_shards_per_node limit (Step 3), you will have to temporarily relax the cluster.max_shards_per_node limit in Elasticsearch before upgrading. As an example, this command increases the limit from the default 1000 to 1500:

curl -XPUT "$ELASTICSEARCH_URL/_cluster/settings" -H 'Content-Type: application/json' -d'{  "persistent": {    "cluster.max_shards_per_node": 1500  }}'

After the migration has completed successfully, and you’ve purged the old indices, you can revert the setting:

curl -XPUT "$ELASTICSEARCH_URL/_cluster/settings" -H 'Content-Type: application/json' -d'{  "persistent": {    "cluster.max_shards_per_node": null  }}'

The upgrade keeps failing. Anything I should check for?

The most common hurdle to upgrading from Enterprise Search 7.11 to a newer version is available storage capacity for the deployment. Given the significant changes made to the search index architecture powering Enterprise Search, all data structures must be duplicated temporarily at upgrade time, and therefore available deployment storage must be at least twice as much as the deployment size itself. Once the deployment upgrade has successfully completed, you may remove the obsolete search indices following the purging instructions above.

Another common challenge is deployment scale. The bigger the deployment, the longer the migration time. In very rare cases (where a deployment is unusually large), timeouts may occur. Restarting the upgrade will pick up the migration where the timeout occurred and should complete successfully.

I’ve upgraded successfully but my deployment is much larger than it used to be, when I was expecting it to be much smaller. What’s wrong?

This is expected. Given the significant changes made to the search index architecture powering Enterprise Search, all data structures must be duplicated temporarily at upgrade time. Once the deployment upgrade has successfully completed, you may remove the obsolete search indices following the purging instructions above.

The search experience seems to be returning fewer results for all queries. Is this normal?

In light of the valuable feedback of hundreds of organizations and users, newer versions of Enterprise Search bring an updated relevance model that promotes precision in favor of recall. Don’t worry, all your documents are still there, but your search experience just got a whole lot more tidy and precise.