---
type: api
title: Create or update a script or search template
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/operation/operation-put-script
resource: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/operation/operation-put-script
products:
  - Elasticsearch
---

# Create or update a script or search template

Authentication: required

## Paths

- `POST` (also `PUT`) `/_scripts/{id}/{context}`
- `POST` (also `PUT`) `/_scripts/{id}`

#### Path parameters

- `id` (string) — required
  The identifier for the stored script or search template.
It must be unique within the cluster.
- `context` (string) — optional, leave it out to use `/_scripts/{id}`
  The context in which the script or search template should run.
To prevent errors, the API immediately compiles the script or template in this context.

## Description

Creates or updates a stored script or search template.

[More about searching templates](https://www.elastic.co/docs/solutions/search/search-templates)

## Required authorization

- Cluster privileges: `manage`

## Query string parameters

- `context` (string) — optional
  The context in which the script or search template should run.
To prevent errors, the API immediately compiles the script or template in this context.
If you specify both this and the `<context>` path parameter, the API uses the request path parameter.
- `master_timeout` (string · default: 30s) — optional
  The period to wait for a connection to the master node.
If no response is received before the timeout expires, the request fails and returns an error.
It can also be set to `-1` to indicate that the request should never timeout.
- `timeout` (string · default: 30s) — optional
  The period to wait for a response.
If no response is received before the timeout expires, the request fails and returns an error.
It can also be set to `-1` to indicate that the request should never timeout.

## Request body

`application/json`

- `script` (object) — required
  The script or search template, its parameters, and its language.
  - `lang` (union anyOf) — required
    The language the script is written in.
For search templates, use `mustache`.

Supported values include:
  - `painless`: Painless scripting language, purpose-built for Elasticsearch.
  - `expression`: Lucene’s expressions language, compiles a JavaScript expression to bytecode.
  - `mustache`: Mustache templated, used for templates.
  - `java`: Expert Java API
    Values: `painless`, `expression`, `mustache`, `java`
  - `options` (map string to string) — optional
  - `source` (union oneOf) — required
    The script source.
For search templates, an object containing the search template.
    - **string**
    - **SearchRequestBody**
      - `aggregations` (map string to {} Aggregation) — optional
        Defines the aggregations that are run as part of the search request.
        See [Aggregation](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-aggregations-aggregationcontainer)
      - `collapse` (object) — optional
        Collapses search results the values of the specified field.
        - `field` (string) — required
          The field to collapse the result set on
        - `inner_hits` (union oneOf) — optional
          The number of inner hits and their sort order
          `object` or `object[]`
          - `name` (string) — optional
            The name for the particular inner hit definition in the response.
Useful when a search request contains multiple inner hits.
          - `size` (number · default: 3) — optional
            The maximum number of hits to return per `inner_hits`.
          - `from` (number · default: 0) — optional
            Inner hit starting document offset.
          - `collapse` (object) — optional — recursive
            Same fields as `collapse` in `SearchRequestBody`
          - `docvalue_fields` (object[]) — optional
            - `field` (string) — required
              A wildcard pattern. The request returns values for field names matching this pattern.
            - `format` (string) — optional
              The format in which the values are returned.
            - `include_unmapped` (boolean) — optional
          - `explain` (boolean) — optional
          - `highlight` (object) — optional
            - `type` (union anyOf) — optional
              

Supported values include:
  - `plain`: The `plain` highlighter uses the standard Lucene highlighter
  - `fvh`: The fvh highlighter uses the Lucene Fast Vector highlighter.
  - `unified`: The unified highlighter uses the Lucene Unified Highlighter.
              Values: `plain`, `fvh`, `unified`
            - `boundary_chars` (string · default: .,!? \t\n) — optional
              A string that contains each boundary character.
            - `boundary_max_scan` (number · default: 20) — optional
              How far to scan for boundary characters.
            - `boundary_scanner` (enum) — optional
              Specifies how to break the highlighted fragments: chars, sentence, or word.
Only valid for the unified and fvh highlighters.
Defaults to `sentence` for the `unified` highlighter. Defaults to `chars` for the `fvh` highlighter.

Supported values include:
  - `chars`: Use the characters specified by `boundary_chars` as highlighting boundaries.
The `boundary_max_scan` setting controls how far to scan for boundary characters.
Only valid for the `fvh` highlighter.
  - `sentence`: Break highlighted fragments at the next sentence boundary, as determined by Java’s `BreakIterator`.
You can specify the locale to use with `boundary_scanner_locale`.
When used with the `unified` highlighter, the `sentence` scanner splits sentences bigger than `fragment_size` at the first word boundary next to fragment_size.
You can set `fragment_size` to `0` to never split any sentence.
  - `word`: Break highlighted fragments at the next word boundary, as determined by Java’s `BreakIterator`.
You can specify the locale to use with `boundary_scanner_locale`.
              Values: `chars`, `sentence`, `word`
            - `boundary_scanner_locale` (string · default: Locale.ROOT) — optional
              Controls which locale is used to search for sentence and word boundaries.
This parameter takes a form of a language tag, for example: `"en-US"`, `"fr-FR"`, `"ja-JP"`.
            - `force_source` (boolean) — optional — deprecated
            - `fragmenter` (enum · default: span) — optional
              Specifies how text should be broken up in highlight snippets: `simple` or `span`.
Only valid for the `plain` highlighter.
              Values: `simple`, `span`
            - `fragment_size` (number · default: 100) — optional
              The size of the highlighted fragment in characters.
            - `highlight_filter` (boolean) — optional
            - `highlight_query` ({} Query) — optional
              Highlight matches for a query other than the search query.
This is especially useful if you use a rescore query because those are not taken into account by highlighting by default.
              See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            - `max_fragment_length` (number) — optional
            - `max_analyzed_offset` (number) — optional
              If set to a non-negative value, highlighting stops at this defined maximum limit.
The rest of the text is not processed, thus not highlighted and no error is returned
The `max_analyzed_offset` query setting does not override the `index.highlight.max_analyzed_offset` setting, which prevails when it’s set to lower value than the query setting.
            - `no_match_size` (number · default: 0) — optional
              The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
            - `number_of_fragments` (number · default: 5) — optional
              The maximum number of fragments to return.
If the number of fragments is set to `0`, no fragments are returned.
Instead, the entire field contents are highlighted and returned.
This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required.
If `number_of_fragments` is `0`, `fragment_size` is ignored.
            - `options` (map string to object) — optional
            - `order` (enum · default: none) — optional
              Sorts highlighted fragments by score when set to `score`.
By default, fragments will be output in the order they appear in the field (order: `none`).
Setting this option to `score` will output the most relevant fragments first.
Each highlighter applies its own logic to compute relevancy scores.
              Values: `score`
            - `phrase_limit` (number · default: 256) — optional
              Controls the number of matching phrases in a document that are considered.
Prevents the `fvh` highlighter from analyzing too many phrases and consuming too much memory.
When using `matched_fields`, `phrase_limit` phrases per matched field are considered. Raising the limit increases query time and consumes more memory.
Only supported by the `fvh` highlighter.
            - `post_tags` (string[]) — optional
              Use in conjunction with `pre_tags` to define the HTML tags to use for the highlighted text.
By default, highlighted text is wrapped in `<em>` and `</em>` tags.
            - `pre_tags` (string[]) — optional
              Use in conjunction with `post_tags` to define the HTML tags to use for the highlighted text.
By default, highlighted text is wrapped in `<em>` and `</em>` tags.
            - `require_field_match` (boolean · default: true) — optional
              By default, only fields that contains a query match are highlighted.
Set to `false` to highlight all fields.
            - `tags_schema` (enum) — optional
              Set to `styled` to use the built-in tag schema.
              Values: `styled`
            - `encoder` (enum) — optional
              Values: `default`, `html`
            - `fields` (union oneOf) — required
              `map string to object` or `[] map string to object`
          - `ignore_unmapped` (boolean) — optional
          - `script_fields` (map string to object) — optional
            Map values (object)
            - `script` (string) — required
            - `ignore_failure` (boolean) — optional
          - `seq_no_primary_term` (boolean) — optional
          - `field` (string[]) — optional
          - `fields` (object[]) — optional
            - `field` (string) — required
              A wildcard pattern. The request returns values for field names matching this pattern.
            - `format` (string) — optional
              The format in which the values are returned.
            - `include_unmapped` (boolean) — optional
          - `sort` (union oneOf) — optional
            How the inner hits should be sorted per `inner_hits`.
By default, inner hits are sorted by score.
            A value or an array; each item is one of:
            - **string**
              Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
            - **SortOptions**
              - `_score` (object) — optional
                - `order` (enum) — optional
                  

Supported values include:
  - `asc`: Ascending (smallest to largest)
  - `desc`: Descending (largest to smallest)
                  Values: `asc`, `desc`
              - `_doc` (object) — optional
                - `order` (enum) — optional
                  

Supported values include:
  - `asc`: Ascending (smallest to largest)
  - `desc`: Descending (largest to smallest)
                  Values: `asc`, `desc`
              - `_geo_distance` (object) — optional
                - `mode` (enum) — optional
                  Values: `min`, `max`, `sum`, `avg`, `median`
                - `distance_type` (enum) — optional
                  

Supported values include:
  - `arc`: The `arc` calculation is the most accurate.
  - `plane`: The `plane` calculation is faster but less accurate.
                  Values: `arc`, `plane`
                - `ignore_unmapped` (boolean) — optional
                - `order` (enum) — optional
                  

Supported values include:
  - `asc`: Ascending (smallest to largest)
  - `desc`: Descending (largest to smallest)
                  Values: `asc`, `desc`
                - `unit` (enum) — optional
                  Values: `in`, `ft`, `yd`, `mi`, `nmi`, `km`, `m`, `cm`, `mm`
                - `nested` (object) — optional
                  - `filter` ({} Query) — optional
                    See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
                  - `max_children` (number) — optional
                  - `nested` (object) — optional — recursive
                    Same fields as `nested` in `_geo_distance`
                  - `path` (string) — required
              - `_script` (object) — optional
                - `order` (enum) — optional
                  

Supported values include:
  - `asc`: Ascending (smallest to largest)
  - `desc`: Descending (largest to smallest)
                  Values: `asc`, `desc`
                - `script` (string) — required
                - `type` (enum) — optional
                  Values: `string`, `number`, `version`
                - `mode` (enum) — optional
                  Values: `min`, `max`, `sum`, `avg`, `median`
                - `nested` (object) — optional
                  - `filter` ({} Query) — optional
                    See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
                  - `max_children` (number) — optional
                  - `nested` (object) — optional — recursive
                    Same fields as `nested` in `_script`
                  - `path` (string) — required
          - `_source` (union oneOf) — optional
            - **boolean**
            - **SourceFilter**
              - `exclude_vectors` (boolean) — optional
                If `true`, vector fields are excluded from the returned source.

This option takes precedence over `includes`: any vector field will
remain excluded even if it matches an `includes` rule.
              - `excludes` (union oneOf) — optional
                A list of fields to exclude from the returned source.
                One of: `string[]` or `string`
              - `includes` (union oneOf) — optional
                A list of fields to include in the returned source.
                One of: `string[]` or `string`
          - `stored_fields` (union oneOf) — optional
            One of: `string[]` or `string`
          - `track_scores` (boolean · default: false) — optional
          - `version` (boolean) — optional
        - `max_concurrent_group_searches` (number) — optional
          The number of concurrent requests allowed to retrieve the inner_hits per group
      - `explain` (boolean · default: false) — optional
        If `true`, the request returns detailed information about score computation as part of a hit.
      - `ext` (map string to object) — optional
        Configuration of search extensions defined by Elasticsearch plugins.
      - `from` (number · default: 0) — optional
        The starting document offset, which must be non-negative.
By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.
To page through more hits, use the `search_after` parameter.
      - `highlight` (object) — optional
        Specifies the highlighter to use for retrieving highlighted snippets from one or more fields in your search results.
        Same fields as `highlight` in `inner_hits`
      - `track_total_hits` (boolean | number · default: 10000) — optional
        Number of hits matching the query to count accurately.
If `true`, the exact number of hits is returned at the cost of some performance.
If `false`, the  response does not include the total number of hits matching the query.
      - `indices_boost` (string to number[]) — optional
        Boost the `_score` of documents from specified indices.
The boost value is the factor by which scores are multiplied.
A boost value greater than `1.0` increases the score.
A boost value between `0` and `1.0` decreases the score.
      - `docvalue_fields` (object[]) — optional
        An array of wildcard (`*`) field patterns.
The request returns doc values for field names matching these patterns in the `hits.fields` property of the response.
        - `field` (string) — required
          A wildcard pattern. The request returns values for field names matching this pattern.
        - `format` (string) — optional
          The format in which the values are returned.
        - `include_unmapped` (boolean) — optional
      - `knn` (union oneOf) — optional
        The approximate kNN search to run.
        `object` or `object[]`
        - `field` (string) — required
          The name of the vector field to search against
        - `query_vector` (union oneOf) — optional
          The query vector
          One of: `number[]` or `string`
        - `query_vector_builder` (object) — optional
          The query vector builder. You must provide a query_vector_builder or query_vector, but not both.
          - `embedding` (object) — optional
            - `inference_id` (string) — optional
            - `input` (union oneOf) — required
              - **string**
              - **InferenceStringGroup**
            - `timeout` (string) — optional
          - `text_embedding` (object) — optional
            - `model_id` (string) — optional
              Model ID is required for all dense_vector fields but
may be inferred for semantic_text fields
            - `model_text` (string) — required
              The text to be converted into a vector by the specified model
          - `lookup` (object) — optional
            Lookup a vector from an existing document.
Must reference a dense_vector field and a single value.
            - `id` (string) — required
              The ID of the document to fetch the vector from
            - `index` (string) — required
              The name of the index to fetch the document from
            - `path` (string) — required
              The name of the field containing the vector
            - `routing` (string) — optional
              The routing value to use when fetching the document
        - `k` (number) — optional
          The final number of nearest neighbors to return as top hits
        - `num_candidates` (number) — optional
          The number of nearest neighbor candidates to consider per shard
        - `visit_percentage` (number) — optional
          The percentage of vectors to explore per shard while doing knn search with bbq_disk
        - `boost` (number) — optional
          Boost value to apply to kNN scores
        - `filter` (union oneOf) — optional
          Filters for the kNN search query
          One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
        - `similarity` (number) — optional
          The minimum similarity for a vector to be considered a match
        - `inner_hits` (object) — optional
          If defined, each search hit will contain inner hits.
          - `name` (string) — optional
            The name for the particular inner hit definition in the response.
Useful when a search request contains multiple inner hits.
          - `size` (number · default: 3) — optional
            The maximum number of hits to return per `inner_hits`.
          - `from` (number · default: 0) — optional
            Inner hit starting document offset.
          - `collapse` (object) — optional
            - `field` (string) — required
              The field to collapse the result set on
            - `inner_hits` (union oneOf) — optional — recursive
              The number of inner hits and their sort order
              `object` or `object[]`
            - `max_concurrent_group_searches` (number) — optional
              The number of concurrent requests allowed to retrieve the inner_hits per group
          - `docvalue_fields` (object[]) — optional
            - `field` (string) — required
              A wildcard pattern. The request returns values for field names matching this pattern.
            - `format` (string) — optional
              The format in which the values are returned.
            - `include_unmapped` (boolean) — optional
          - `explain` (boolean) — optional
          - `highlight` (object) — optional
            Same fields as `highlight` in `inner_hits`
          - `ignore_unmapped` (boolean) — optional
          - `script_fields` (map string to object) — optional
            Map values (object)
            - `script` (string) — required
            - `ignore_failure` (boolean) — optional
          - `seq_no_primary_term` (boolean) — optional
          - `field` (string[]) — optional
          - `fields` (object[]) — optional
            - `field` (string) — required
              A wildcard pattern. The request returns values for field names matching this pattern.
            - `format` (string) — optional
              The format in which the values are returned.
            - `include_unmapped` (boolean) — optional
          - `sort` (union oneOf) — optional
            How the inner hits should be sorted per `inner_hits`.
By default, inner hits are sorted by score.
            Same options as `sort` in `inner_hits`
          - `_source` (union oneOf) — optional
            - **boolean**
            - **SourceFilter**
              - `exclude_vectors` (boolean) — optional
                If `true`, vector fields are excluded from the returned source.

This option takes precedence over `includes`: any vector field will
remain excluded even if it matches an `includes` rule.
              - `excludes` (union oneOf) — optional
                A list of fields to exclude from the returned source.
                One of: `string[]` or `string`
              - `includes` (union oneOf) — optional
                A list of fields to include in the returned source.
                One of: `string[]` or `string`
          - `stored_fields` (union oneOf) — optional
            One of: `string[]` or `string`
          - `track_scores` (boolean · default: false) — optional
          - `version` (boolean) — optional
        - `rescore_vector` (object) — optional
          Apply oversampling and rescoring to quantized vectors
          - `oversample` (number) — required
            Applies the specified oversample factor to k on the approximate kNN search
        - `_name` (string) — optional
      - `rank` (object) — optional
        The Reciprocal Rank Fusion (RRF) to use.
        - `rrf` (object) — optional
          The reciprocal rank fusion parameters
          - `rank_constant` (number) — optional
            How much influence documents in individual result sets per query have over the final ranked result set
          - `rank_window_size` (number) — optional
            Size of the individual result sets per query
      - `min_score` (number) — optional
        The minimum `_score` for matching documents.
Documents with a lower `_score` are not included in search results or results collected by aggregations.
      - `post_filter` ({} Query) — optional
        Use the `post_filter` parameter to filter search results.
The search hits are filtered after the aggregations are calculated.
A post filter has no impact on the aggregation results.
        See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
      - `profile` (boolean · default: false) — optional
        Set to `true` to return detailed timing information about the execution of individual components in a search request.
NOTE: This is a debugging tool and adds significant overhead to search execution.
      - `query` ({} Query) — optional
        The search definition using the Query DSL.
        See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
      - `rescore` (union oneOf) — optional
        Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the `query` and `post_filter` phases.
        `object` or `object[]`
        - `window_size` (number) — optional
        - `query` (object) — optional
          - `rescore_query` ({} Query) — required
            The query to use for rescoring.
This query is only run on the Top-K results returned by the `query` and `post_filter` phases.
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `query_weight` (number · default: 1) — optional
            Relative importance of the original query versus the rescore query.
          - `rescore_query_weight` (number · default: 1) — optional
            Relative importance of the rescore query versus the original query.
          - `score_mode` (enum · default: total) — optional
            Determines how scores are combined.

Supported values include:
  - `avg`: Average the original score and the rescore query score.
  - `max`: Take the max of original score and the rescore query score.
  - `min`: Take the min of the original score and the rescore query score.
  - `multiply`: Multiply the original score by the rescore query score.
Useful for `function` query rescores.
  - `total`: Add the original score and the rescore query score.
            Values: `avg`, `max`, `min`, `multiply`, `total`
        - `learning_to_rank` (object) — optional
          - `model_id` (string) — required
            The unique identifier of the trained model uploaded to Elasticsearch
          - `params` (map string to object) — optional
            Named parameters to be passed to the query templates used for feature
        - `script` (object) — optional
          - `script` (string) — required
      - `retriever` (object) — optional
        A retriever is a specification to describe top documents returned from a search.
A retriever replaces other elements of the search API that also return top documents such as `query` and `knn`.
        - `standard` (object) — optional
          A retriever that replaces the functionality of a traditional query.
          - `filter` (union oneOf) — optional
            Query to filter the documents that can match.
            One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `min_score` (number) — optional
            Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
          - `_name` (string) — optional
            Retriever name.
          - `query` ({} Query) — optional
            Defines a query to retrieve a set of top documents.
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `search_after` (union[]) — optional
            Defines a search after object parameter used for pagination.
          - `terminate_after` (number) — optional
            Maximum number of documents to collect for each shard.
          - `sort` (union oneOf) — optional
            A sort object that that specifies the order of matching documents.
            Same options as `sort` in `inner_hits`
          - `collapse` (object) — optional
            Collapses the top documents by a specified key into a single top document per key.
            Same fields as `collapse` in `SearchRequestBody`
        - `knn` (object) — optional
          A retriever that replaces the functionality  of a knn search.
          - `filter` (union oneOf) — optional
            Query to filter the documents that can match.
            One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `min_score` (number) — optional
            Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
          - `_name` (string) — optional
            Retriever name.
          - `field` (string) — required
            The name of the vector field to search against.
          - `query_vector` (union oneOf) — optional
            Query vector. Must have the same number of dimensions as the vector field you are searching against. You must provide a query_vector_builder or query_vector, but not both.
            One of: `number[]` or `string`
          - `query_vector_builder` (object) — optional
            Defines a model to build a query vector.
            Same fields as `query_vector_builder` in `knn`
          - `k` (number) — required
            Number of nearest neighbors to return as top hits.
          - `num_candidates` (number) — optional
            Number of nearest neighbor candidates to consider per shard.
          - `visit_percentage` (number) — optional
            The percentage of vectors to explore per shard while doing knn search with bbq_disk
          - `similarity` (number) — optional
            The minimum similarity required for a document to be considered a match.
          - `rescore_vector` (object) — optional
            Apply oversampling and rescoring to quantized vectors
            - `oversample` (number) — required
              Applies the specified oversample factor to k on the approximate kNN search
        - `rrf` (object) — optional
          A retriever that produces top documents from reciprocal rank fusion (RRF).
          - `filter` (union oneOf) — optional
            Query to filter the documents that can match.
            One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `min_score` (number) — optional
            Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
          - `_name` (string) — optional
            Retriever name.
          - `retrievers` (union oneOf[]) — required — recursive
            A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them. Each retriever can optionally include a weight parameter.
          - `rank_constant` (number) — optional
            This value determines how much influence documents in individual result sets per query have over the final ranked result set.
          - `rank_window_size` (number) — optional
            This value determines the size of the individual result sets per query.
          - `query` (string) — optional
          - `fields` (string[]) — optional
        - `text_similarity_reranker` (object) — optional
          A retriever that reranks the top documents based on a reranking model using the InferenceAPI
          - `filter` (union oneOf) — optional
            Query to filter the documents that can match.
            One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `min_score` (number) — optional
            Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
          - `_name` (string) — optional
            Retriever name.
          - `retriever` (object) — required — recursive
            The nested retriever which will produce the first-level results, that will later be used for reranking.
            Same fields as `retriever` in `SearchRequestBody`
          - `rank_window_size` (number) — optional
            This value determines how many documents we will consider from the nested retriever.
          - `inference_id` (string) — optional
            Unique identifier of the inference endpoint created using the inference API.
          - `inference_text` (string) — required
            The text snippet used as the basis for similarity comparison.
          - `field` (string) — required
            The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text.
          - `chunk_rescorer` (object) — optional
            Whether to rescore on only the best matching chunks.
            - `size` (number) — optional
              The number of chunks per document to evaluate for reranking.
            - `chunking_settings` (object) — optional
              Chunking settings to apply
              - `max_chunk_size` (number · default: 250) — required
                The maximum size of a chunk in words.
This value cannot be lower than `20` (for `sentence` strategy) or `10` (for `word` strategy).
This value should not exceed the window size for the associated model.
              - `overlap` (number · default: 100) — optional
                The number of overlapping words for chunks.
It is applicable only to a `word` chunking strategy.
This value cannot be higher than half the `max_chunk_size` value.
              - `sentence_overlap` (number · default: 1) — optional
                The number of overlapping sentences for chunks.
It is applicable only for a `sentence` chunking strategy.
It can be either `1` or `0`.
              - `separator_group` (string) — optional
                Only applicable to the `recursive` strategy and required when using it.

Sets a predefined list of separators in the saved chunking settings based on the selected text type.
Values can be `markdown` or `plaintext`.

Using this parameter is an alternative to manually specifying a custom `separators` list.
              - `separators` (string[]) — optional
                Only applicable to the `recursive` strategy and required when using it.

A list of strings used as possible split points when chunking text.

Each string can be a plain string or a regular expression (regex) pattern.
The system tries each separator in order to split the text, starting from the first item in the list.

After splitting, it attempts to recombine smaller pieces into larger chunks that stay within
the `max_chunk_size` limit, to reduce the total number of chunks generated.
              - `strategy` (string · default: sentence) — optional
                The chunking strategy: `sentence`, `word`, `none` or `recursive`.

 * If `strategy` is set to `recursive`, you must also specify:

- `max_chunk_size`
- either `separators` or`separator_group`

Learn more about different chunking strategies in the linked documentation.
        - `rule` (object) — optional
          A retriever that replaces the functionality of a rule query.
          - `filter` (union oneOf) — optional
            Query to filter the documents that can match.
            One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `min_score` (number) — optional
            Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
          - `_name` (string) — optional
            Retriever name.
          - `ruleset_ids` (union string | string[]) — required
            The ruleset IDs containing the rules this retriever is evaluating against.
          - `match_criteria` (object) — required
            The match criteria that will determine if a rule in the provided rulesets should be applied.
          - `retriever` (object) — required — recursive
            The retriever whose results rules should be applied to.
            Same fields as `retriever` in `SearchRequestBody`
          - `rank_window_size` (number) — optional
            This value determines the size of the individual result set.
        - `rescorer` (object) — optional
          A retriever that re-scores only the results produced by its child retriever.
          - `filter` (union oneOf) — optional
            Query to filter the documents that can match.
            One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `min_score` (number) — optional
            Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
          - `_name` (string) — optional
            Retriever name.
          - `retriever` (object) — required — recursive
            Inner retriever.
            Same fields as `retriever` in `SearchRequestBody`
          - `rescore` (union oneOf) — required
            Same options as `rescore` in `SearchRequestBody`
            `object` or `object[]`
        - `linear` (object) — optional
          A retriever that supports the combination of different retrievers through a weighted linear combination.
          - `filter` (union oneOf) — optional
            Query to filter the documents that can match.
            One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `min_score` (number) — optional
            Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
          - `_name` (string) — optional
            Retriever name.
          - `retrievers` (object[]) — optional
            Inner retrievers.
            - `retriever` (object) — required — recursive
              The nested retriever configuration.
              Same fields as `retriever` in `SearchRequestBody`
            - `weight` (number · default: 1) — optional
              Weight multiplier for this retriever's contribution to the linear combination.
Must be non-negative.
            - `normalizer` (enum · default: none) — optional
              Score normalizer to apply to this retriever's results before weighting.
Falls back to the top-level `normalizer` on the linear retriever if unset,
then to `none` (identity) if neither is set.
              Values: `none`, `minmax`, `l2_norm`
          - `rank_window_size` (number) — optional
          - `query` (string) — optional
          - `fields` (string[]) — optional
          - `normalizer` (enum) — optional
            Values: `none`, `minmax`, `l2_norm`
        - `pinned` (object) — optional
          A pinned retriever applies pinned documents to the underlying retriever.
This retriever will rewrite to a PinnedQueryBuilder.
          - `filter` (union oneOf) — optional
            Query to filter the documents that can match.
            One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `min_score` (number) — optional
            Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
          - `_name` (string) — optional
            Retriever name.
          - `retriever` (object) — required — recursive
            Inner retriever.
            Same fields as `retriever` in `SearchRequestBody`
          - `ids` (string[]) — optional
          - `docs` (object[]) — optional
            - `index` (string) — optional
            - `id` (string) — required
          - `rank_window_size` (number) — optional
        - `diversify` (object) — optional
          A retriever that diversifies the results from its child retriever.
          - `filter` (union oneOf) — optional
            Query to filter the documents that can match.
            One of: [`Query[]`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`Query`](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
            See [Query](https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/types/_types-query_dsl-querycontainer)
          - `min_score` (number) — optional
            Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
          - `_name` (string) — optional
            Retriever name.
          - `type` (enum) — required
            The diversification strategy to apply.
            Values: `mmr`
          - `field` (string) — required
            The document field on which to diversify results on.
          - `retriever` (object) — required — recursive
            The nested retriever whose results will be diversified.
            Same fields as `retriever` in `SearchRequestBody`
          - `size` (number) — optional
            The number of top documents to return after diversification.
          - `rank_window_size` (number) — optional
            The number of top documents from the nested retriever to consider for diversification.
          - `query_vector` (union oneOf) — optional
            The query vector used for diversification.
            One of: `number[]` or `string`
          - `query_vector_builder` (object) — optional
            a dense vector query vector builder to use instead of a static query_vector
            Same fields as `query_vector_builder` in `knn`
          - `lambda` (number) — optional
            Controls the trade-off between relevance and diversity for MMR. A value of 0.0 focuses solely on diversity, while a value of 1.0 focuses solely on relevance. Required for MMR
      - `script_fields` (map string to object) — optional
        Retrieve a script evaluation (based on different fields) for each hit.
        Map values (object)
        - `script` (string) — required
        - `ignore_failure` (boolean) — optional
      - `search_after` (union[]) — optional
        Used to retrieve the next page of hits using a set of sort values from the previous page.
      - `size` (number · default: 10) — optional
        The number of hits to return, which must not be negative.
By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.
To page through more hits, use the `search_after` property.
      - `slice` (object) — optional
        Split a scrolled search into multiple slices that can be consumed independently.
        - `field` (string) — optional
        - `id` (string) — required
        - `max` (number) — required
      - `sort` (union oneOf) — optional
        A comma-separated list of <field>:<direction> pairs.
        Same options as `sort` in `inner_hits`
      - `_source` (union oneOf) — optional
        The source fields that are returned for matching documents.
These fields are returned in the `hits._source` property of the search response.
If the `stored_fields` property is specified, the `_source` property defaults to `false`.
Otherwise, it defaults to `true`.
        - **boolean**
        - **SourceFilter**
          - `exclude_vectors` (boolean) — optional
            If `true`, vector fields are excluded from the returned source.

This option takes precedence over `includes`: any vector field will
remain excluded even if it matches an `includes` rule.
          - `excludes` (union oneOf) — optional
            A list of fields to exclude from the returned source.
            One of: `string[]` or `string`
          - `includes` (union oneOf) — optional
            A list of fields to include in the returned source.
            One of: `string[]` or `string`
      - `fields` (object[]) — optional
        An array of wildcard (`*`) field patterns.
The request returns values for field names matching these patterns in the `hits.fields` property of the response.
        - `field` (string) — required
          A wildcard pattern. The request returns values for field names matching this pattern.
        - `format` (string) — optional
          The format in which the values are returned.
        - `include_unmapped` (boolean) — optional
      - `suggest` (object) — optional
        Defines a suggester that provides similar looking terms based on a provided text.
        - `text` (string) — optional
          Global suggest text, to avoid repetition when the same text is used in several suggesters
      - `terminate_after` (number · default: 0) — optional
        The maximum number of documents to collect for each shard.
If a query reaches this limit, Elasticsearch terminates the query early.
Elasticsearch collects documents before sorting.

IMPORTANT: Use with caution.
Elasticsearch applies this property to each shard handling the request.
When possible, let Elasticsearch perform early termination automatically.
Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.

If set to `0` (default), the query does not terminate early.
      - `timeout` (string) — optional
        The period of time to wait for a response from each shard.
If no response is received before the timeout expires, the request fails and returns an error.
Defaults to no timeout.
      - `track_scores` (boolean · default: false) — optional
        If `true`, calculate and return document scores, even if the scores are not used for sorting.
      - `version` (boolean · default: false) — optional
        If `true`, the request returns the document version as part of a hit.
      - `seq_no_primary_term` (boolean) — optional
        If `true`, the request returns sequence number and primary term of the last modification of each hit.
      - `stored_fields` (union oneOf) — optional
        A comma-separated list of stored fields to return as part of a hit.
If no fields are specified, no stored fields are included in the response.
If this field is specified, the `_source` property defaults to `false`.
You can pass `_source: true` to return both source fields and stored fields in the search response.
        One of: `string[]` or `string`
      - `pit` (object) — optional
        Limit the search to a point in time (PIT).
If you provide a PIT, you cannot specify an `<index>` in the request path.
        - `id` (string) — required
        - `keep_alive` (string) — optional
      - `runtime_mappings` (object) — optional
        One or more runtime fields in the search request.
These fields take precedence over mapped fields with the same name.
      - `stats` (string[]) — optional
        The stats groups to associate with the search.
Each group maintains a statistics aggregation for its associated searches.
You can retrieve these stats using the indices stats API.

## Response

`application/json`

- `acknowledged` (boolean)
  For a successful response, this value is always true. On failure, an exception is returned instead.
## Code examples

### Create a search template

#### Console

```console
POST _scripts/my-search-template
{
  "script": {
    "lang": "mustache",
    "source": {
      "query": {
        "match": {
          "message": "{{query_string}}"
        }
      },
      "from": "{{from}}",
      "size": "{{size}}"
    }
  }
}
```

#### JavaScript

```javascript
const response = await client.putScript({
  id: "my-search-template",
  script: {
    lang: "mustache",
    source: {
      query: {
        match: {
          message: "{{query_string}}",
        },
      },
      from: "{{from}}",
      size: "{{size}}",
    },
  },
});
```

#### Python

```python
resp = client.put_script(
    id="my-search-template",
    script={
        "lang": "mustache",
        "source": {
            "query": {
                "match": {
                    "message": "{{query_string}}"
                }
            },
            "from": "{{from}}",
            "size": "{{size}}"
        }
    },
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_scripts/my-search-template" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": {
      "lang": "mustache",
      "source": {
        "query": {
          "match": {
            "message": "{{query_string}}"
          }
        },
        "from": "{{from}}",
        "size": "{{size}}"
      }
    }
  }'
```

#### PHP

```php
$resp = $client->putScript([
    "id" => "my-search-template",
    "body" => [
        "script" => [
            "lang" => "mustache",
            "source" => [
                "query" => [
                    "match" => [
                        "message" => "{{query_string}}",
                    ],
                ],
                "from" => "{{from}}",
                "size" => "{{size}}",
            ],
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.put_script(
  id: "my-search-template",
  body: {
    "script": {
      "lang": "mustache",
      "source": {
        "query": {
          "match": {
            "message": "{{query_string}}"
          }
        },
        "from": "{{from}}",
        "size": "{{size}}"
      }
    }
  }
)
```

### Create a stored script

#### Console

```console
POST _scripts/my-stored-script
{
  "script": {
    "lang": "painless",
    "source": "Math.log(_score * 2) + params['my_modifier']"
  }
}
```

#### JavaScript

```javascript
const response = await client.putScript({
  id: "my-stored-script",
  script: {
    lang: "painless",
    source: "Math.log(_score * 2) + params['my_modifier']",
  },
});
```

#### Python

```python
resp = client.put_script(
    id="my-stored-script",
    script={
        "lang": "painless",
        "source": "Math.log(_score * 2) + params['my_modifier']"
    },
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_scripts/my-stored-script" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script":{"lang":"painless","source":"Math.log(_score * 2) + params[' \
  "'" \
  'my_modifier' \
  "'" \
  ']"}}'
```

#### Java

```java
client.putScript(p -> p
    .id("my-stored-script")
    .script(s -> s
        .lang("painless")
        .source(so -> so
            .scriptString("Math.log(_score * 2) + params['my_modifier']")
        )
    )
);
```

#### C#

```c#
var response = await client
    .PutScriptAsync(new PutScriptRequest()
    {
        Id = "my-stored-script",
        Script = new()
        {
            Language = ScriptLanguage.Painless,
            Source = "Math.log(_score * 2) + params['my_modifier']"
        }
    });
```

#### PHP

```php
$resp = $client->putScript([
    "id" => "my-stored-script",
    "body" => [
        "script" => [
            "lang" => "painless",
            "source" => "Math.log(_score * 2) + params['my_modifier']",
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.put_script(
  id: "my-stored-script",
  body: {
    "script": {
      "lang": "painless",
      "source": "Math.log(_score * 2) + params['my_modifier']"
    }
  }
)
```

## Response examples

#### 200

`application/json`

Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields.

```json
{
  "acknowledged": false
}
```