Add Searchable and Display Fields to a Search Vertical

Within each vertical, you will determine which fields can be searched on the Search backend by configuring Searchable Fields. Searchable Fields specify which Knowledge Graph fields are indexed by the Search algorithm in each vertical, and how. This determines which results are returned to the user.

Make sure to designate at least one searchable field for each vertical — otherwise, the Search algorithm will have nothing to search on and no results will be returned.

When defining a searchable field, you need to specify two things: the field and the algorithm.

Choosing the Algorithm Applied

Advanced Search Tier Features: Semantic search, inferred filters (except on builtin.location), and document search are only available on the Advanced Search tier. Check out the Search Tiers reference doc to learn more.

Think about what type of data you're searching on: structured, semi-structured, or unstructured. Each algorithm searches the content of a field in a different way.

When multiple fields have Keyword Search or Document Search enabled, you can add field-level weighting to assign boosts to fields. There are also special inferred filter use cases to allow you to search on location, entity type, and hours.

For best practices on choosing search algorithms, see the Searchable Fields Best Practices reference doc. For full property details, see the Search Config - Verticals reference doc.

Legacy Searchable Field Types

While technically considered filters and sorting — not searchable fields — the following were previously defined as searchable field types. In the updated config UI, you'll find them in the appropriate sections. If editing via the JSON editor, enable these in the searchableFields object.

• Facet (facet): allows a field to be used as a dynamic filter users can interact with to narrow their search; best for structured enum/option fields with a finite number of variations. Learn more in the Facets and Filters unit.
• Static Filter (staticFilter): viewable "pre-search" and not dependent on the search query. Learn more in the Facets and Filters unit.
• Sortable (sortable): allows a field to be used as a sorting method controlled by the algorithm or by the user. (Fields added to sorting via the UI are configured as sortable automatically. Fields added via the JSON editor must be marked as sortable.) Learn more in the Sorting unit.

Defining Fields

For each vertical, you can pick from the fields available in the Knowledge Graph for the relevant entity type(s). Both built-in (profile) and custom fields can be marked as searchable.

In the JSON editor, fields are referenced by their API name. See the View Field API Name help article to find API names. These API names also appear under the field name when adding fields in the UI. Custom fields have a prefix of c_; built-in fields do not.

Entity Relationships

You can use linked entities as searchable fields to search for content on entities related to the ones you want to return in results.

When referencing data from linked entities in Search, use dot notation:

[[customRelationshipFieldID]].[[fieldName]]

For example, to return the name of menu items sold at a restaurant location:

c_relatedMenuItems.name

You can also use multi-hop relationships — fields from a linked entity of a linked entity. For example, in a Doctors vertical, you could link conditions to a specialty that is also linked to a doctor, allowing patients to search for conditions and get results for doctors that treat them.

Note: In the Search config UI, you can only add the name field of related entities. To add other fields or multi-hop relationships, use the JSON editor.

{
  "verticals": {
    "ce_doctors": {
      "searchableFields": {
        "c_relatedSpecialties.c_relatedCondition.name": {
          "nlpFilter": true
        }
      }
    }
  }
}

Events Example

There are four searchable fields in the Events vertical:

• Inferred Filter on the Entity Type (builtin.entityType)
• Inferred Filter on the Location (builtin.location)
• Phrase Match on the Keywords field (keywords)
• Semantic Search on the Name field (name)

Inferred Filter on entity type — returns the Events entity type for search queries that contain "events." This is a built-in value you can use with inferred filters only.

Inferred Filter on location — enables location search on entity types with an address. Returns results for searches on "near me," addresses, zip codes, cities, and other address parts based on proximity to the user's location (rather than matching on exact terms in the query).

Phrase Match on keywords — surfaces an entity only when there is an exact match on the phrase in the query. For example, if you have an event with keyword "taco Tuesday" and another with "taco Thursday," phrase match prevents both from surfacing for a query of just "taco."

Semantic Search on name — matches a query that is close in meaning, not just an exact match. For example, an event called "Steak Night" should surface for the query "beef burritos" since "steak" and "beef" are semantically similar.

Add Searchable Fields

Edit via the Platform UI

1. Click Search in the navigation bar and click on the desired Search experience. You'll land on the Verticals screen.
2. Select the vertical you want to add searchable fields to.
3. On the Search Algorithms or Filters tab, find the relevant searchable field type you want to add.
4. Click + Add / Update Fields. A dialog box appears.
5. Select the checkbox next to the fields you would like to add and uncheck any fields you want to remove. Click Update.
6. Click Save.

Note: Inferred filters are found on the Filters tab, not the Search Algorithms tab.

In the example FAQs vertical below, the following searchable fields are configured:

• Keyword Search on Keywords
• Semantic Search on Question

Edit via the JSON Editor

1. Click Search in the navigation bar and click on the desired Search experience.
2. Click Edit as JSON to open your Search configuration file.
3. Specify the API name of the field along with the searchable field options you'd like to set.

The JSON for the FAQs vertical above:

"verticals": {
  "faqs": {
    "searchableFields": {
      "keywords": {
        "textSearch": true
      },
      "question": {
        "semanticTextSearch": true
      }
    },
    "sortBys": [],
    "source": "YEXT"
  }
}

Another example with multiple field types:

"community_stories": {
  "entityTypes": [
    "ce_communityStory"
  ],
  "name": "Community Stories",
  "searchableFields": {
    "builtin.entityType": {
      "nlpFilter": true,
      "textSearch": false
    },
    "c_theme": {
      "facet": true,
      "nlpFilter": true
    },
    "name": {
      "nlpFilter": false,
      "phraseMatch": false,
      "textSearch": true
    }
  }
}

For full property details see the Search Config - Verticals reference doc.

Display Fields

While you're thinking about which fields to pass from your Knowledge Graph to your Search backend, you'll also want to think about which ones to pass to your Search frontend. You can only display fields on the frontend if they are passed to the frontend by the backend via the Search API response.

By default, the Search API response returns all fields on the result entity, but not any fields of related entities. If you want to display fields from related entities, add display fields to specify the entity profile fields returned as part of the Search API response. If you do include display fields, Search will only return the fields you provide in this property — even if they are on the result entity — so you will need to add all fields you want to display on the frontend of that vertical, including from related entities as well as the base entities.

It is highly recommended to configure display fields because only returning the content you need will ensure the Search API is as fast as possible. While this property doesn't affect which results are returned from the backend, you'll need it to get content to the frontend.

Be precise when specifying display fields, particularly for linked entities. If there is a particular subfield you need, specify that subfield exactly instead of the parent field. For example, to display a doctor's specialties, add c_relatedSpecialties.name to display fields, not c_relatedSpecialties.

Note: You can't include both the top-level field and subfields of that parent field in the same display fields list. For example, you can't have both c_relatedSpecialties and c_relatedSpecialties.name.

Note that Search API responses return all display fields that ever existed on any version of the experience. For example, if version 45 had the "description" field as a display field but the most recent version 49 does not, the Search API response would still return "description."

Edit via the Platform UI

1. Navigate to the Verticals screen and choose the desired vertical.
2. Select the Display Fields tab.
3. Click + Add / Update Fields to bring up a field modal and check off the fields you want to include. Uncheck any fields you want to remove, or click the trash can icon next to the field.

Edit via the JSON Editor

The JSON for a doctors vertical with display fields for specialties, conditions, and treatments:

"verticals": {
  "doctors": {
    "displayFields": [
      "name",
      "c_specialty.name",
      "c_specialty.c_relatedConditions.name",
      "c_specialty.c_relatedTreatments.name"
    ]
  }
}

See the Search Config - Verticals reference doc for more.

Searchable Fields Best Practices

To make the most of your search configuration, it is crucial to ensure that you are using the appropriate search algorithm for each field you make searchable. The following is a list of tips for setting up your searchable fields.

Note: If you are using Search for healthcare, find industry-specific guidance in the Set Up Your Search Configuration for Healthcare guide.

Tips by Search Algorithm

Keyword Search

Keyword Search is the simplest way to search a field. Search will simply look for the tokens in the query in fields set up with keyword search. Keyword search works best for short text fields with relatively unstructured data.

Example: Jobs vertical, Name field

The tokens from the query "application for partner roles" are "application," "partner," and "role." This can return jobs with the names:

• Partner Engineer
• Partner Engineer, New Grad
• Technical Partner Manager
• Associate Technical Partner Manager

It's not immediately clear which exact role the user is looking for, and since these job names are varied, unstructured data with infinite values that are similar to each other, keyword search would be the best choice.

Use Keyword Search for:

• keywords when these are just related to the entity and may not be searched exactly. Use phrase match with more specific keywords when possible, but if the data quality is not certain, use keyword search.

Keyword Search tips:

• If the field contains the full name of a person like "John Doe," phrase match will provide better exact matches for "John Doe" rather than keyword search results for both "John" and "Doe."
• Fields with similar and overlapping content should use keyword search rather than an inferred filter, which is more restrictive. For example, if a retail bank had both "Student Checking Accounts" and "Checking Accounts" as products, use keyword search to surface both. An inferred filter would filter down to the one best match, and phrase match would be too exact.
• Keyword search should almost never be used on long-form text fields like description. This will produce irrelevant results because of the high likelihood of random keyword matches with long text.
• If multiple fields with Keyword Search or Document Search enabled may have similar content, use field-level weighting to assign boosts to prioritize matches. See Field-Level Weighting for Keyword and Document Search for more information.

Semantic Search

Advanced Search Tier Feature: Semantic search is only available on the Advanced Search tier. Check out the Search Tiers reference doc for details.

Semantic Search works by matching a user's query to anything that is semantically similar (think "beef," "steak," and "cheeseburger" — these three terms have a similar meaning).

Example: FAQs vertical, Question field

A query for "send back my food" would surface the FAQ "Can I return my order?" because they are semantically similar. Keyword search would not return this result because the words themselves are not a match.

Use Semantic Search for:

• name of entities where a user may not search for the exact terms, but is likely to search for something semantically similar (e.g., "shrimp" may be on a restaurant's menu, but users could also search for "prawns").

Semantic Search tips:

• Semantic search is ONLY available for entity names, and is not available for the locations vertical.
• Semantic Search should not be used for names of proper nouns, as semantic similarity does not apply here.

Phrase Match

Phrase Match allows an entity to be surfaced only when there is an exact phrase match contained in the query. It works best for text fields where you want the query to exactly match the content of the field.

Example: FAQs vertical, Keywords field

If the FAQ "Do you offer any special menus?" has the keyword "happy hour," you only want to return this FAQ when users search for the entire phrase "happy hour" — not when they query "what are your hours?" Phrase match works best here.

Use Phrase Match for:

• name of a person (e.g., "John Doe") to only return exact matches for "John Doe" instead of returning all results for "John" and "Doe" separately.
• keywords when these may actually be key phrases that should be searched exactly (e.g., if you want "Mortgage Loan Officers" to only return results for "Mortgage Loan Officers" and not results for "mortgage," "loan," and "officers" separately).

Phrase Match tips:

• Make sure keywords added to entities represent the entity and are not just related to the entity. Think of keywords as synonyms for the entity — setting keywords that are too broad will result in bad matches. For example, if you set "mortgage" as a keyword for a mortgage officer entity, that officer will return when the user searches "mortgage rates," which should not return officers.

Inferred Filter

Advanced Search Tier Feature: Inferred filtering, except on builtin.location, is only available on the Advanced Search tier. Check out the Search Tiers doc for details.

Inferred Filter is best for structured fields for which there are a finite number of options, such as department or builtin.entityType. It infers a specific filter and applies it to the search, making it a black and white, much stricter filter than any other search algorithm.

Example: Jobs vertical, Job Department field (single option select with options for Revenue, Technology, Delivery, etc.)

A query for "open technology jobs" will filter to only jobs with "Technology" populated in the Job Department field. Since this field is structured with a finite number of value options, inferred filter works best.

Use Inferred Filter for:

• Fields that represent a specific category or label for an entity (e.g., filter products down to "Men's Shoes").
• builtin.entityType for every vertical to surface those entities when a user searches for the name of the entity type. For example, searching "FAQs" would apply an inferred filter for the FAQs entity type, boosting that vertical to the top of results.
• builtin.hours for any entity type you want to filter to options that are "open now."
• builtin.location for any entity type with an address that can be searched by location (e.g., locations, professionals, jobs).
• address.region (or other address field) for an entity type with an address where users are expected to search for specific cities or other address parts. This creates a more restrictive location filter.

Inferred Filter tips:

• Inferred Filters will exclude results that do not fall under that category.
• Inferred Filters use the exact content of the field, so be careful of duplicative categories like "Men's Shoes" and "Men's Shoe." The algorithm will choose the best match and exclude results for the other.
• Inferred Filters are available in Experience Training, so you can easily improve your search experience by accepting and rejecting filters.
• If you are using multiple inferred filters, you can add nlpFilterOrder to your config to set prioritization. 

Document Search

Advanced Search Tier Feature: Document search is only available on the Advanced Search tier. Check out the Search Tiers doc for details.

Document Search works by matching query intent to long-form, unstructured text to find the most relevant snippet within the document.

Example: Help articles vertical, Body field

The query "What does Yext do?" is answered in a help article. Document search returns the most relevant help article by searching the long-form content and provides the most relevant snippet as a featured snippet.

Use Document Search for:

• description and body fields with long, unstructured content (e.g., help articles, product descriptions, and file search).

Document Search tips:

• Document Search works well with extractive QA to surface direct answers. For more information, see Direct Answers.
• Check out limitations of file search in the File Search doc.
• If multiple fields with Keyword Search or Document Search enabled may have similar content, use field-level weighting to assign boosts to prioritize matches. See Field-Level Weighting for Keyword and Document Search for more information.

Facets

Facets allow a field to be used as a dynamic filter that a user can interact with in the frontend to narrow their search. This is best for structured enum/option fields with a finite number of options.

Example: Jobs vertical, Job Department field

Fields that work well with inferred filters are typically good for facets as well. Facets will also need to be set up on the frontend — see the Facets and Filters (Frontend Theme) unit for more detail.

Use Facets for:

• Structured enum/option fields with a finite number of options.
• Fields whose filter you want a user to be able to toggle on the frontend.
• Fields that are good candidates for an inferred filter are typically good candidates for facets as well. These work well together because when an inferred filter is detected, the corresponding facet will show up as checked.

Facets tips:

• Facets use the exact content of the field, so be careful of duplicative categories like "Men's Shoes" and "Men's Shoe" — these will both show as options. Consolidate these into one category.
• Setting too many searchable fields as facets may be overwhelming to a user. Defer to the fields most likely to help a user narrow down results.
• Facets with lots of options can be made searchable. For instructions, see the Facets and Filters (Frontend Theme) doc.
• Place the most general, high-level filter categories at the top and more specific ones at the bottom. For instructions on setting facet order, see the Facets and Filters (Backend) doc.

Multiple Search Algorithms on the Same Field

Only use multiple search algorithms for the same field if it's deliberate, or else it could cloud which algorithms are being applied.

• Inferred Filters override other searchable fields because of their strict nature to filter down to only the one best match.
• People names is an example of a deliberate use of multiple algorithms. Use both Phrase Match and Keyword Search. Results will display phrase match results first, then keyword search. For example, if the search query is "John Doe," phrase match returns all exact matches for "John Doe," and keyword search returns any matches for "John" and any for "Doe." Since a match to "John Doe" is stronger than "John" or "Doe" alone, the phrase match results appear above the keyword search results.

Tips by Vertical

The following are guidelines for setting searchable fields by vertical type. These examples are meant to give you a starting point for your own Search experiences. Your specific use case may lead you to diverge from these guidelines.

Advanced Search Tier Features: Semantic search and inferred filtering (except on builtin.location) are only available on the Advanced Search tier. Check out the Search Tiers doc for details.

Locations

• Add keyword search to name. Note: if all location entities have the same or similar names, using name as a searchable field is not recommended.
• Add an inferred filter to builtin.location.
• If you want to filter results to a specific zip code, city, or state, set the field (e.g., address.city) as an inferred filter.
• If using multiple inferred filters, add nlpFilterOrder to set prioritization. 
• Add an inferred filter to builtin.entityType.
• Add phrase match to keywords.
• If your locations fall into multiple categories (e.g., hospitals and outpatient centers), consider adding the corresponding category field as a facet and an inferred filter.

FAQs

• Add semantic search to name.
• Add phrase match to keywords.
• Add an inferred filter to builtin.entityType.
• If your FAQs fall into multiple categories (e.g., account, order status), consider adding a category field as a facet and an inferred filter.

Products

• Add semantic search to name.
• Add phrase match to keywords.
• Add an inferred filter to builtin.entityType.
• If your products have features that fall under multiple but finite categories (e.g., brands, colors, parent products, stock statuses), consider adding those feature fields as an inferred filter and a facet.

Professionals

• Add keyword search and phrase match to name (name, first name, and last name).
• Add phrase match to keywords.
• Add an inferred filter to builtin.entityType.
• If professionals speak different languages, add an inferred filter and a facet to language.
• If professionals have associated addresses, add an inferred filter to builtin.location.
• For healthcare accounts, consider adding an inferred filter and facet to insurance accepted.
• If professionals are associated with specific locations in the Knowledge Graph, consider adding phrase match and keyword search to related locations.

Jobs

• Add semantic keyword search to name.
• Add phrase match to keywords.
• Add an inferred filter to builtin.entityType.
• Add an inferred filter to builtin.location.
• If applicable, add keyword search to department and hiring organization (or, if the options are limited, consider these as inferred filter and facet).
• Add an inferred filter to employment type.