Configure Vertical Ranking

In the Overview of Algorithm and Indexing doc, you learned how the Search algorithm ranks verticals. This unit will walk through the different properties in the Search configuration you can set to influence the vertical ranking of your Search experience.

Namely, we will cover:

Semantic Vertical Intents: phrases associated with each vertical
Semantic Vertical Thresholds: minimum score requirement a vertical must meet to be returned at all in the universal search results
Semantic Thresholds: minimum score individual entity results must meet to be returned
Semantic Vertical Biases: adjustment to the final score of each vertical used to rank verticals against each other
(Optional) Semantic Vertical Ranking Priority Fields: select fields to prioritize when determining vertical ranking

Semantic Vertical Intents

One of the most direct ways you can control the vertical ranking of your Search experience is by defining semantic vertical intents for each of your verticals.

Vertical Intents are phrases that you want to associate with that vertical as a whole, like a synonym for the vertical. A good way to think about vertical intents is to ask yourself: if this intent was placed as a search query, would I want this vertical to always return first?

Vertical intents are used by the Search algorithm as one of the "clues" to evaluate the relevance of a vertical for a particular search query. If the search query is similar in meaning to a vertical intent, it is likely that vertical will appear first as a result.

Edit via the Platform UI

To configure vertical intents in the UI, navigate to the Verticals screen. Under the vertical intents column, add each phrase separately and delete phrases by clicking the 'x' icon next to them.

Edit via the JSON Editor

"verticals": {
  "resources": {
    "semanticVerticalIntents": [
      "sales resources",
      "sales sheet",
      "corporate pitch deck",
      "support deck"
    ]
  }
}

Semantic Vertical Thresholds

Semantic vertical thresholds are minimum score requirements that a vertical must meet in order to be returned at all in the universal search results. A vertical will always be returned in vertical search.

Thresholds are limited from 0 to 1 (inclusive) and can only include a single decimal point. They are set in the JSON of the Search configuration using the semanticVerticalThreshold property.

Choosing a Threshold

A useful way to think about vertical thresholds is how strict you want Search to be when deciding whether to return a vertical or not.

Setting a very high threshold (e.g., 0.7 or 0.8) indicates that you only want that vertical to return if there is an extremely high semantic match with the user's search query.

Without a threshold, a vertical will often be returned in Search if there is any keyword match with the user's search query whatsoever. This can be frustrating when working with verticals with a lot of content (e.g., long crawled documents, forum posts, etc.), where the probability of a random keyword match is high.

Therefore, setting a high threshold for these types of verticals can be a good way to restrict how often they return, so they only return when the algorithm thinks they are meaningfully related to the query.

On the other hand, setting a low threshold (e.g., 0.1 or 0.2) can be good practice in general across verticals, to ensure matches on keywords that are not actually semantically similar to the query are ignored.

Edit via the Platform UI

To configure vertical thresholds in the UI, navigate to the Verticals screen. Under the threshold column, enter the vertical threshold number in the text box or use the arrows to increment or decrement by 0.1.

Edit via the JSON Editor

"verticals": {
  "resources": {
    "semanticVerticalThreshold": 0.4
  }
}

Semantic Thresholds

Semantic thresholds specify the minimum semantic score individual entity results must meet to be returned for universal search and vertical search.

Note the difference between semantic vertical thresholds and semantic thresholds. Semantic thresholds determine whether individual results surface on either universal search or vertical search using those minimum scores respectively. On the other hand, semantic vertical thresholds determine whether a vertical shows up at all on universal search only. This means that as long as one result in the vertical meets the semantic vertical threshold, all results will surface in universal search. Semantic vertical thresholds does not affect vertical search.

Let's walk through some examples. Say semantic thresholds is 0.4 for both universal and vertical search and semantic vertical thresholds is 0.5. The vertical will only be returned on universal search if at least one entity is at least 0.5, and even then, only entities with semantic similarity of at least 0.4 will surface on either universal search or vertical search.

Say semantic thresholds is 0.5 for both universal and vertical search and semantic vertical thresholds is 0.4. The vertical will only be returned on universal search if at least one entity is at least 0.4, and even then, only entities with semantic similarity of at least 0.5 will surface on universal search, effectively setting the semantic vertical threshold to 0.5 as well.

Edit via the JSON Editor

Semantic thresholds can only be edited in the JSON editor:

"resources": {
  "semanticThresholds": {
    "results": {
      "minimumVerticalSearch": 0.4,
      "minimumUniversalSearch": 0.5
    }
  }
}

Semantic Vertical Biases

Semantic vertical biases are adjustments you can make to the final score of each vertical, which determine the rank in which they appear. Adding a positive bias will be added to the vertical score, and a negative bias will be subtracted.

Note: The semantic vertical threshold is enforced before the semantic vertical bias is applied. This means that if a vertical does not meet the threshold, even if there is a positive bias, the vertical will not be returned.

Note: The vertical score is calculated as (Best Semantic Similarity [base score]) + (Vertical Bias) = (Vertical Score [final score]). If the threshold is not met, there is a known bug in the UI. In this case the bias should be 0 and the base score should be the same as the final score. However, the UI incorrectly assumes the bias is applied and subtracts the bias from the final score to find the base score: (final score) - (bias) = (base score). The base score will thus inaccurately show as negative.

Biases are limited from -1 to 1 (inclusive) and can only include a single decimal point. They are set in the JSON of the Search configuration using the semanticVerticalBias property.

Choosing a Bias

Vertical biases can be used to nudge the Search algorithm into favoring one vertical over another. This can be useful, for example, if you have some verticals that are more authoritative or that you find are more useful than others.

For instance, say you have a support Search experience with one vertical featuring official published help articles, and another featuring forum posts. If there is a roughly equal match between help articles and forum posts, it is preferable for the user to go to the official published content, so you'll want to bias the algorithm towards returning the official content.

Determining the right bias for your verticals should be done iteratively; by placing searches, evaluating the ranking of verticals, and making adjustments to the biases until the ranking feels generally correct.

Edit via the Platform UI

To configure vertical ranking in the UI, navigate to the Verticals screen, choose the desired vertical, and find the Vertical Ranking section. Enter the vertical bias number in the text box or use the arrows to increment or decrement by 0.1.

Edit via the JSON Editor

"verticals": {
  "resources": {
    "semanticVerticalBias": 0.2
  }
}

Semantic Vertical Ranking Priority Fields

Semantic vertical ranking priority fields are a select list of the searchable fields that you want the algorithm to prioritize for a vertical when evaluating vertical ranking. As a more subtle way to impact vertical ranking, this is an advanced concept, and is not required to configure vertical ranking.

If two verticals are tied and have the same vertical score, the Search algorithm will use priority fields as a tiebreaker: looking at the top entities returned on each vertical, matches on priority fields are ranked above other matches.

The most common use of priority fields is to prioritize fields that are visible to the user on the Search Engine Results Page (SERP).

Say for example, you have an experience with two verticals: Product Categories and Locations. A user searches for "shoes", and the algorithm returns a Product Category with the name "Shoes", and a Location with a keyword "shoes".

The Product Categories vertical is obviously the better vertical to show first, because the shoes product category more directly addresses the user's query than a location that sells shoes. Therefore, we can add name as a priority field for the Product Categories vertical, to ensure it always appears above similar matches on keywords for Locations.

Priority fields are defined using the semanticVerticalRankingPriorityFields property in the Search configuration. Note that by default, name and builtin.entityType are set as priority fields for all verticals, as this is a pretty common use case. You'll only need to define priority fields if you are looking to override this default.

Edit via the JSON Editor

Vertical priority fields can only be edited in the JSON editor:

"verticals": {
  "resources": {
    "semanticVerticalRankingPriorityFields": [
      "name",
      "c_category"
    ]
  }
}

Edit via the Platform UI

To configure vertical ranking in the UI, navigate to the Verticals screen. For vertical intents, add each phrase separately and delete phrases by clicking the trash can icon next to them. For threshold and bias, enter the number in the text box or use the arrows to increment or decrement by 0.1.

Edit via the JSON Editor

Putting together all of the above vertical ranking properties, your resources vertical would look like the below in the configuration.

"verticals": {
  "restaurants": {
    "semanticThresholds": {
      "results": {
        "minimumVerticalSearch": 0.1,
        "minimumUniversalSearch": 0.5
      }
    },
    "semanticVerticalBias": 0.2,
    "semanticVerticalIntents": [
      "locations",
      "location"
    ],
    "semanticVerticalRankingPriorityFields": [
      "name"
    ],
    "semanticVerticalThreshold": 0.3
  }
}