Offload any WP_Query to Enterprise Search

With Enterprise Search, standard front-end search queries (which have an s argument) are automatically sent to Elasticsearch. No code changes are needed.

Offloading to WP_Query is not enabled by default. If you need to use ES on non-search queries, you’ll need to add an extra WP_Query argument.

Deciding which query to offload

It is not necessary to offload all queries to Enterprise Search. There are many queries that run on MySQL perfectly fine and offloading them may not provide significant benefit. For example, offloading it on every request for a single post will not be effective and can result in rate limiting.

We generally recommend offloading queries that are poorly performing (i.e. taxonomy and meta queries). To find out which queries may be slow on your site, use Query Monitor.

Adding the query argument

Be sure to test each query as you go, make sure the results are what you expect, and adjust as needed!

The standard (and easy) way to do this leverages the built-in es-wp-query adapter, which will handle transforming the query into an Elasticsearch request, obtain the search results (generally, a list of Post IDs), and then obtain the post data from the database.

Using pre_get_posts

You can offload using the pre_get_posts hook:

function vip_sample_es_offload( $query ) {
    if ( $query->is_main_query() && ! $query->is_category() ) { // Conditions to offload to ES.
        $query->set( 'es', true );
    }
}
add_action( 'pre_get_posts', 'vip_sample_es_offload' );

WP_Query arguments

Alternatively, you could directly add it to the argument list where you already call WP_Query (or get_posts) directly by adding 'es' => true to the query args:

$query = new WP_Query(
	array(
		'post_type'      => 'post',
		'post_status'    => 'publish',
		'posts_per_page' => 10,
		'es'             => true,
	)
);

However, if any of those queries are filtering by terms (or taxonomy, e.g. categories), the terms feature will need to be enabled. It would also be worth reviewing the meta and taxonomy filters, because those aren’t indexed by default.

Advanced use

If you’re offloading existing MySQL queries to Elasticsearch, please use the approach above, with the es parameter. That parameter activates an adapter called es-wp-query that does a very good job of mapping most SQL queries to Elasticsearch, and should cover most use cases.

Direct MySQL

In other cases, you may wish to query MySQL directly. For example, if you’re just providing a list of post IDs, and the query is very fast, there may be no need to use Elasticsearch. Omit the es parameter. Monitor both the results and the speed using tools such as New Relic and Query Monitor / Debug Bar.

ElasticPress offloading via ep_integrate

If es, or a direct DB query, does not produce the search results you need, you may wish to use the ElasticPress approach for offloading select queries – which looks similar but behaves differently.

Instead of es in the WP_Query arguments, use ep_integrate (set to true). You can do this on a case-by-case basis; for example, almost all offloaded queries might use es, and one very specialized query might use ep_integrate.

Please be sure to review the ElasticPress documentation before using this option. And of course, if the query involves terms or users, those features will need to be enabled.