ES|QL TOP_SNIPPETS function

×

field

The field to extract snippets from. The input can be a single-valued or multi-valued field. In the case of a multi-valued argument, snippets are extracted from each value separately.

query

The input text containing only query terms for snippet extraction. Lucene query syntax, operators, and wildcards are not allowed.

options

(Optional) TOP_SNIPPETS additional options as function named parameters.

Use TOP_SNIPPETS to extract the best snippets for a given query string from a text field.

TOP_SNIPPETS can be used on fields from the text family like text and semantic_text. TOP_SNIPPETS will extract the best snippets for a given query string.

num_snippets

(integer) The maximum number of matching snippets to return.

num_words

(integer) The maximum number of words to return in each snippet.

When set to 0, disables chunking entirely, the input field values are used as-is, which is useful when the text has already been chunked.

highlight

(boolean) When true, wraps matched query terms in the returned snippets with markup tags. Defaults to false.

pre_tag

(keyword) Opening tag for highlighted terms. Only applies when highlight is true. Defaults to <em>.

post_tag

(keyword) Closing tag for highlighted terms. Only applies when highlight is true. Defaults to </em>.

encoder

(keyword) Controls HTML encoding of snippet text before tagging: default (no encoding) or html. Only applies when highlight is true. Defaults to default.

FROM books
| EVAL snippets = TOP_SNIPPETS(description, "Tolkien")
		

FROM books
| WHERE MATCH(title, "Return")
| EVAL snippets = TOP_SNIPPETS(description, "Tolkien", { "num_snippets": 3, "num_words": 25 })
		

FROM books
| WHERE MATCH(title, "return")
| RERANK "Tolkien" ON TOP_SNIPPETS(description, "Tolkien", { "num_snippets": 3, "num_words": 25 }) WITH { "inference_id" : "test_reranker" }
		

This examples demonstrates how to use TOP_SNIPPETS with RERANK. By returning a fixed number of snippets with a limited size, we have more control over the number of tokens that are used for semantic reranking.

FROM books
| WHERE MATCH(title, "Return")
| EVAL snippets = TOP_SNIPPETS(description, "Tolkien", { "num_snippets": 1, "num_words": 25, "highlight": true })
		

Enable highlighting by setting highlight to true in the options. This wraps matched query terms in the returned snippets with <em> tags by default. To use different tags, set the pre_tag and post_tag options to the desired opening and closing tags respectively.

ROW chunks = ["Alice was beginning to get very tired of sitting by her sister on the bank. The white rabbit disappeared down a hole and Alice quickly jumped in after it. The rabbit hole went straight on like a tunnel for some way and then dipped suddenly.", "The Queen of Hearts ordered her soldiers to paint the white roses red."]
| EVAL snippets = TOP_SNIPPETS(chunks, "alice rabbit hole", {"num_words": 0, "highlight": true})
		

Set num_words to 0 to disable chunking entirely. This keeps the input field values as-is, which is useful when the text has already been chunked. Combine this with highlight set to true to highlight matched terms within each full value.

ROW content = CONCAT(
    "# Climate Change Solutions\\n\\n",
    "## Renewable Energy\\n",
    "Solar and wind power are becoming cost-competitive with fossil fuels. Investment in clean energy infrastructure creates jobs.\\n\\n",
    "## Carbon Capture\\n",
    "Direct air capture technology removes CO2 from the atmosphere. These systems require significant energy input but show promise for large-scale deployment.\\n\\n",
    "## Policy Changes\\n",
    "Government regulations can accelerate the transition to clean energy through carbon pricing and renewable energy mandates.")
| EVAL chunked_content = CHUNK(content, {"strategy": "recursive", "max_chunk_size": 30, "separators": ["##", "\\n\\n"]})
| EVAL snippets = TOP_SNIPPETS(chunked_content, "clean energy", {"num_words": 0, "num_snippets": 1, "highlight":true})
| KEEP snippets
		

This is another example of setting num_words to 0, this time applied to an input that has already been chunked with the CHUNK command. The markdown text is chunked by sections first, and because the text is pre-chunked, no further splitting is needed. Setting num_words to 0 disables chunking so that each chunk is scored and highlighted individually.