Skip to content

Enterprise Search on multisite

After completing the steps to code-enable Enterprise Search for an environment, indexes for each site on the network can be created either network-wide or per-site.

Once created, an index for a specific network site can be targeted in CLI commands by passing the site URL in the --url argument. If the --url argument is omitted, the CLI command will target the index of the main site (ID 1).

VIP-CLI command examples

For demonstration purposes, the <app-name> value mytestsite and the <env> value develop are used in the VIP-CLI command examples below. Read more about how to target environments in VIP-CLI commands.

Setting up indexes for all sites on a network

To avoid having some network sites with non-functional searches, set up indexes for all network sites on a WordPress multisite at the same time by including the --network-wide option.

vip @mytestsite.develop -- wp vip-search index --setup --network-wide

Caution

If a multisite has over 100 sites on the 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 sites that will actively use them. Creating unused indexes may negatively impact the indexing and revalidation operations triggered by periodic health checks.

Creating an index for a new site on a network

By default, an index is not automatically created for a newly added site on the network even if Enterprise Search is already enabled for the multisite.

When a new site is created on a multisite, create a new index for that site with the wp vip-search index --setup command. Target the specific network site by passing the value of the site’s ID with the --blog-ids option. In this example, an index is created for network site ID 2:

vip @mytestsite.develop -- wp vip-search index --setup --blog-ids=2

If a network site has been updated by a SQL database import, the wp vip-search index --setup command should be used to re-index the site and bring the database and Elasticsearch index back into sync.

A newly created or updated index for a network site can be tested (and any existing issues identified) by using Search Dev Tools or the wp vip-search health commands.

Note

When a site is added to a network and its index has been set up with the correct mapping, the VIP-CLI command vip-search recreate-network-alias must be run again to account for the newly added site.

Searching across network sites

To enable search functionality across sites on the network, define the EP_IS_NETWORK constant as true in vip-config.php.

define( 'EP_IS_NETWORK', true );

To search across sites on the network, use the sites parameter in WP_Query. The default value is at current, but other accepted values are a site ID, all, or an array of site IDs.

For example, to enable searching across site IDs 2 and 3, use the pre_get_posts hook:

add_action( 'pre_get_posts', 'vip_search_across_sites' );
function vip_search_across_sites( $query ) {
	if ( $query->is_search() && $query->is_main_query() ) {
		$query->set( 'sites', array( 2, 3 ) );
	}
}

Alternatively, use WP_Query to search for the keyword “test” across site IDs 2 and 3, set the parameter ep_integrate to true:

$query = new WP_Query(
	array(
		's' => 'test',
		'sites' => array( 2, 3 ), // Search only in site IDs 2 and 3 
		'ep_integrate' => true,
	)
);

Using the all parameter in WP_Query requires that:

  • All sites on the network have been set up with an index with correct mappings.
  • An alias index (which points to every index in the network) has been created with the VIP-CLI command vip-search recreate-network-alias:
vip @mytestsite.develop -- wp vip-search recreate-network-alias

Last updated: December 22, 2023

Relevant to

  • WordPress