Searchable and Display Fields | Yext Hitchhikers Platform
What You’ll Learn
By the end of this unit, you will be able to:
- Define searchable fields and list the two components that are needed to set them up
- Recall common use cases for when to use each searchable field type
- Configure searchable fields, including for entity relationships, and display fields
Now that you’ve defined your verticals at a high level, including the name and entity types it should include, we’ll dive into configuring what is returned. The first step is to specify which fields can be searched by the Search backend for each vertical. This is what’s called a searchable field. In this unit we’ll go into more detail about what searchable fields are and how to configure them.
Intro to Searchable Fields
In the Search config, you’ll define which fields are indexed (or searched) by the Search algorithm in each vertical. These searchable fields then affect which results are returned to the user. For example, if you want users to be able to find restaurants that are near them, you’ll want to make the entity location searchable in the Restaurants vertical.
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.
The first thing you’ll need when configuring searchable fields is to specify the fields you want to search. For each vertical, you can pick from the fields available in the Content for the relevant entity type(s) (or and populate them if the content doesn’t yet exist in the platform). Each entity type that you set up in the platform has both built-in (profile) and custom fields associated to it. Both can be marked as searchable.
In the JSON instance of the Search configuration, fields are referenced by their API name (check out the
help article to learn how to find this). These API names are also listed under the field name in the Searchable Fields section when editing via the UI. Any custom fields will have a prefix of
c_ and any built-in fields will not.
In the case of a restaurant chain, a location may be limited to only showing menu items with multi-option select or text-type fields (and any data changes would need to be made manually within the field). However, relating or linking Menu Item entities to Restaurant entities allows customers to see other relevant information about dietary restrictions or ingredients of specific menu items to help them choose a location that best serves their needs.
When referencing data from linked entities in Search, use dot notation (
.) like so:
In the example above, you may add a relationship field on Restaurant entities that links to Menu Items. To return the name of menu items sold at a specific location, use something like this:
You can even use fields from a linked entity of a linked entity, or a multi-hop relationship. For example, in a Doctors vertical, you could link conditions to a specialty that is also linked to a doctor. This would allow patients to search for conditions and get results for Doctors that treat them even though those entity types aren’t directly related.
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. Use dot notation for every linked entity relationship.
Choosing the Algorithm Applied
When you set fields as searchable for each vertical, you’ll have the option to choose how you want that field searched. We have a list of preset searchable field types that are recognized by the algorithm that you can find in the reference doc. Each searchable field type triggers a different algorithm and will search the content in the field it’s turned on for in a different way.
- Phrase Match (
- Text Search (
- Semantic Text Search (
- NLP Filter (
- Document Search (
- Facet (
- Sortable (
For example, the NLP Filter searchable field type filters for the best exact match and is thus very restrictive. Text Search, on the other hand, looks for keyword matches in the content and is more flexible. Semantic Text Search adds some natural language processing to understand the user’s intent beyond just matching on keywords.
When choosing which searchable field types to use, you’ll need to decide which one best fits the contents of the field and the purpose of making that field searchable. For best practices on how to approach choosing searchable field types, check out the reference doc.
There are four searchable fields in the Events vertical we set up:
- NLP Filter on the Entity Type (
- NLP Filter on the Location (
- Phrase Match on the Keywords field (
- Semantic Text Search on the Name field (
Let’s break this down:
NLP Filters create a black and white filter with the best exact match. The NLP Filter on entity type will return the Events entity type for search queries that contain “events.” This is a built-in value you can use with NLP filters only.
The NLP Filter on location is another special case that enables location search on entity types with an address. This will return results for searches on “near me”, addresses, zip codes, cities, and other parts of the address based on proximity to the users’ location (rather than matching on the exact terms in the search query).
Phrase match allows an entity to be surfaced only when there is an exact match on the phrase in the query. This is good for keywords which are more free form and can include generic words that may match to content easily. This way, the keywords only get triggered if there is an exact match. For example, you may have an event with the keyword “taco Tuesday” and another with the keyword “taco Thursday.” You want to only surface the event if the whole keyword is queried, so you use phrase match. This will prevent both events from surfacing if the search is just “taco.”
Semantic Text Search matches a query that is close in meaning, so it doesn’t have to be an exact match. In general, name fields (except on location entity types) are a good use case to use semantic text search because users are likely to search for terms close in meaning without knowing the actual name. For example, you may have an event called “Steak Night.” You’ll likely want this event to surface for the query “beef burritos” as “steak” and “beef” are semantically similar.
Edit Searchable Fields
Edit via the Platform UI
To configure searchable fields in the UI, navigate to the Verticals screen, choose the desired vertical, and then find the Searchable Fields section at the top. Add a field in the top right of this section to enable another field for Search indexing. Once you select the field, you can designate which searchable field type to apply to the given field.
In the example FAQs vertical below, we’ve set up the following searchable fields:
- Phrase Match on Keywords
- Semantic Text Search on Name
Edit via the JSON Editor
In the JSON instance of the Search configuration, fields are referenced by their API name (check out the help article to learn how to find this). To set a field as searchable, specify the API Name of the field you are setting along with the searchable field type(s) you’d like to use. Find more details on each searchable field type in the reference doc.
The JSON for the same FAQs vertical searchable fields configuration above would look like the following:
While you’re thinking about which fields to pass from your Content 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, you can use the
displayFields property to specify the entity profile fields that are returned as part of the Search API response. If you do include the
displayFields property, Search will only return the fields that 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 front end of that vertical, including from related entities as well as the base entities.
It is highly recommended that you configure display fields because only returning the content you need in the API response will ensure the Search API is as fast as can be. While this property doesn’t affect your backend and how results are returned, you’ll need to use it to get content to the frontend.
Let’s say, for example, that you are working on a doctors vertical, and each doctor is related to a specialty entity that has the name of that specialty and a list of related conditions and treatments. Here is an example of a
displayFields property that you might set up to display all of those attributes: