Indexing is the process by which data is compiled and inserted into Elasticsearch. Elasticsearch (ES) is designed for quick retrieval and filtering of items in the index. To accomplish this, ES does not store the full database of a site, and the index will differ from the site’s MySQL table indexes.
VIP-CLI command examples
For demonstration purposes, the
mytestsite and the
develop are used in the VIP-CLI command examples below. Read more about how to target environments in VIP-CLI commands.
How indexing works
The continual indexing of Elasticsearch is dependent on built-in WordPress event action hooks. Normally, the standard WordPress editing process uses event action hooks, and every change made by an editor to a post or page will be quickly reflected in the Elasticsearch index.
Custom code or plugins that use direct database queries or non-standard ways of modifying the database will not sync to the Elasticsearch index.
Content is indexed incrementally, as it is created and updated. Indexing can manually be triggered by opening the particular post or page in the WordPress editor and selecting the button labeled “Update”.
If more than one type of ES index exists (e.g. one for terms and another one for posts), each one requires separate steps for indexing, re-indexing, and versioning.
index command initiates indexing activity on a new or existing index (starting from the newest content). Running the
index command is necessary to create a new index or if an allow list entry (e.g. post types, taxonomies, or post meta) has been recently modified.
An example of the
index command and its output:
$ vip @mytestsite.develop -- wp vip-search index Indexing posts... Processed 500/37674. Last Object ID: 37550 ... Processed 37500/37674. Last Object ID: 179 Processed 37674/37674. Last Object ID: 1 Number of posts indexed: 37674 Total time elapsed: 605.960 Success: Done!
The amount of time to complete indexing depends on the size of the database. To increase the amount of posts indexed per cycle, use the
For additional reference on the options available, use the
wp help vip-search index command:
vip @mytestsite.develop -- wp help vip-search index
Values not accepted.
Completely drops and recreates the index with mappings.
--setup option is required to create an index the first time. This ensures that mappings are correctly in place.
Recreating an existing index with the
--setup option or 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_IMPORTINGto true, or direct SQL queries that modify data).
- Search tokenization filter settings have been added or modified.
vip @mytestsite.develop -- wp vip-search index --setup
Versioning should be used whenever possible to update a site’s index. Re-creating an existing index with the
--setup option is a destructive action and can cause the index to be temporarily unavailable until the process is complete.
Values not accepted.
--using-versions option can be used when re-indexing. Passing the
--using-versions option with the
wp vip-search index command will automatically:
- Create a new, updated version of the index
- Enable the new version of the index
- Allow the user to delete the previous, inactive index.
vip @mytestsite.develop -- wp vip-search index --using-versions
Values not accepted.
Sequentially indexes all sites on a WordPress multisite network.
Refer to Search and multisites for more information.
vip @mytestsite.develop -- wp vip-search index --network-wide
If a multisite has over 100 sites on its network, it is strongly recommend to create an index on a per-site basis. Rather than creating indexes for all sites, only create indexes for specific network sites that will actively use them. Creating unused indexes may negatively impact the indexing and revalidation operations triggered by periodic health checks.
Accepted values: blog id or comma-separated list of blog ids
Will target select blog IDs.
For example, to index only blog IDs 3 and 5:
vip @mytestsite.develop -- wp vip-search index --blog-ids=3,5
Accepted values: index version number,
The index version which the command is targeting. Used during versioning to build up a new index in parallel with the current active index. Typically used in conjunction with the
For example, to index version
2 of a posts index:
vip @mytestsite.develop -- wp vip-search index --version=2 --indexables=post
Accepted values: single value Indexable or comma-separated list of Indexables
Default values: all registered Indexables (
Targets specific Indexable(s).
For example, to index the
vip @mytestsite.develop -- wp vip-search index --indexables=term
Accepted values: single value object ID
Limits a subset of object IDs (e.g. post IDs, term IDs, user IDs). IDs are indexed from highest to lowest.
A common use case would be to resume indexing after an interruption or timeout. For example, a previous index command was interrupted at post ID
100, so we would trigger a new index operation using
--upper-limit-object-id to begin at
vip @mytestsite.develop -- wp vip-search index --upper-limit-object-id=100
When these options are used together, they limit the indexing to a range of documents. For example, to index only post IDs from
vip @mytestsite.develop -- wp vip-search index --upper-limit-object-id=50 --lower-limit-object-id=10
Accepted values: numerical value of posts per page
500, maximum of
Determines the amount of posts to be indexed per cycle.
For example, to increase the indexed posts per cycle to
vip @mytestsite.develop -- wp vip-search index --per-page=1000
Accepted values: single value object ID or comma-separated list of object IDs
Targets indexing only the listed ID(s).
For example, to index only
vip @mytestsite.develop -- wp vip-search index --include=7,20
Accepted values: single post type or comma-separated list of post types
Default values: all public post types
Targets indexing only the specified post type(s).
For example, to index only a custom post type
vip @mytestsite.develop -- wp vip-search index --post-type=event,recipe
Values not accepted.
Displays a verbose error output during indexing. If a post fails to index, it will return with the full error message (compared to just the post ID and title).
vip @mytestsite.develop -- wp vip-search index --show-errors
Values not accepted.
Omits the Enterprise Search confirmation prompt for destructive operations:
You are about to run a destructive operation. Are you sure?.
For example, indexing with
--setup is a destructive action and will generate the following prompt:
$ vip @mytestsite.develop -- vip-search index --setup ⚠️ You are about to run a destructive operation. Are you sure? [y/n] y Indexing with setup option needs to delete Elasticsearch index first, are you sure you want to delete your Elasticsearch index? [y/n] y
--skip-confirm will omit the destructive operation confirmation prompt:
$ vip @mytestsite.develop -- wp vip-search index --setup --skip-confirm Indexing with setup option needs to delete Elasticsearch index first, are you sure you want to delete your Elasticsearch index? [y/n] y
Monitor or interrupt the indexing process
vip-search are available to retrieve information about the indexing process, stop the process, or unblock the process if necessary.
Retrieve information about the progress of a currently running
index command with
vip @mytestsite.develop -- wp vip-search get-indexing-status
Output will be returned in JSON format:
truefor in process;
"method": how the indexing was actioned
"items_indexed": number of items already indexed
"total_items": total number of items not yet indexed
If the indexing has unexpectedly failed, it is possible that
true will be the returned value for
"indexing" but the total items will return
get-last-indexed-post-id to identify the post ID that was last indexed:
vip @mytestsite.develop -- wp vip-search get-last-indexed-post-id
stop-indexing to stop an active indexing command:
vip @mytestsite.develop -- wp vip-search stop-indexing
delete-transient command may be necessary if an indexing command process is not currently running—or has unexpectedly stopped—and this error is returned when re-indexing is attempted:
Error: An index is already occurring. Try again later.
delete-transient command removes the index lock will allow re-indexing.
vip @mytestsite.develop -- wp vip-search delete-transient
Last updated: August 03, 2023