Skip to content


How-to Guides

Technical References

Enterprise Search /

Debug with Search Dev Tools

Logged in administrative users can debug individual queries with the Enterprise Search Dev Tools.

Enabling Search Dev Tools

To enable the tools, please enable Enterprise Search per the documentation, and then, if the Dev Tools do not appear, add the following define to your vip-config.php:

define( 'VIP_SEARCH_DEV_TOOLS', true );

This tool will be available in the admin bar.

Because of the need to display JSON, it’s not implemented as a Debug Bar panel. It operates independently from Debug Bar or Query Monitor.

General details

To use the tool, click the text. A large panel will cover the remainder of the page. It can be closed by clicking the x in the top right corner.

Search status area

The top area summarizes some search status information for the current site:

If the list of items is extensive, a click on each item reveals the details (example is based on this website):


Each separate Elasticsearch query that was run on the current page can be inspected in detail by clicking the + icon

You can see the request payload that was sent to Elasticsearch, and the response payload that it sent back.

When there are search results, that will be indicated and the response hits will contain those matches. In the example above, there were 48 results matching the import keyword.

Query context details

Often, in addition to seeing the query request data, it’s useful to see the WP_Query object attributes and the stack trace.

These can be inspected by clicking the headings at the top of the section:

WP_Query will present the details of the WP_Query object just before the Elasticsearch request.

Trace will provide a stack trace up to the point of the request, which should reveal which functions were involved in constructing the query, and which functions invoked the search.

Editing requests and testing changes

If you’re familiar with Elasticsearch 7.x request formats, you can edit the request and test how changes to a request affect the search results.

For example, in this result that brought back 48 matches, the sort order has been changed to “asc” from the default “desc”

Once the request has been edited, the run and reset buttons will appear.

When you click run, the Result area is updated with the new result. The hits array that contained 48 entries still contains all, but they are in the reverse order; the least relevant match is first.

This will not actually change the rendered page, but provides a way to validate a possible query change before going into the PHP code and modifying the WP_Query arguments, or a pre_get_posts filter, or another more advanced Elasticsearch filter.

You can change any portion of the request this way. Reset will restore the original JSON request and response.

Last updated: May 27, 2021