Relewise Documentation

Appearance

Search Highlight ​

The Search Highlight feature is used to return data that allows you to create a UI element capable of displaying how a search term has matched with a product or content entity. This is useful for creating a rarified search experience where users are shown how their search query has interfaced with the results they are being shown.

Example of search highlighting in action

Search Highlight Settings ​

The Search Highlight feature itself is utilized by enabling it as part of your search query. When performing a search query towards either the ProductSearchRequest or ContentSearchRequest endpoints, you will have the option of toggling the setting Highlight to true. From here, you will have several options for specifying how you want your output to look. These settings are used to specify how many snippets you want returned per entity, how many snippets you want returned per data field on an entity, and what shape the snippet should take.

The search highlight settings include:

  • MaxEntryLimit
  • MaxSnippetsPerEntry
  • MaxSnippetsPerField
  • MaxWordsBeforeMatch
  • MaxWordsAfterMatch
  • MaxSentencesToIncludeBeforeMatch
  • MaxSentencesToIncludeAfterMatch
Click here to see an example of Highlight Settings
json
{
  "$type": "Relewise.Client.Requests.Shared.Highlighting.HighlightSettings, Relewise.Client",
  "MaxSnippetsPerEntry": 5,
  "MaxSnippetsPerField": 3,
  "MaxWordsBeforeMatch": 5,
  "MaxWordsAfterMatch": 5,
  "MaxSentencesToIncludeBeforeMatch": 0,
  "MaxSentencesToIncludeAfterMatch": 0
}

MaxEntryLimit ​

This determines how many search results should be evaluated for search highlight purposes. This cannot exceed the take value of the search request. The entries are selected "in order", that is, according to the sort order that they are returned in the search.

MaxSnippetsPerEntry ​

This determines how many snippets should be returned per entry. This amount is divided across the individual fields, and is spent "in order"; that is, if the MaxSnippetsPerEntry is set to 2, and the term would match on the DisplayName twice, and the Description field once, then the search highlight will return only the two matches for DisplayName, and as it has now "used up" its maximum allowed amount of snippets, return none for the Description field.

MaxSnippetsPerField ​

This determines how many snippets may be matched per field on an entry. This can alleviate the issue of matching too many times on one field, by limiting it to just a handful of matches and thus "saving" the MaxSnippetsPerEntry amount for other fields.

MaxWordsBeforeMatch ​

This determines how many words should be returned before the matching word in a snippet.

Usecase example

Consider the sentence:

This dog house is best suited for small dogs.

In a search query for house, with MaxWordsBeforeMatch = 3, the output would be:

rain. This dog house

MaxWordsAfterMatch ​

This determines how many words should be returned after the matching word in a snippet.

Usecase example

Consider the sentence:

This dog house is best suited for small dogs.

In a search query for house, with MaxWordsAfterMatch = 3, the output would be:

house is best suited

MaxSentencesToIncludeBeforeMatch ​

This determines how many sentences should be returned before the matching word in a snippet. This is contingent on the value of the MaxWordsBeforeMatch value: If the value of the MaxWords setting is less than the total amount of words needed to encompas the entirety of the amount of sentences you want returned with MaxSentencesToIncludeBeforeMatch, the query will only return the amount of sentences that can be contained within the alloted word count.

The relationship between MaxSentencesToIncludeBeforeMatch and MaxWordsBeforeMatch thus requires that the word count value be considerably high, to account for the length of full sentences.

Usecase example

Consider the paragraph:

This product is made from combined wood and stained to withstand weather. A slanted roof protects from rain. This dog house is best suited for small dogs. Available in black, red, or white. Consider buying this product today.

In a search query for house with:

  • MaxSentencesToIncludeBeforeMatch = 1, and
  • MaxWordsBeforeMatch = 50

the output would be:

A slanted roof protects from rain. This dog house

MaxSentencesToIncludeAfterMatch ​

This determines how many sentences should be returned after the matching word in a snippet. This is contingent on the value of the MaxWordsAfterMatch value:If the value of the MaxWords setting is less than the total amount of words needed to encompas the entirety of the amount of sentences you want returned with MaxSentencesToIncludeAfterMatch, the query will only return the amount of sentences that can be contained within the alloted word count.

The relationship between MaxSentencesToIncludeAfterMatch and MaxWordsAfterMatch thus requires that the word count value be considerably high, to account for the length of full sentences.

Usecase example

Consider the paragraph:

This product is made from combined wood and stained to withstand weather. A slanted roof protects from rain. This dog house is best suited for small dogs. Available in black, red, or white. Consider buying this product today.

In a search query for house with:

  • MaxSentencesToIncludeAfterMatch = 1, and
  • MaxWordsBeforeMatch = 50

the output would be:

house is best suited for small dogs. Available in black, red, or white.

Highlight Props ​

The Highlight setting requires you to specify what datakeys or datafields should be used for the highlighting. These datakeys will need to be specified manually, as the request does not inherit any data from the search index. Inclusion of an entity's DisplayName is set as a true/false boolean, while other datakeys will need to be specified as a list in the request.

Click here to see an example of Highlight Props
json
{
  "$type": "Relewise.Client.Requests.Shared.Highlighting.ProductHighlightProps, Relewise.Client",
  "DisplayName": true,
  "DataKeys": [
    "Description",
    "ShortDescription"
  ]
}

Shape ​

The shape of the highlight dictates how the data returned by the feature should be presented. There are two options, Offset and Snippets.

Snippet ​

A Snippet presents the results as a string of text, which contains both the search term itself, as well as the text surrounding it. By configuring the snippet settings (see above), you can specify how many words or sentences should be retrieved before and after the search term match, which helps to create a context for the search result itself.

UseEllipses ​

This toggles whether to use ellipses (...) in the response. The use of ellipses is a stylistic choice, which can help describe at a glance if the snippet is part of a larger context or not.

The UseEllipses setting is a true/false flag, and if toggled on, will inherit its settings from the "words before/after match" values outlined above.

Usecase example

Consider the sentence:

This dog house is best suited for small dogs.

In a search query for house, with WordsBeforeMatch = 1 and WordsAfterMatch = 1, with Ellipses set to true, the results would be:

...dog house is...

IncludeMatchedWords ​

This setting specifies that the request should return an offset value for the returned snippet, highlighting where exactly the matching word is located within the snippet.

This offset value is different from the Offset shape described below, because it describes the position of the matches search term within the snippet, as opposed to within the entire datakey.

Usecase example

Consider the sentence:

This dog house is best suited for small dogs.

In a search query for house, with WordsBeforeMatch = 1 and WordsAfterMatch = 1, with IncludeMatchedWords set to true, the results would be:

json
"Snippets": {
    "DisplayName": [],
    "Data": [
      {
        "Key": "Description",
        "Value": [
          {
            "Text": "...dog house is...",
            "MatchedWords": [
              {
                "Offset": {
                  "LowerBoundInclusive": 7,
                  "UpperBoundInclusive": 12
                }
              }
            ]
          }
        ]
      }
    ]
  }

Offset ​

An Offset is a numeric representation of where in the datakey the search term has been found. Toggling Offset to true will return the intervals at which the search term has been matched within each datakey.

Specifically, this means that the Search Highlight will return a numeric match for where the start of the term has been found in the string, and where the end of the string has been found. These are described as the Upper- and LowerBoundInclusive values.

Usecase example

Consider the sentence

This product is made from combined wood and stained to withstand weather. A slanted roof protects from rain. This dog house is best suited for small dogs. Available in black, red, or white. Consider buying this product today.

In a search query for house, an Offset result would look look like this:

json
"Offsets": {
    "DisplayName": [],
    "Data": [
      {
        "Key": "Description",
        "Value": [
          {
            "LowerBoundInclusive": 118,
            "UpperBoundInclusive": 123
          }
        ]
      }
    ]
  },

Search Hightlighting Example ​

For the example below, Search Highlighting has been activated for a product search query for the search term house.

We return a match for one product, productID p-2. This product has a Description datakey containing the string:

This product is made from combined wood and stained to withstand weather. A slanted roof protects from rain. This dog house is best suited for small dogs. Available in black, red, or white. Consider buying this product today.

Below is outlined the search highlight part of the search query, and the search highlight result being returned for the p-2 product.

For the purpose of demonstration, we request both Shape types with as much data as we can get. We specify the Highlightable Props to be both DisplayName and Description.

Search Highlight request example
json
{
  "$type": "Relewise.Client.Requests.Search.Settings.ProductSearchSettings+HighlightSettings, Relewise.Client",
  "Enabled": true,
  "Limit": {
    "MaxEntryLimit": 5,
    "MaxSnippetsPerEntry": 5,
    "MaxSnippetsPerField": 3,
    "MaxWordsBeforeMatch": 5,
    "MaxWordsAfterMatch": 5,
    "MaxSentencesToIncludeBeforeMatch": 1,
    "MaxSentencesToIncludeAfterMatch": 1
  },
  "Highlightable": {
    "DisplayName": true,
    "DataKeys": [
      "Description"
    ]
  },
  "Shape": {
    "Offsets": {
      "Include": true
    },
    "Snippets": {
      "Include": true,
      "UseEllipses": true,
      "IncludeMatchedWords": true
    }
  }
}
json
{
  "$type": "Relewise.Client.DataTypes.HighlightResult, Relewise.Client",
  "Offsets": {
    "DisplayName": [],
    "Data": [
      {
        "Key": "Description",
        "Value": [
          {
            "LowerBoundInclusive": 118,
            "UpperBoundInclusive": 123
          }
        ]
      }
    ]
  },
  "Snippets": {
    "DisplayName": [],
    "Data": [
      {
        "Key": "Description",
        "Value": [
          {
            "Text": "...protects from rain. This dog house is best suited for small...",
            "MatchedWords": [
              {
                "Offset": {
                  "LowerBoundInclusive": 32,
                  "UpperBoundInclusive": 37
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Don't know us? Don't worry - you can find more information about us, by visiting our main page www.relewise.com

ContactChangelogsCookies, Privacy & TermsAPI Reference