Enable Enterprise Search features
Enterprise Search does not index everything, and is currently focused mainly around posts. Other indexables/features available in the underlying ElasticPress 3.4.2 such as terms and users may be enabled, but they are not yet tested or guaranteed to work.
Only WordPress events trigger the underlying ElasticPress plugin hooks that cause the index to update. Directly modifying the database or editing data through means that aren’t handled by these hooks will not change the Elasticsearch (ES) index. For example, database imports will not change the ES index.
Editing most pieces of post data will result in incremental indexing. The exceptions are through the various allow lists in both ElasticPress and VIP Search. A very prominent example is the vip_search_post_meta_allow_list
filter which controls which post meta are indexed. If it’s empty, no post meta is indexed.
Once you’ve set up the allow lists to match existing queries, you are ready to perform searches, but additional configuration is possible in order to send other arbitrary queries to Elasticsearch.
The following presumes that Enterprise Search has been enabled by adding the required constants to the code.
Search
Search is a feature that is enabled by default.
Queries with an s
parameter will be automatically sent to Elasticsearch and searched against post_title
, post_content
, and post_excerpt
. This is highly beneficial because the default MySQL behavior, fulltext search with LIKE
clauses, can result in poor database performance.
To prevent this behavior and force the query to go to MySQL, set both the es
and ep_integrate
WP_Query parameters to false. (Keep in mind, this results in poor performance).
Protected content
By default, only public content is indexed. To enable indexing of non-public content, that feature must be activated, and a re-index (or versioning) will be necessary.
$ wp vip-search activate-feature protected_content
Note
Once enabled, there’s a real risk of exposing non-public content to unauthorized users. Test all queries carefully!
Indexables
Each database resource in WordPress uses a related class, e.g. WP_Query, and has a separate Enterprise Search index. Not every one is supported, or enabled by default.
Posts
The posts indexable supports WP_Query. Posts are indexed by default.
Terms
The terms indexable supports WP_Term_Query.
To index terms (taxonomies), you will need to explicitly enable this as a feature.
If you’ve created an allow list for taxonomies, then you’ll need to enable the feature and then initiate a re-index. You can do this via the VIP-CLI.
Note
Because these are WP-CLI commands, you’ll need to pass them to the VIP-CLI, as demonstrated in the first example (where our app id is 103). We’ve omitted this prefix from the remaining commands for clarity.
In the terminal, run the following commands to activate the feature, enable the terms mapping, and (re)index the terms.
$ vip @103 -- wp vip-search activate-feature terms
Warning: Feature is usable but there are warnings:
Warning: This feature requires a re-index. You may want to run the index command next.
Success: Feature activated
If you’re not using a multisite, the --network-wide
option (to apply to all subsites) is not necessary. You can also specify just a single subsite of a multisite with --url
.
Now that the feature is activated, we can enable the mapping and index just the terms:
$ wp vip-search put-mapping --indexables="term"
⚠️ You are about to run a destructive operation. Are you sure? [y/n] y
Adding term mapping...
Success: Mapping sent
$ wp vip-search index --indexables="term"
Processed 1/1. Last Object ID: 1
Number of terms indexed: 1
Total time elapsed: 0.101
Success: Done!
Users
The users indexable supports WP_User_Query. To index users, you will need to enable the indexable first.
In the terminal, run the following command to activate the feature, enable the users mapping, and (re)index the users.
$ wp vip-search activate-feature users
Warning: Feature is usable but there are warnings:
Warning: This feature requires a re-index. You may want to run the index command next.
Success: Feature activated
$ wp vip-search put-mapping --indexables="user"
Success: Mapping sent
$ wp vip-search index --indexables="user"
Processed 1/1. Last Object ID: 1
Number of users indexed: 1
Total time elapsed: 0.197
Success: Done!
Command arguments
These arguments may be handy depending on the type of site. Each is preceded by two dashes
- network-wide – runs the command against all subsites in a multisite
- url=”top.example.com” – runs the command against just this particular subsite in a multisite
- show-errors – adds verbosity to the output