loading

Debugging the Backend - Search Detail, Experience Preview, and API Requests| Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

  • Experience Training
  • Search Detail Overview
  • Search Metadata
  • Search Factors
  • Debugging with Experience Preview
  • How to Read an API Request
  • What to Look For in the API Request

Overview of Debugging the Backend

When it comes to debugging the search results themselves, you have many tools at your disposal, including:

  • Experience Training
  • Search Detail Overview, with search metadata and search factors
  • Experience Preview
  • API Requests

We’ll review these in detail in this unit.

Experience Training

Experience Training is a critical tool for debugging backend issues and optimizing results for all search experiences, as you’ll learn about in the Post Launch Optimization module. The more feedback that you provide or corrections that you apply here, the better the algorithm can perform in the future.

You can do things like:

  • Review Featured Snippets: This screen will surface all featured snippets that the algorithm would return. You can accept, reject, or modify the snippets, and if you have snippets set to APPROVE_ONLY then only those you accept will display on search results.

experience training featured snippets

  • Review Spell Checking: Here you can review any suggested spell checks and accept or reject the corrections. If you reject a correction, the algorithm will no longer surface that correction when that search term is run for that experience.

experience training spell check

  • Review NLP Filters: Here you can review the NLP filters that were applied to any queries run and accept or reject. If you reject it, the algorithm will no longer apply the NLP filter for that search term for that experience.

experience training nlp

Overview of Search Detail Screen

With Search Detail, you are able to view any historical search run on Answers along with a recreation of its results and the factors that led to those results being returned.

This will allow you to understand historically what results were being returned for searches as well as understand what factors caused the results to be returned. With Search Detail, you are provided with a set of tools to not only understand what results were returned on the backend but also why results were returned.

You can access the Search Detail screen by navigating to:

Answers → Experiences → View Experience → Search Logs → Search ID

Inspecting Page

Alternatively, you can go directly to a specific test query’s Search Detail screen by clicking “Debug in search log” at the top of your Experience Preview results.

Debug via Search Log

Once you navigate through to a specific Search ID (which represents a single user’s search) you will then be presented with the Search Detail screen, where you can find metadata related to Session ID, Location Bias, Search Type, etc, a recreation of the results returned to the user and most importantly, search factors.

We’ll dive into all of the various terms on this screen in the next section.

Inspecting Page

Search Metadata

Search metadata is a combination of inputs from the user’s search like Location Bias and Language as well as outputs from the system such as Search ID and Session ID used to identify a unique search that help provide you with additional context for the given search.

Inspecting Page

Search metadata will include the following:

Attribute Description
Search Term Search Term string searched by User
Search ID ID of Search
Date Time (in UTC) Time Search was ran
Language Language / Locale of Search
Location Bias Location of User
Search Type Type of Search (Universal or Vertical)
Configuration Version Configuration Number and Label if Applicable, ex: 107 (Production)


Search Factors

Search Factors helps provide you with context as to why results were returned for a given search. Let’s take a look at the example query “Yext NYC office address”. This query on Yext.com returned a Direct Answer, the Yext NYC office entity, a handful of FAQs, as well as Knowledge Center articles, Help Center articles, and links from a third party backend.

Inspecting Page

When trying to understand the why in the example query, “Yext NYC office address”, you can see that the following search factors were applied to the query:

NLP Filters: Builtin.location: NYC builtin. entityType: Location

Inspecting Page

As the Admin in this example, you can quickly see that the query produced a match in the offices vertical to two NLP filters: one is a match to the New York City location, and the other is to the Location entity type, which is why the NYC office location entity was returned within the offices vertical:

Inspecting Page

If we scroll down the page, we see that the other entities and verticals, for example FAQs, Knowledge Center Articles, and Help Center links, were all returned due to a text search match within on the ‘name’ field, identifiable by the bold highlighting within the text search match:

Inspecting Page

light bulb
Tip
Always look for bold highlighting in the text search matches to understand which entity field keywords matched in a given query.

If you are in the QA process in this example and are trying to understand why Knowledge Center links were returned in the query, the Administrator can quickly identify that there was a text search filter match, set up in the Search Configuration, that is matching on “location” text in the query.

As of now, Search Factors contain the following attributes for each Search:

Attribute Examples
NLP Filter builtin.location: NYC (offices), builtin.entityType: Location (offices), builtin.medicalCondition: (providers)


Debugging with Experience Preview

Within the Experiences UI of the Yext platform, an Administrator can also run various searches to get a quick preview of how results are returned to the backend.

Below is a sample workflow in which you can use the Experience Preview to debug and optimize your backend via the Search Configuration. Let’s say that we’ve determined users are searching quite frequently for “open positions” in the Turtlehead Tacos Answers experience. We can use Experience Preview to understand what results are coming back for this query:

navigating to search configuration

The search only returns a somewhat relevant FAQ. We should likely be showing all open jobs instead. In order to optimize the query, let’s add a one way synonym from “positions” -> “jobs” and click save to create a new Search Configuration version.

navigating to search configuration

The version will automatically update our Staging environment assuming we are, as a best practice in Staging, pinned to the “LATEST” Search Configuration version. Therefore, we can jump right back to our Experience Preview and re-run the search:

navigating to search configuration

Now all jobs matching our search criteria return!

Let’s take it a step further. Looking at the above screenshot, we see the Waiter job returning in results (Entity ID: Job 8). This job should not be returning because it is a “Closed” position based on an open/closed custom field on the Job entity type. It should be filtered out using a Saved Filter. Currently, we do not have any saved filter applied to the Jobs vertical:

navigating to search configuration

If we apply our Saved Filter to this vertical (which filters out closed Jobs using custom fields) and click Save, we can re-run the search using the updated configuration:

navigating to search configuration

Success! The inactive job (Entity ID: Job 8) is no longer returning in the Jobs vertical.

We have debugged the “open positions” query using Experience Preview and optimized by 1) adding synonyms and 2) applying a Saved Filter.

Looking at API Requests

An Administrator can also quickly see which results were returned and which filters were applied to a given query by looking at the API Requests in-browser. When debugging, we often need to look at these API results, along with the Search Details screens, to understand what is being returned by the Answers algorithm.

You can now view API logs directly from your Experience Preview results. Just toggle the “Show API Request” option in the top right of your Experience Preview results to view API Request and Response information. You can click “View More” to expand request details, as well as view and copy the raw API response (with line formatting options) in the next window. This will save you time when debugging and sharing searches!

Experience Preview API Requests

Alternatively, yout can right click on the results page and click inspect:

Inspecting Page

light bulb
Tip
When debugging, do so from vertical search, as you will get a better set of data to debug in vertical vs. in universal.

Once you click inspect, you can then navigate over to the “Network” tab where you will want to re-run the search. You should see a Live API request show up, which you can always identify via the “query?” naming convention.

Inspecting Page 2

When you run the search and double-click on the API request, a new tab will open and you’ll be presented with a JSON blob of all the vertical results. The result will look something like this:

Inspecting Page 3

light bulb
Tip
If you are seeing an unformatted JSON result, make sure to download the JSON Formatter Chrome Extension.

If you collapse the “results” object in the above example, you can get a really quick summary of how the results were returned:

Inspecting Page 4

What to Look for in the API Request

At a high level, you should always see results returned in the API request, since it’s built off the Live API. API results should update instantaneously after you make an edit in the Knowledge Graph. If you ever see an error when loading the API request (specifically a 500 error), then there could be a Yext Live API outage.

Additionally, you should always look out for any discrepancies between the back end data and the front end display. For example, if you are using a subtitle of c_providerTitle on your doctor card and it isn’t displaying right away - look at the API request! If you can’t find that value in the API request, there’s your problem! The frontend displays the information in the API request, so if the information isn’t there, the frontend can’t display it. If you are seeing that data is not appearing right away in the API results, then there could potentially be a lag.

Here are some specific insights that we can extract from the above example (note these are also identifiable via Search Factors in Search Detail):

  • resultsCount: 4:

    • We know that the query “doctors who treat acne” returned 4 doctors on the backend.
  • appliedQueryFilters (also known as NLP Filter):

    • We know that the doctors were filtered on a field called “Conditions Treated” with a value of “Acne”.
  • locationBias:

    • We know that location-centric results will be biased to my current device location, which is Yarmouth, Maine, United States of America.
light bulb
Tip
You can spoof your location in the API Request by adding &location=lat,long to the request URL.
unit Quiz
+20 points
Daily Quiz Streak Daily Quiz Streak: 0
Quiz Accuracy Streak Quiz Accuracy Streak: 0
    Error Success Question 1 of 6

    True or False: The Search Detail screen provides you with a historical, backend view of not only what results were returned but also why results were returned

    Error Success Question 2 of 6

    True or False: NLP Filter is an example of a search factor

    Error Success Question 3 of 6

    True or False: When inspecting the page and looking at API results, it is not possible to see what NLP Filters were applied.

    Error Success Question 4 of 6

    True or False: When looking at API results, you should always inspect the Universal results, not Vertical results.

    Error Success Question 5 of 6

    Which of the following is true regarding location searching and location biases?

    Error Success Question 6 of 6

    If you don't like a featured snippet that is returned or an NLP filter that is applied for a given query, can you do anything about that?

    You're out of this world! 🌎

    You've already completed this quiz, so you can't earn more points.You completed this quiz in 1 attempt and earned 0 points! Feel free to review your answers and move on when you're ready.
1st attempt
0 incorrect
Splash Loading