If you’re already a Hitchhiker, log in to access this content.
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 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_ONLYthen only those you accept will display on search results.
- 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.
- 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.
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
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.
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.
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.
Search metadata will include the following:
|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 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.
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
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:
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:
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:
|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:
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.
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:
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:
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:
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!
Alternatively, yout can right click on the results page and click inspect:
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.
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:
If you collapse the “results” object in the above example, you can get a really quick summary of how the results were returned:
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):
- 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”.
- We know that location-centric results will be biased to my current device location, which is Yarmouth, Maine, United States of America.