Skip to content

Debug with Search Dev Tools

Enterprise Search Dev Tools is built into Enterprise Search and can be found in the WordPress admin bar. It allows for Elasticsearch queries to be edited and run in real-time, which is useful for debugging and testing individual queries.

Prerequisites

The panel is accessed by selecting the “Search: x query” link in the WordPress admin bar.

In this example screenshot, the link to Enterprise Search Dev Tools in the WordPress admin bar is highlighted with a red border around it.

The top area of the Enterprise Search Dev Tools panel summarizes search status information types for the current query:

Example screenshot of the Enterprise Search Dev Tools panel

Each search status information type can be selected to reveal more details:

Example search status information as they appear for VIP’s Documentation site

When no longer needed, the Enterprise Search Dev Tools panel can be closed by selecting the “x” figure in the top right corner.

Queries

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

Results are returned based on the content that is indexed.

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

If an item appears in the response JSON, but not in the page, verify that the item has the correct status and has not been filtered out of the results because the post has a non-public status (i.e. draft).

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 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.

See the below video for an example of editing the order of the _score in the Elasticsearch query and running it to test and then, resetting it afterward:

To check if your site is properly offloading its search functionality to Enterprise Search:

  1. On the front-end, search for a word present in one of the posts (e.g. “example”):
  1. Click on Search Dev Tools and expand on the query itself:

If you see the search term as part of the “Request”, it is confirmed that your search is being offloaded to Enterprise Search!

  1. If you do not, you should expect to see the below query in Query Monitor > Queries:
This is the default WordPress/MySQL full text query using “LIKE”, which can be very inefficient (especially with significant amounts of content).

If you don’t see the above query, it might be cached in object cache and may need to be flushed:

wp cache flush

Errors

It is an indication that Enterprise Search is not working as expected if any of the following errors are returned in the Search Dev Tools panel.

index_not_found_exception

The index_not_found_exception error indicates that there is no index present:

{
  "error": {
    "root_cause": [
      {
        "type": "index_not_found_exception",
        "reason": "no such index [vip-200508-post-1]",
        "resource.type": "index_or_alias",
        "resource.id": "vip-200508-post-1",
        "index_uuid": "_na_",
        "index": "vip-200508-post-1"
      }
    ],
    "type": "index_not_found_exception",
    "reason": "no such index [vip-200508-post-1]",
    "resource.type": "index_or_alias",
    "resource.id": "vip-200508-post-1",
    "index_uuid": "_na_",
    "index": "vip-200508-post-1"
  },
  "status": 404
}

A missing index can be confirmed with the wp vip-search health validate-counts CLI command.
Example command and output:

$ wp vip-search health validate-counts
Skipping validation of 'post' index as it doesn't exist.

parsing_exception

A parsing_exception error indicates that the index has not been correctly mapped if the value of reason is field [post_date_gmt] is of type [indexed,tokenized], but only numeric types are supported:

{
  "error": {
    "root_cause": [
      {
        "type": "parsing_exception",
        "reason": "field [post_date_gmt] is of type [indexed,tokenized], but only numeric types are supported.",
        "line": 1,
        "col": 1
      }
    ],
    "type": "search_phase_execution_exception",
    "reason": "all shards failed",
    "phase": "query",
    "grouped": true,
    "failed_shards": [
      {
        "shard": 0,
        "index": "vip-123-post-1",
        "node": "12345",
        "reason": {
          "type": "parsing_exception",
          "reason": "field [post_date_gmt] is of type [indexed,tokenized], but only numeric types are supported.",
          "line": 1,
          "col": 1
        }
      }
    ]
  },
  "status": 400
}

In this case, Elasticsearch detects that the first field of post_date_gmt does not have the proper mapping. To correctly map the index, use the index command with the --setup command option:

$ wp vip-search index --setup
⚠️  You are about to run a destructive operation. Are you sure? [y/n] y
Indexing with setup option needs to delete Elasticsearch index first, are you sure you want to delete your Elasticsearch index? [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.184
Success: Done!

Last updated: November 22, 2022