Highlighting

Emphasize matched query terms via affix snippets or fully highlighted fields. Options, compiler mapping, and result helpers.

When you want to emphasize matched query terms, use highlighting. It supports concise affix snippets around matches or fully highlighted fields.

DSL usage

Verbatim ticket example:

rel = SearchEngine::Book
  .highlight(fields: %i[name description], full_fields: %i[description], start_tag: "<em>", end_tag: "</em>", affix_tokens: 8, snippet_threshold: 30)

Variations:

# Use <mark> tags and only snippet fields
SearchEngine::Book.highlight(fields: %i[name], start_tag: "<mark>", end_tag: "</mark>")

# Only full_fields (no affix snippets)
SearchEngine::Book.highlight(fields: %i[name], full_fields: %i[description])

Compiler mapping

Emitted Typesense params:

• highlight_fields
• highlight_full_fields
• highlight_affix_num_tokens
• highlight_start_tag
• highlight_end_tag
• snippet_threshold

Options and validation

• fields: Array<Symbol/String> — required. At least one non‑blank field.
• full_fields: Array<Symbol/String> — optional.
• start_tag/end_tag: simple HTML‑like tokens such as <em>, </em>, <mark>, </mark>. Attributes are not allowed.
• affix_tokens/snippet_threshold: non‑negative integers; strings of digits are coerced.

On invalid values the API raises SearchEngine::Errors::InvalidOption with a helpful hint.

See: #options in this page.

Result helpers

Each hydrated hit gets two helpers:

• hit.highlights → Hash{ field_name => [ { value:, matched_tokens:, snippet: true/false } ] }
• hit.snippet_for(:description, full: false) → HTML safe string (Rails SafeBuffer when present)

Safety:

• Only your configured start_tag/end_tag are preserved. All other markup is escaped to prevent XSS.
• If the server returns different tags, they are normalized to your configured tags.

Troubleshooting

• Missing highlights: ensure fields: includes the attributes you search over and that Typesense has highlighting enabled for the collection.
• Tags not applied: invalid tags are rejected; use simple tokens like <em> and </em>.
• Snippets too long/short: adjust affix_tokens and snippet_threshold.

Backlinks

• See DX for DX helpers (to_params_json, dry_run!, explain).
• See Relation Guide and Cookbook Queries for composing DSL calls.
• See Observability for event names.
• Related: Faceting if you combine facets and highlighting.