Skip to content

Backgrounds

How-to Guides

Technical References

Local development /

Use Enterprise Search on a VIP Local Development Environment

Prerequisites

  • VIP-CLI is installed and has been updated to the most current version.
  • Basic understanding of WordPress development
  • Basic Git experience
  • A local machine capable of running Docker Desktop
  • Familiarity with the command line and code editing

Set up local environment

Follow the steps to set up a VIP Local Development Environment using Method B without an application ID and the slug name example-site.

  1. After the environment is created and started, log in to the backend with the default credentials: http://example-site.vipdev.lndo.site/wp-admin
    The local environment is set up as an empty multisite (with one main site).
  2. Navigate to the home page: http://example-site.vipdev.lndo.site
    After logging in, the WordPress admin too bar will be visible at the top of the browser window.
Screenshot of the home page with the WordPress admin tool bar visible at the top
  1. Navigate to the vip-config directory.
cd ~/vipdev
cd vip-go-skeleton/vip-config
  1. To enable both Enterprise Search and Search Dev Tools, add the code below to vip-config.php:
/**
 * Enable VIP Search
 *
 */
define( 'VIP_ENABLE_VIP_SEARCH', true );
define( 'VIP_ENABLE_VIP_SEARCH_QUERY_INTEGRATION', true );
define( 'EP_IS_NETWORK', true );

/**
 * Enable Search Dev Tools
 * 
 */
define( 'VIP_SEARCH_DEV_TOOLS', true );

After completing the above steps, Elasticsearch is now enabled for the site. Perform a basic test to verify that Enterprise Search is running as expected.

  1. Reload the page with the search results: http://example-site.vipdev.lndo.site/?s=example
  2. Locate the Search Dev Tools dropdown link in the admin tool bar. It will appear to the right of Query Monitor dropdown link
A screenshot of Search Dev Tools and Query Monitor links in the WordPress admin tool bar
  1. Click the Search Dev Tools and expand the query:
The query results will be displayed in JSON format.

On the VIP Local Development Environment, Enterprise Search automatically starts in the background (not enabled yet) and existing posts at that time were indexed.

Testing indexing

  1. To verify if indexing is working, publish a new test post with title of “New test post” and content “This post contains some words to search for. Who likes cheeseburgers? What about hot dogs?”.
  1. Perform a search again with text that was in the new test post: http://example-site.vipdev.lndo.site/?s=cheeseburgers
New test post returned from Elasticsearch in search result.
  1. Use the CLI to check the health of the index with the validate-counts command.
vip --slug=example-site dev-env exec -- wp vip-search health validate-counts

The output from the command will display post counts for two different post types, post and page, and compare the count for each between the database (DB) and index (ES).

Validating post count

✅ no inconsistencies found when counting entity: post, type: post, index_version: 1 - (DB: 2, ES: 2, Diff: 0)
✅ no inconsistencies found when counting entity: post, type: page, index_version: 1 - (DB: 1, ES: 1, Diff: 0)

The health check above shows that there are no differences between the database and the index. This indicates that Enterprise Search is enabled and indexing is running correctly.

Enterprise Search and new subsites

  1. Create a new subsite by navigating to “Sites” in the Network Admin:
    http://example-site.vipdev.lndo.site/wp-admin/network/sites.php
    and selecting “Add New”.
  2. Complete the field prompts with the following values:
    • Site Address (URL): example-subsite
    • Site Title: Example Subsite
    • Admin Email: example.admin@example-subsite.com (or any email value of your choice)
  1. Click on “Add Site“.
View of completed fields for “Add New Site”
  1. Navigate to the home page of the site on the front end.
  2. Enter the search term “hello” in the Search field.
    http://example-subsite.example-site.vipdev.lndo.site/?s=hello
  3. Open the Search Dev Tools panel to view more information about the search results.
    Search Dev Tools shows that an index exists for the new subsite, but no posts have been indexed.
Search Dev Tools displays zero search results for the term “hello” on the new subsite.
  1. Use the CLI to check the health of the subsite index with the validate-counts command.
vip --slug=example-site dev-env exec -- wp vip-search health validate-counts --url=example-subsite.example-site.vipdev.lndo.site

The health report indicates there are no posts in the subsite index:

Validating post count

🟧 skipping, because there are no documents in ES when counting entity: post, type: post, index_version: 1
🟧 skipping, because there are no documents in ES when counting entity: post, type: page, index_version: 1
  1. Run the index command to sync the posts in the database with the index.

Note: When re-indexing a live production site, use versioning. Since this is a local environment with no live traffic, we will index as-is.

vip --slug=example-site dev-env exec -- wp vip-search index --setup --url=example-subsite.example-site.vipdev.lndo.site
⚠️  You are about to run a destructive operation. Are you sure? [y/n] y
Adding post mapping…
Success: Mapping sent
Indexing posts...
Processed 2/2. Last Object ID: 1
Number of posts indexed: 2
Total time elapsed: 0.524
Success: Done!
  1. Search for “hello” again in the subsite: http://example-subsite.example-site.vipdev.lndo.site/?s=hello

The search result will now be displayed.

  1. The Search Dev Tools will also return a search result:

Offloading to WP_Query

Non-search queries are not offloaded to Enterprise Search by default. In order to offload them to Enterprise Search, WP_Query will need to be modified.

  1. Generate some posts with content using the command line.
curl -N http://loripsum.net/api/5 | vip --slug=example-site dev-env exec -- wp post generate --post_content --count=10

This generates 10 new posts with Lorem Ipsum content in the root site. The posts will be indexed immediately.

  1. Repeat the same command with an older date using the --post-date option.
curl -N http://loripsum.net/api/5 | vip --slug=example-site dev-env exec -- wp post generate --count=10 --post_type=post --post_date=1999-01-04
  1. Navigate to the home page to view the newly generated posts: http://example-site.vipdev.lndo.site
Newly generated posts displayed on the home page
  1. Navigate to the second page of posts: http://example-site.vipdev.lndo.site/page/2/
  2. Open the Query Monitor panel and view “Queries”. Look for the query that determines which posts are displayed on the second page:
SELECT SQL_CALC_FOUND_ROWS wp_posts.ID
 FROM wp_posts
 WHERE 1=1
 AND wp_posts.post_type IN ('post', 'page')
 AND (wp_posts.post_status = 'publish'
 OR wp_posts.post_status = 'private')
 ORDER BY wp_posts.post_date DESC
 LIMIT 10, 10

If the query does not appear, the object cache may need to be flushed with wp cache flush.

  1. In the footer, the “Recent Posts” widget displays the latest five posts. The query for this widget can also be found in Query Monitor:
SELECT wp_posts.ID
 FROM wp_posts
 WHERE 1=1
 AND wp_posts.post_type = 'post'
 AND ((wp_posts.post_status = 'publish'))
 ORDER BY wp_posts.post_date DESC
 LIMIT 0,5
Recent Posts footer widget.

The query for the “Recent Posts” widget and for the posts on the second page are usually relatively fast, but they can become slow on a site with a lot of posts and traffic.

  1. On the local machine, navigate to the client-mu-plugins directory in the vip-go-skeleton directory and create a new file named search.php.
cd ~/vipdev/vip-go-skeleton/client-mu-plugins
touch search.php
  1. Add the below code to search.php. The code in this snippet uses the pre_get_posts hook to offload both queries (e.g. not of the back-end or category type):
<?php

/**
 * Offload to ES
 *
 */
function vip_sample_es_offload( $query ) {
	if ( is_admin() ) {
		return;
	}
	
    if ( ! $query->is_category() ) {
        $query->set( 'es', true );
    }
}
add_action( 'pre_get_posts', 'vip_sample_es_offload' );
  1. Navigate to the homepage and select the Search Dev Tools dropdown link from the WordPress admin tool bar: http://example-site.vipdev.lndo.site

Two Enterprise Search queries will be displayed:

  1. Refer to “Queries” in the Query Monitor panel. Locate the /* ES_WP_Query Shoehorn */ comment at the end of the query. This message indicates that the query was generated by es-wp-query:
Screenshot of the Queries view of the Query Monitor panel

When Elasticsearch returns the list of post IDs that matched the query, the database is queried (via the “shoehorn”) to obtain the post data needed to construct the HTML result that a user sees on the front end.

Elasticsearch queries run first, and any other MySQL queries (without the shoehorn comment) run afterwards.

Cleaning up

The destroy command dismantles the local development environment.

vip --slug=example-site dev-env destroy

The code that was manually cloned earlier will remain in the ~/vipdev directory. This can be explicitly deleted with the rm command:

rm -r ~/vipdev

Last updated: December 21, 2021