How to Create and Edit a Search Configuration | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

  • How to access and Create a Search Configuration
  • How to edit the Search Configuration
  • How to use Test Search
  • Refresher: UI vs. JSON

How to access the Search Configuration file

You can access the Search Configuration by clicking Search in the navigation bar and then clicking All Experiences. This is where you will create the experience(s) within your account. Note that when you initially navigate to this page, you’ll be presented with a screen that will prompt you to create a new experience. The setup wizard will walk you through the steps to create a Search Configuration and when you make it through all of the steps, you will have the very first version of your backend Search Configuration. Once you’ve created the experience, it will look like the screenshot below:

navigation to Experiences screen

From here, you can:

  • Click View Experience to access the Search Configuration.
  • Click Add Experience to add an additional experience to your account.
  • Click the drop-down next to an experience to get options to Duplicate Experience and Delete Experience.

Creating a New Experience

There are two steps to creating a new experience. In each step, the setup wizard will walk you through the process and provide some best practices and guidance.

Step 1: Enter Experience Details

Enter a name and key for your search experience. The name is used for internal identification only, and the key is used as part of the API call when you eventually apply the configuration to your frontend build. You can always change the name later, though the key will stay the same.

config wizard 1

Step 2: Select Entity Types

Choose the entity types from your Knowledge Graph that you would like Yext Search to search in this experience. You will automatically be presented with entity type options that are enabled in your account.

config wizard 2

Once you have stepped through each of these steps, you have successfully created your very first Search Configuration!

How to edit the Search Configuration

Editing Configuration via UI or JSON

As a reminder, you can edit the Search Configuration through our interactive, in-platform UI or through the JSON editor. Both options work the same way technically in Search; however, the UI uses a point-and-click interface whereas the JSON editor leverages code with JSON syntax. You can use either option to edit your Search Configuration.

light bulb
Some Search configuration features might only be available via the JSON editor. We will make sure to list out JSON-only features in the Configuration: Additional Settings Unit .

Editing Configuration via UI

To update, maintain, and add additional configuration settings, you can access the left configuration settings and click into any of the options (i.e., Verticals, Query Suggestions, Synonyms, etc). The process of updating the configuration through the UI is interactive, so you will typically find yourself in a state of editing, scrolling, and saving.

config UI 1

Test Search

You can always test out your backend configuration in the UI by using Test Search. You can use the full screen interface of Test Search from the Home page of your Experience, or use panel on the right side of the Experience Details screen. Test Search will allow you to run various searches and preview how results are returned based on your configuration of the backend without having to switch over to your front-end experience.

navigating to search configuration

Test Search gives you greater visibility into your search configuration’s output, beyond just the order in which results are returned. With Test Search, you can view:

  • Entity Previews: The same entity previews that you can use and configure in Knowledge Graph are also be visible in the Search Test Search module. This allows you to customize each entity type’s preview content settings (such as a photo or particular field). Learn more about customizable entity previews in this community post .

  • Featured Snippets: You can view featured snippets in the test search, making it easier to test and debug queries. Learn more about direct answers and featured snippets in the Direct Answers - Fields and Featured Snippets unit

  • NLP Filters: Test Search displays which NLP filters have been applied to a given query. Learn more about searchable fields and NLP filters in the Searchable Fields - NLP Filters unit

  • Test Searches Appearing in Search Logs: You can now run a test search and see it immediately in the search logs, so that it’s easier to debug queries over time. Clicking “Debug in search log” will take you directly to that particular query’s search log page, where you can see search factors, search and session IDs, and more.

  • View Raw API Responses: You can now view API responses directly from any query, streamlining debugging and optimization processes. Just toggle the “Show API Request” option in the top right of your Test Search results to view the API Request and Response information. You can click “View More” to expand details.

  • Vertical Tabs: For a given query, you can toggle between universal search and vertical search tabs to better visualize how an end-user may see results for a given query.

  • Facets: With vertical results, Test Search also supports facets. This will allow you to see applicable facets as well as apply them to the search results in order to guage their impact. Note that this is only available in the full screen Test Search on the Home Screen.

Editing Configuration via JSON

To access the Search Configuration in the JSON editor, simply click the “Edit as JSON’ link in the navigation bar.

navigating to search configuration

Once you open the configuration in JSON, you will be presented with a full code editor:

navigating to search configuration

With JSON (JavaScript Object Notation) syntax, a user can quickly add verticals, synonyms, query suggestions, query rules, and more. The JSON configuration will always mirror the UI configuration options but display the various options in code. You can learn more about JSON syntax in the JSON Module . Here is a Search Configuration sample code snippet for a one way synonym:

"synonyms": {  
  "oneWay": [
      "phrase": "office",
      "synonyms": [

Once you make a change, all you have to do is click Save, and you’ve created a new configuration version. This is important! Configuration versions allow you to test out your configuration changes, apply unique versions to a staging and production instance of your experience, and run version comparisons. You will learn more about versioning and version labels in the next unit.

unit Quiz
+20 points
Daily Quiz Streak Daily Quiz Streak: 0
Quiz Accuracy Streak Quiz Accuracy Streak: 0
    Error Success Question 1 of 4

    What properties are set in your Search Configuration? (Select all that apply)

    Error Success Question 2 of 4

    True or False: The Search Configuration leverages JavaScript syntax.

    Error Success Question 3 of 4

    When is a configuration version created?

    Error Success Question 4 of 4

    Where can you find the search configuration file?

    Climbing that leaderboard! 📈

    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