Index with Enterprise Search
Elasticsearch (ES) indexes differ from MySQL table indexes. ES doesn’t store the full database, as it’s designed for quick retrieval and sorting/filtering of the items in the index.
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.
Indexing
Content is indexed incrementally, as it is created and updated.
The index
command initiates indexing activity on a new or existing index (starting from the newest content). This is needed if you’ve recently modified an allow list entry (e.g. post types, taxonomies, or post meta).
Note
When using VIP-CLI, specify the app and its environment that are the destination for the command(s) by providing the app alias, a dot separator, and the environment name, in the form of:@<app-alias or app ID>.<env>
.
The @mysite.production
values in the command examples below are for demonstration only.
$ vip @mysite.production -- 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 it takes for an index depends on the size of the database. To increase the amount of posts indexed per cycle, use the --per-page
option.
Command options
For additional reference on the options available, use the wp help vip-search index
command:
$ vip @mysite.production -- wp help vip-search index
--setup
Values not accepted.
Will completely drop and recreate the index.
Warning
If the site is in production, use index versioning instead.
When the database is modified outside of normal WordPress functionality (i.e. using bulk CLI commands to modify data using raw SQL resulting in the proper hooks not firing), recreating the index with the --setup
option will be necessary to bring the database and Elasticsearch index back into sync.
$ vip @mysite.production -- wp vip-search index --setup
--network-wide
Values not accepted.
Sequentially indexes all of the subsites in a network.
$ vip @mysite.production -- wp vip-search index --network-wide
--version
Accepted values: index version number, next
, active
, current
, or previous
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 --indexables
parameter.
For example, to index version 2
of a posts index:
$ vip @mysite.production -- wp vip-search index --version=2 --indexables=post
--indexables
Accepted values: single value Indexable or comma-separated list of Indexables
Default values: all registered Indexables (post
, user
, term
, comment
)
Targets specific Indexable(s).
For example, to index the term
Indexable:
$ vip @mysite.production -- wp vip-search index --indexables=term
--upper-limit-object-id, --lower-limit-object-id
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 100
:
$ vip @mysite.production -- 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 50
to 10
:
$ vip @mysite.production -- wp vip-search index --upper-limit-object-id=50 --lower-limit-object-id=10
--per-page
Accepted values: numerical value of posts per page
Default value: 500
, maximum of 5000
Determines the amount of posts to be indexed per cycle.
For example, to increase the indexed posts per cycle to 1000
:
$ vip @mysite.production -- wp vip-search index --per-page=1000
--include
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 7
and 20
:
$ vip @mysite.production -- wp vip-search index --include=7,20
--post-type
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 event
and recipe
:
$ vip @mysite.production -- wp vip-search index --post-type=event,recipe
--show-bulk-errors
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 @mysite.production -- wp vip-search index --show-bulk-errors
--skip-confirm
Values not accepted.
Omits the Enterprise Search confirmation prompt, “You are about to run a destructive operation. Are you sure?”, for destructive operations.
For example, indexing with --setup
is a destructive action and will generate the prompt:
$ vip @mysite.production -- 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
Including --skip-confirm
will omit the destructive operation confirmation prompt:
$ vip @mysite.production -- 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
Indexing status
Check on the progress of an index
command that is currently running with get-indexing-status
:
$ vip @mysite.production -- wp vip-search get-indexing-status
Output will be returned in JSON format with the below fields:
"indexing"
:true
for in process,false
for inactive"method"
: how the indexing was actioned-
"items_indexed"
: number of items already indexed -
"total_items"
: total number of items needing to be indexed
{"indexing":true,"method":"cli","items_indexed":1000,"total_items":1015153}
In a scenario where the indexing has unexpectedly failed, you may still see true
for "indexing"
, but the total items will return -1
:
{"indexing":true,"method":"cli","items_indexed":0,"total_items":-1}
Stop indexing
An active indexing command in process can be stopped with stop-indexing
:
$ vip @mysite.production -- wp vip-search stop-indexing
Troubleshooting
Error: An index is already occurring. Try again later.
Check the status of indexing with get-indexing-status
. If no indexing command is currently running (i.e. the indexing command unexpectedly stopped) and the error is being displayed, remove the index lock with delete-transient
before re-trying to index:
$ vip @mysite.production -- wp vip-search delete-transient