Version with Enterprise Search

Versioning makes it possible to perform a reindex of an Elasticsearch index without needing to drop the current index. Before activating the new version of an index, steps should be taken to ensure that it is healthy.

Versioning is necessary to bring a database and its Elasticsearch index back into sync if:

• The database is modified outside of normal WordPress functionality (i.e. database imports, bulk CLI commands that disable the hooks by setting WP_IMPORTING to true, or direct SQL queries that modify data).
• Search tokenization filter settings have been added or modified.

1. Register a new index

wp vip-search index-versions add post will create a new index for post content (this will also work with other Indexables such as term). The response will include the version number added.

In this example, the newly created index is version 2:

$ vip @example-app.develop -- wp vip-search index-versions add post
Success: Registered and created new index version 2

A new index version has been added and created (with mapping) on Elasticsearch. The current active version will continue to receive incremental changes.

This step does not do any bulk indexing of content, but it will start the indexing of incremental changes to the new version.

2. Build the new index

Build the new index alongside the current one. The larger a database is, the longer the amount of time it will take for this process to complete.

In the command, specify a version:

$ vip @example-app.develop -- wp vip-search index --indexables="post" --version="next"
Indexing posts...
Processed 500/37674. Last Object ID: 37550
Processed 1000/37674. Last Object ID: 37050
Processed 1500/37674. Last Object ID: 36550
...
Processed 37674/37674. Last Object ID: 1
Number of posts indexed: 37674
Total time elapsed: 492.615
Success: Done!

3. Health check

Check the status of both the current index and the next index:

$ vip @example-app.develop -- wp vip-search health validate-counts
Validating post count

✅ no inconsistencies found when counting entity: post, type: post, index_version: 1 - (DB: 37498, ES: 37498, Diff: 0)
✅ no inconsistencies found when counting entity: post, type: page, index_version: 1 - (DB: 176, ES: 176, Diff: 0)
✅ no inconsistencies found when counting entity: post, type: post, index_version: 2 - (DB: 37498, ES: 37498, Diff: 0)
✅ no inconsistencies found when counting entity: post, type: page, index_version: 2 - (DB: 176, ES: 176, Diff: 0)

Verify search results before activating a new index version

The query parameter vip-search-<indexable>-version can be used to verify search results before activating a new index version by appending the parameter and a relevant version value to a site’s search query URL.

https://example.com/?s=<search-term>&vip-search-<indexable>-version=<version>

For example, the following URL could be used in the browser to verify search results for the search term apple against the next index version on posts:

https://example.com/?s=apple&vip-search-post-version=next

4. Activate the new index

If the new index version passes the health check and is in sync (Diff: 0) it is ready to be activated.

The active index is the one that serves site traffic (queries), so be sure the target index is ready for production before switching.

$ vip @example-app.develop -- wp vip-search index-versions activate post next
Are you sure you want to activate index version next for type post? [y/n] y
Success: Successfully activated index version next for type post

5. Delete the old index

Once it is verified that the new index is handling requests correctly, the old index should be deleted. Only two index versions can exist at a given time.

If the old version is not deleted, it will continue to be updated and indexed as content is created and modified. This may impact indexing performance.

Use the index-versions list <indexable-slug> command to determine if multiple indexes exist:

$ vip @example-app.develop -- wp vip-search index-versions list post
+--------+--------+--------------+----------------+----------------+
| number | active | created_time | activated_time | document_count |
+--------+--------+--------------+----------------+----------------+
| 1      | 1      | 1642182701   | 1642185939     | 2              |
| 2      |        | 1642449776   |                | 0              |
+--------+--------+--------------+----------------+----------------+

In the example above, index 1 is marked as active. The active index cannot be deleted.

Delete the older, inactive index with index-versions delete <indexable-slug> previous:

$ vip @example-app.develop -- wp vip-search index-versions delete post previous
⚠️ You are about to run a destructive operation. Are you sure? [y/n] y
Success: Successfully deleted index version 1 for type post

Testing index versions

The query parameter vip-search-<indexable>-version can be appended to a site’s URL to test different index versions. This would be useful to test a new index version before activating it. For example, if a site currently has an active post index version of 1, but they have an inactive post index version of 2. They would use the query string of &vip-search-post-version=2 to test index version 2 on the search query for the term “test”:

http://example.com/?s=test&vip-search-post-version=2