English (United States) Čeština Deutsch Español (España) Français (France) Italiano 日本語

See more

Create and Manage a Search Configuration

Who does this article apply to?

  • Enterprise, Partner, and Small Business accounts.
  • Accounts in all regions.

The Search configuration (config) is the backend tool that allows you to configure business rules and search logic to define the scope of what the algorithms should return in your Search experience. The config is part of the Search backend — you are setting up the underlying data and business logic, not the display, colors, or branding. For frontend build options, see Ways to Build Search.

The prerequisite to building a Search configuration is having an underlying Knowledge Graph set up — entity types, entity relationships, and custom fields activated, and entity data loaded. Once your Knowledge Graph is ready, you can create and configure a Search experience.

Note: Some Search configuration features are only available via the JSON editor. These are called out in training and in the Search Config Properties docs.

What the Configuration Controls

Within the Search configuration, you define verticals, control which entities flow into the experience, determine how entities are sorted and ranked, set up filters, create synonyms, and more.

Verticals: Define each type of content you want to search on and the specific settings for that class of content. Define what entities the vertical can include by choosing entity types and setting saved filters. Set what fields are searchable, how results are sorted within the vertical, and how the vertical ranks against others.

verticals-overview.png

Query Suggestions: Define the hardcoded prompts that appear when a user clicks into the search bar, as well as the popular queries that appear as the user types.

query-suggestions-overview.png

Synonyms: Set words and terms that mean the same thing for your business. Search terms that have synonyms defined will pull in results for those synonyms as well.

synonyms.png

Query Rules: Set business rules to specify customized logic when you want to surface results that stray from what the algorithm and configuration return by default.

query-rules.png

General Settings: Set the countries your location search should run on, terms you don't want to search on, and words that should be searched as one phrase.

general-settings.png

Create a Search Configuration

  1. Click Search in the navigation bar and click All Search Experiences.
  2. Click Add Experience in the top right. This will open the setup wizard.

  3. Enter the Experience Name and Experience Key.

    • Experience Name — used for internal identification only.
    • Experience Key — used as part of the API call when you apply the configuration to your frontend build. This is filled in automatically as you type the experience name, but you can edit it.

    Note: You can always change the name later, but the key is harder to change.

  4. Click Save.

Once created, you'll land on the Verticals configuration screen with a blank configuration. Verticals are the first thing you need to add to have something to search on.

From the All Search Experiences screen, you can:

  • Click View Experience to access a configuration.
  • Click Add Experience to add another experience to the account.
  • Click the dropdown next to an experience to Duplicate Experience or Delete Experience.

experiences-default.png

Edit a Search Configuration

Once you click into an experience, edit the config by clicking into any screen under the Configuration section. The UI and JSON editor always mirror each other and stay in sync. Always save your edits before toggling between the UI and JSON formats, or between different configuration screens.

Edit via the Platform UI

  1. Click on the desired screen under Configuration.
  2. Make your edits.
  3. Click Save at the bottom of the screen.

The process is interactive — you'll typically find yourself editing, scrolling, and saving. Save before navigating to a different configuration screen.

For example, on the Synonyms screen, you'll find modules for each type of synonym with descriptions. Click + Add next to the type you want to add, fill in the required fields, and save when ready.

synonyms-default.png

Edit via the JSON Editor

  1. Click Edit as JSON in the navigation bar. A full code editor appears.
  2. Make your edits. Find syntax for configuration properties in the Search Config Properties docs. You can also add a property via the UI first, then copy its syntax as a starting point.
  3. Click Save.

edit-as-json.png

Duplicate a Search Configuration

Duplicating creates a new Search configuration with your current settings so you don't have to build from scratch.

  1. Click Search in the navigation bar and click All Search Experiences.
  2. Click the dropdown arrow next to the experience you want to duplicate and select Duplicate.
  3. Enter the Experience Name and Experience Key for the new experience.
  4. Click Save.

Revision History and Configuration Labels

The Revision History screen under the Deployment section shows a log of all configuration versions you have saved. Every successful save — whether via UI or JSON — creates a new version. Use this screen to publish a tested version to production or revert to a previous version.

revision history screen

Configuration Labels

Each Search config has a latest and a production configuration label by default, which align with the staging and production instances of your frontend site:

  • The staging instance of your frontend is powered by the latest configuration label.
  • The production instance of your frontend is powered by the production configuration label.

Best practice: Keep the latest label pinned to the most recent version so you can always test the latest changes on staging. Once you've thoroughly tested a version and are ready to go live, open the dropdown next to that version and click Publish to Production.

You can only edit the latest version of the config. To reference an older version, click View JSON next to the version number for a read-only view. To use a previous version as your staging starting point, click Restore to Latest.

Configuration Versions in Test Search

Test Search allows you to run and compare queries by configuration label (Latest or Production). Use the dropdown within Test Search to toggle between labels, then run your search.

Languages and Locales

A search experience will only return entities whose locales match the locales specified in the search config using the top-level property supportedLocales. See the Search Config Properties - Top Level doc for details.

If you are building a non-English experience or an experience with multiple languages or locales, see the Multi-Language Experiences documentation.