{
  "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.",
  "type" : "scalar",
  "name" : "top_snippets",
  "description" : "Use `TOP_SNIPPETS` to extract the best snippets for a given query string from a text field.",
  "signatures" : [
    {
      "params" : [
        {
          "name" : "field",
          "type" : "keyword",
          "optional" : false,
          "description" : "The input to chunk."
        },
        {
          "name" : "query",
          "type" : "keyword",
          "optional" : false,
          "description" : "The input text containing only query terms for snippet extraction. Lucene query syntax, operators, and wildcards are not allowed. "
        }
      ],
      "variadic" : false,
      "returnType" : "keyword"
    },
    {
      "params" : [
        {
          "name" : "field",
          "type" : "keyword",
          "optional" : false,
          "description" : "The input to chunk."
        },
        {
          "name" : "query",
          "type" : "keyword",
          "optional" : false,
          "description" : "The input text containing only query terms for snippet extraction. Lucene query syntax, operators, and wildcards are not allowed. "
        },
        {
          "name" : "options",
          "type" : "function_named_parameters",
          "mapParams" : "{name='num_words', values=[300], description='The maximum number of words to return in each snippet.\nThis allows better control of inference costs by limiting the size of tokens per snippet.\n', type=[integer]}, {name='num_snippets', values=[3], description='The maximum number of matching snippets to return.', type=[integer]}",
          "optional" : true,
          "description" : "(Optional) `TOP_SNIPPETS` additional options as [function named parameters](https://www.elastic.co/docs/reference/query-languages/esql/esql-syntax#esql-function-named-params)."
        }
      ],
      "variadic" : false,
      "returnType" : "keyword"
    },
    {
      "params" : [
        {
          "name" : "field",
          "type" : "text",
          "optional" : false,
          "description" : "The input to chunk."
        },
        {
          "name" : "query",
          "type" : "keyword",
          "optional" : false,
          "description" : "The input text containing only query terms for snippet extraction. Lucene query syntax, operators, and wildcards are not allowed. "
        }
      ],
      "variadic" : false,
      "returnType" : "keyword"
    },
    {
      "params" : [
        {
          "name" : "field",
          "type" : "text",
          "optional" : false,
          "description" : "The input to chunk."
        },
        {
          "name" : "query",
          "type" : "keyword",
          "optional" : false,
          "description" : "The input text containing only query terms for snippet extraction. Lucene query syntax, operators, and wildcards are not allowed. "
        },
        {
          "name" : "options",
          "type" : "function_named_parameters",
          "mapParams" : "{name='num_words', values=[300], description='The maximum number of words to return in each snippet.\nThis allows better control of inference costs by limiting the size of tokens per snippet.\n', type=[integer]}, {name='num_snippets', values=[3], description='The maximum number of matching snippets to return.', type=[integer]}",
          "optional" : true,
          "description" : "(Optional) `TOP_SNIPPETS` additional options as [function named parameters](https://www.elastic.co/docs/reference/query-languages/esql/esql-syntax#esql-function-named-params)."
        }
      ],
      "variadic" : false,
      "returnType" : "keyword"
    }
  ],
  "examples" : [
    "FROM books\n| EVAL snippets = TOP_SNIPPETS(description, \"Tolkien\")",
    "FROM books\n| WHERE MATCH(title, \"Return\")\n| EVAL snippets = TOP_SNIPPETS(description, \"Tolkien\", { \"num_snippets\": 3, \"num_words\": 25 })"
  ],
  "preview" : true,
  "snapshot_only" : false
}