Debugging is something you'll become familiar with for Search — from QA'ing a new experience, testing configuration changes, or investigating a search quality issue. If done properly, you'll isolate the issue and either implement the solution yourself or clearly articulate it to engineering.

The first step is to determine whether an issue is a backend or frontend problem. A general rule of thumb: if the algorithm returns the wrong results or results in the wrong order, you have a backend issue. If the results are returned and ranked correctly in the backend but something looks different in the frontend, it's likely a frontend issue. You can determine this by running test searches and comparing them to the results in Test Search, which shows the backend results.

Backend Debugging Tools

There are several useful tools at your disposal. 

• Test Search — isolate the backend from the frontend and see raw results
• Search Log Details Page — see why specific results were returned
• Search Query API Responses — inspect the raw API response as JSON
• Experience Training Table — audit and override algorithm predictions

Using Test Search to Debug

Test Search is often the best place to start. It isolates the backend Search configuration from the frontend so you can see what your "raw" search results look like and then access the Search Log Details page, which contains most of the tools you'll need.

Using the Search Log Details Page to Debug

The Search Log Details page is where you should spend most of your time when debugging. Each search run has a Search Log Details page that shows the results returned for that historical search, as well as the factors that caused those results to be returned.

In general when debugging, compare the expected results to the actual results and determine how and why they differ. Search logs provide the details on why actual results appear.

How to Access the Search Log Details Page

• After running a Test Search, click the dropdown and select Debug Query.

  

• On the Search Logs screen, click into the relevant search log. Logs are sorted by most recent and can be filtered using the search bar.

  

Search Metadata

Search metadata appears in the box above the results. It shows a combination of inputs (location bias, language) and system outputs (Search ID, Session ID) that provide additional context for a given search. From a debugging standpoint:

• Location Bias: the searcher's location — useful for debugging location searches.
• Configuration: the configuration version number and label — helps spot a situation where the label is set to the wrong version.

Search-Level Search Factors

Search Factors tell you all of the factors applied during your search. The search-level factors in the upper right box are applied to the whole search. Start here when debugging general top-level issues — whether a query rule, synonym, or phrase was applied, and what tokens or location was detected.

If a search factor was triggered when it shouldn't have been, or not triggered when it should have, go back and check that the Search configuration is set up correctly for the results you want.

Vertical-Level Search Factors

Vertical score is indicated in the top-right corner of each vertical. It controls whether the vertical is returned at all and what order it appears relative to other verticals.

The vertical score is based on the most semantically similar entity and any biases or thresholds configured. If you have questions about why certain verticals appear or are ranked a certain way, check the vertical scores.

Advanced Search Tier Feature: Semantic search is only available on the Advanced Search tier.

For steps on debugging vertical ranking issues, see the Search Backend Troubleshooting: Vertical Ranking help article.

Entity-Level Search Factors

The results section tells you why each entity was returned, its similarity to the query, the entity sorting order within the vertical, and more. This is where you'll spend the most time when debugging why certain entities were or weren't returned.

Two attributes just below the vertical name apply to the vertical as a whole:

• Inferred Filters: Any entity that does not satisfy the triggered inferred filter exactly will be filtered out. Useful for figuring out why a certain result set is showing or missing.
• Sort Order: Shows the sorting rules applied to the vertical. Use this to determine why results are in a particular order.

Below this are the top 10 results for each vertical. The right side of each result card shows the factors that caused the entity to be returned:

Advanced Search Tier Features: Document search, semantic search, inferred filtering (except on builtin.location), and direct answers are only available on the Advanced Search tier.

Debugging Example

In the following search log, a result with lower semantic similarity is appearing first — but a Query Rule boosts that particular entity, explaining why it returned first. This boost also impacts the vertical score, which in turn can impact vertical ranking.

Using the API Request to Debug

The Search API response contains much of the same information as the Search Log screen, but as a JSON blob. It's useful for targeting discrepancies between the backend data and the frontend display — the frontend inherits information from the API response, so if the data isn't there, the frontend can't display it.

For example, if a subtitle of c_providerTitle isn't displaying on your doctor card, look at the API request. If that value isn't in the API response, that's your problem.

Note: If you ever see a 500 error when loading the API request, there may be a Yext Live API outage. Check the Yext Trust Site for any outages.

Note: When debugging results for a specific vertical, the API request for the vertical search may give more information than the universal search request.

How to Access API Requests

Viewing In-Platform

Click the code brackets icon ("View Code") in the top right of your Test Search results. You can view and copy the raw API response, and copy the URL to share or open in your browser.

Viewing in the Browser Console

Right-click on the results page and click "Inspect" to access the console. Use keyboard shortcuts: command + shift + c (Mac) or ctrl + shift + c (Windows).

Navigate to the Network tab and rerun the search. You will see a Live API request appear, which you can identify by the "query?" naming convention.

Note: If you open the console after running a search, you'll have to rerun the search or refresh the page to see the API request in the Network tab.

Double-click on the API request to open it in a new tab as a JSON blob.

Note: Install the JSON Formatter Chrome Extension if you see an unformatted result.

Example: No Results on Universal Search

You should always see something returned in the API request, even if the search returned no results:

"response": {
  "businessId": 3701021,
  "modules": [],
  "failedVerticals": [],
  "queryId": "018508b7-c43b-d700-590f-52b262c7d64d",
  "searchIntents": [],
  "locationBias": {
    "latitude": 40.7306,
    "longitude": -73.9866,
    "locationDisplayName": "New York City, New York, United States",
    "accuracy": "IP"
  }
}

Note: You can spoof your location in the API Request by adding &location=lat,long to the request URL.

Top-Level API Properties

These are not specific to query results and contain general information about the request. All top-level properties for universal searches are included below. Vertical searches have these properties plus additional result-level properties.

Result-Level API Properties

For universal search, these properties live in the modules array. For vertical search, they live directly in the response object.

What to Look for in an API Request

When reviewing API requests, you may want to collapse long sections (such as results objects) or use CTRL+F to find what you need:

• In a universal search, each vertical is a separate object in the modules array — helpful to see which verticals were returned.
• resultsCount shows the number of results returned for a quick check.
• appliedQueryFilters shows any inferred filters applied, including the field and value — may help explain why certain entities are or are not in the result set.
• locationBias shows the searcher's location and the reference point for place searches.
• results returns the first page of results and all content passed in for each result. If something isn't showing on the frontend, check what's being passed from the backend.
• Within results, highlightedFields shows all keyword search and phrase match matches, including the field name, field value, and the offset position and length of matchedSubstrings.

Experience Training as a Debugging Tool

Experience Training is a way of overriding a prediction served by the Search algorithm. There are two primary debugging use cases:

• Overriding a bad prediction: If the algorithm serves an inferred filter you don't want, you can reject it in Experience Training and no filter will be applied.
• Auditing previous overrides: If you're seeing an issue with an inferred filter, featured snippet, or spelling suggestion, there might be an Experience Training override already approved for that search term. Multiple approved overrides for the same search term can be active at once and confuse the algorithm.