Skip to content


How-to Guides

Technical References

Enterprise Search /

Search implementation tips

These tips may be helpful when setting up Enterprise Search for the first time, or when designing advanced queries.

Migrating from another Search solution

Please review our suggestion on how to get Enterprise Search set up without enabling active searches.

Note that before fully enabling Enterprise Search, any existing copies of search code (such as es-wp-query) that reside in your code repository should be removed, to avoid conflicts with the code used for Enterprise Search that is provided in vip-go-mu-plugins.

Standard search options

If you’re not happy with the search results for a standard text search (i.e. a WordPress search using a query parameter such as s), then perhaps try using ep_integrate (from the ElasticPress fork) instead of es. This bypasses the provided es-wp-query adapter and uses the ElasticPress code instead, which may filter and normalize some special characters, such as apostrophes and quotes, differently.

This will of course depend on your use case and the type of text being searched. We recommend starting with the es option.

You may also wish to try filtering the search term (in your code) prior to executing the search.

Post meta and term meta

Only index what you need. If you are not using the meta key in a query as a filter, then it does not need to be indexed.

Post types and taxonomies

It’s easier to add post types and taxonomies to the allow lists in code first, than to incrementally add them and re-index (or version the indexes). Especially if multiple subsites and search indexes are involved.

Do try to avoid indexing anything that will not be searched.

Disabling Elasticsearch conditionally for certain post types

Some default MySQL queries are better. Some plugins provide good (or great) solutions to standard MySQL searches. For example, there’s a redirect plugin that uses a custom post type and has built-in support for querying these using standard MySQL. In these cases, omit that post type from indexing, and ensure that related queries do not use the es query argument.


If you start getting unexpected results ordering, you are probably sorting in your WP_Query. Remove the sorting from the WP_Query and you should see the default Elasticsearch ordering by relevancy results.

By date

If you wish to sort Elasticsearch results by date, use the ep_set_default_sort filter. For example to sort from newest to oldest:

add_filter( 'ep_set_sort', 'ep_sort_by_date', 20, 2 );

function ep_sort_by_date( $sort, $order ) {
	$sort = array(
					'post_date' => array(
						'order' => $order,
	return $sort;


If you get too many loosely relevant results on the end of your results list, you can use min_score on the ES query to trim those down without hurting the more relevant results. A good starting point depends on your scoring methods; review the max_score and individual _score values in the response JSON using Search Dev Tools (coming soon) to determine what works for you. This helps searches for “import” by reducing the unrelated results that match just the word “port” for example.

The following code snippet is a good starting point – the min score is based on the scores obtained on a simple test site, without additional customizations.

add_filter( 'ep_formatted_args', 'vip_sample_filter_min_score', 25, 3 );

 * filter the min_score to exclude unrelated results
function vip_sample_filter_min_score( $formatted_args, $args, $wp_query ) {
     * adjust min_score
     * higher score = better matches
     * lower score = looser matching, more results
    $formatted_args['min_score'] = 0.002;

    return $formatted_args;

Note: the min_score value is arbitrary and can be dependent on the search terms themselves.

AJAX search requests

Enterprise Search relies on a secure API to provide a powerful set of capabilities. It does not provide a public endpoint for running searches, and Elasticsearch results are rather raw. We do not recommend attempting to proxy the search results.

If you need a way to query for and obtain post data (i.e. search results) in JSON format directly from a browser or other client via an AJAX request, we recommend building a custom, cacheable, API adapter route that limits the types of queries that can be made, and use only the post IDs from the raw Elasticsearch results. Any other details from Elasticsearch should not be used for constructing a user interface. Obtain any additional post or comment details from WordPress, such as post title, URL, etc, using its built in data access functions.

Language agnostic

To make search insensitive to diacritics, add asciifolding into the filter ep_default_analyzer_filters to convert Unicode characters to their ASCII counterparts:

add_filter( 'ep_default_analyzer_filters', 'vip_add_asciifolding_filter' );

function vip_add_asciifolding_filter( $filters ) {
    $filters[] = 'asciifolding';

    return $filters;

For example, Elasticsearch considers “Español” and “Espanol” to be different terms and will yield different search results. Once asciifolding has been applied, “Español” and “Espanol” will be treated as the same term.


Changing this setting will require a re-index to account for the changes.

Last updated: October 29, 2021