---
title: ES|QL TOP_SNIPPETS function
description:
url: https://www.elastic.co/elastic/docs-builder/docs/3016/reference/query-languages/esql/functions-operators/search-functions/top-snippets
products:
- Elasticsearch
---
# ES|QL TOP_SNIPPETS function
- Elastic Cloud Serverless: Preview
- Elastic Stack: Preview since 9.3
## Syntax
## Parameters
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.
The input text containing only query terms for snippet extraction. Lucene query syntax, operators, and wildcards are not allowed.
(Optional) `TOP_SNIPPETS` additional options as [function named parameters](/elastic/docs-builder/docs/3016/reference/query-languages/esql/esql-syntax#esql-function-named-params).
## Description
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](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/mapping-reference/text) and [semantic_text](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/elasticsearch/mapping-reference/semantic-text).
`TOP_SNIPPETS` will extract the best snippets for a given query string.
## Supported types
| field | query | options | result |
|---------|---------|------------------|---------|
| keyword | keyword | named parameters | keyword |
| keyword | keyword | | keyword |
| text | keyword | named parameters | keyword |
| text | keyword | | keyword |
### Supported function named parameters
(integer) The maximum number of matching snippets to return.
(integer) The maximum number of words to return in each snippet.
## Examples
- Elastic Stack: Preview since 9.3
```esql
FROM books
| EVAL snippets = TOP_SNIPPETS(description, "Tolkien")
```
| book_no:keyword | title:text | snippets:keyword |
|-----------------|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1211 | The brothers Karamazov | null |
| 1463 | Realms of Tolkien: Images of Middle-earth | Twenty new and familiar Tolkien artists are represented in this fabulous volume, breathing an extraordinary variety of life into 58 different scenes, each of which is accompanied by appropriate passage from The Hobbit and The Lord of the Rings and The Silmarillion |
| 1502 | Selected Passages from Correspondence with Friends | null |
| 1937 | The Best Short Stories of Dostoevsky (Modern Library) | null |
| 1985 | Brothers Karamazov | null |
- Elastic Stack: Preview since 9.3
```esql
FROM books
| WHERE MATCH(title, "Return")
| EVAL snippets = TOP_SNIPPETS(description, "Tolkien", { "num_snippets": 3, "num_words": 25 })
```
| book_no:keyword | title:text | snippets:keyword |
|-----------------|------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 2714 | Return of the King Being the Third Part of The Lord of the Rings | [Concluding the story begun in The Hobbit, this is the final part of Tolkien s epic masterpiece, The Lord of the Rings, featuring an exclusive, Tolkien s epic masterpiece, The Lord of the Rings, featuring an exclusive cover image from the film, the definitive text, and a detailed map of, Tolkien s classic tale of magic and adventure, begun in The Fellowship of the Ring and The Two Towers, features the definitive edition of the] |
| 7350 | Return of the Shadow | [Tolkien for long believed would be a far shorter book, 'a sequel to The Hobbit'., In The Return of the Shadow (an abandoned title for the first volume) Christopher Tolkien describes, with full citation of the earliest notes, outline plans, ) Christopher Tolkien describes, with full citation of the earliest notes, outline plans, and narrative drafts, the intricate evolution of The Fellowship of the Ring and] |
- Elastic Stack: Preview since 9.3
```esql
FROM books
| WHERE MATCH(title, "return")
| RERANK "Tolkien" ON TOP_SNIPPETS(description, "Tolkien", { "num_snippets": 3, "num_words": 25 }) WITH { "inference_id" : "test_reranker" }
```
| book_no:keyword | title:text | _score:double |
|-----------------|------------------------------------------------------------------|----------------------|
| 2714 | Return of the King Being the Third Part of The Lord of the Rings | 0.007092198356986046 |
| 7350 | Return of the Shadow | 0.012500000186264515 |
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.