Skip to main content

Highlighting Search Results

Each search hit returns a highlight for every matched field: the field text with matched query words wrapped in tags. Storefronts use it to show shoppers why a product matched.

Highlighting is configured with highlight_settings on a search profile. Changes apply immediately. A reindex is not required.

Response​

Highlights are returned in each hit's highlight object, keyed by field:

  • snippet: the field text with matches marked. Fields longer than snippet_threshold are trimmed to context_num_tokens words either side of each match.
  • value: the whole marked-up field. Returned only for fields in full_fields.
{
  "highlight": {
    "description": {
      "snippet": "existing locks. 9 V <mark>alkaline</mark> battery included. Fits most"
    }
  }
}

Settings​

SettingDefaultDescription
fieldsAll query fieldsFields to highlight
full_fieldsNoneHighlighted fields that also return value
start_tag<mark>Tag before each match
end_tag</mark>Tag after each match
snippet_threshold30Field length above which snippet is trimmed. 0 trims every field
context_num_tokens4Words kept either side of each match. 0 returns the matched word only

Lengths count words, not characters.

{
  "highlight_settings": {
    "fields": ["name", "description"],
    "full_fields": ["name"],
    "start_tag": "<em>",
    "end_tag": "</em>",
    "snippet_threshold": 30,
    "context_num_tokens": 6
  }
}

On update, the object is replaced as a whole. Send "highlight_settings": null to restore the defaults.

Behavior Notes​

  • fields can name fields the profile does not query, for example to search name but highlight description too. Highlighting has no effect on matching or ranking. An empty array means all query fields. Highlighting cannot be turned off.
  • full_fields entries must be highlighted fields: in fields when set, otherwise query fields. The profile is rejected otherwise.
  • highlight_full_fields request parameter replaces the profile's full_fields for that request.
  • Tags fall back to their defaults independently. Set both, or you get markup like <em>toaster</mark>. The same tags apply to facet value search labels.
  • Autocomplete always highlights the suggestion text. fields and full_fields are ignored. Tags, snippet settings, and highlight_full_fields apply.
warning

Highlights are not escaped. Sanitize them before rendering as HTML.

Ask External AI