<commit_before>[[painless-execute-api]]
=== Painless execute API

experimental[The painless execute api is new and the request / response format may change in a breaking way in the future]

The Painless execute API allows an arbitrary script to be executed and a result to be returned.

[[painless-execute-api-parameters]]
.Parameters
[options="header"]
|======
| Name              | Required  | Default                | Description
| `script`          | yes       | -                      | The script to execute
| `context`         | no        | `painless_test`        | The context the script should be executed in.
| `context_setup`   | no        | -                      | Additional parameters to the context.
|======

==== Contexts

Contexts control how scripts are executed, what variables are available at runtime and what the return type is.

===== Painless test context

The `painless_test` context executes scripts as is and do not add any special parameters.
The only variable that is available is `params`, which can be used to access user defined values.
The result of the script is always converted to a string.
If no context is specified then this context is used by default.

*Example*

Request:

[source,console]
----------------------------------------------------------------
POST /_scripts/painless/_execute
{
  "script": {
    "source": "params.count / params.total",
    "params": {
      "count": 100.0,
      "total": 1000.0
    }
  }
}
----------------------------------------------------------------

Response:

[source,console-result]
--------------------------------------------------
{
  "result": "0.1"
}
--------------------------------------------------

===== Filter context

The `filter` context executes scripts as if they were executed inside a `script` query.
For testing purposes a document must be provided that will be indexed temporarily in-memory and
is accessible to the script being tested. Because of this the _source, stored fields and doc values
are available in the script being tested.

The following parameters may be specified in `context_setup` for a filter context:

document:: Contains the document that will be temporarily indexed in-memory and is accessible from the script.
index:: The name of an index containing a mapping that is compatible with the document being indexed.

*Example*

[source,console]
----------------------------------------------------------------
PUT /my-index
{
  "mappings": {
    "properties": {
      "field": {
        "type": "keyword"
      }
    }
  }
}

POST /_scripts/painless/_execute
{
  "script": {
    "source": "doc['field'].value.length() <= params.max_length",
    "params": {
      "max_length": 4
    }
  },
  "context": "filter",
  "context_setup": {
    "index": "my-index",
    "document": {
      "field": "four"
    }
  }
}
----------------------------------------------------------------

Response:

[source,console-result]
--------------------------------------------------
{
  "result": true
}
--------------------------------------------------


===== Score context

The `score` context executes scripts as if they were executed inside a `script_score` function in
`function_score` query.

The following parameters may be specified in `context_setup` for a score context:

document:: Contains the document that will be temporarily indexed in-memory and is accessible from the script.
index:: The name of an index containing a mapping that is compatible with the document being indexed.
query:: If `_score` is used in the script then a query can specified that will be used to compute a score.

*Example*

[source,console]
----------------------------------------------------------------
PUT /my-index
{
  "mappings": {
    "properties": {
      "field": {
        "type": "keyword"
      },
      "rank": {
        "type": "long"
      }
    }
  }
}


POST /_scripts/painless/_execute
{
  "script": {
    "source": "doc['rank'].value / params.max_rank",
    "params": {
      "max_rank": 5.0
    }
  },
  "context": "score",
  "context_setup": {
    "index": "my-index",
    "document": {
      "rank": 4
    }
  }
}
----------------------------------------------------------------

Response:

[source,console-result]
--------------------------------------------------
{
  "result": 0.8
}
--------------------------------------------------
<commit_msg>[DOCS] Fix typos in Painless execute API docs(#47518)<commit_after>[[painless-execute-api]]
=== Painless execute API

experimental[The painless execute api is new and the request / response format may change in a breaking way in the future]

The Painless execute API allows an arbitrary script to be executed and a result to be returned.

[[painless-execute-api-parameters]]
.Parameters
[options="header"]
|======
| Name              | Required  | Default                | Description
| `script`          | yes       | -                      | The script to execute.
| `context`         | no        | `painless_test`        | The context the script should be executed in.
| `context_setup`   | no        | -                      | Additional parameters to the context.
|======

==== Contexts

Contexts control how scripts are executed, what variables are available at runtime and what the return type is.

===== Painless test context

The `painless_test` context executes scripts as is and does not add any special parameters.
The only variable that is available is `params`, which can be used to access user defined values.
The result of the script is always converted to a string.
If no context is specified then this context is used by default.

*Example*

Request:

[source,console]
----------------------------------------------------------------
POST /_scripts/painless/_execute
{
  "script": {
    "source": "params.count / params.total",
    "params": {
      "count": 100.0,
      "total": 1000.0
    }
  }
}
----------------------------------------------------------------

Response:

[source,console-result]
--------------------------------------------------
{
  "result": "0.1"
}
--------------------------------------------------

===== Filter context

The `filter` context executes scripts as if they were executed inside a `script` query.
For testing purposes, a document must be provided so that it will be temporarily indexed in-memory and
is accessible from the script. More precisely, the _source, stored fields and doc values of such a 
document are available to the script being tested.

The following parameters may be specified in `context_setup` for a filter context:

document:: Contains the document that will be temporarily indexed in-memory and is accessible from the script.
index:: The name of an index containing a mapping that is compatible with the document being indexed.

*Example*

[source,console]
----------------------------------------------------------------
PUT /my-index
{
  "mappings": {
    "properties": {
      "field": {
        "type": "keyword"
      }
    }
  }
}

POST /_scripts/painless/_execute
{
  "script": {
    "source": "doc['field'].value.length() <= params.max_length",
    "params": {
      "max_length": 4
    }
  },
  "context": "filter",
  "context_setup": {
    "index": "my-index",
    "document": {
      "field": "four"
    }
  }
}
----------------------------------------------------------------

Response:

[source,console-result]
--------------------------------------------------
{
  "result": true
}
--------------------------------------------------


===== Score context

The `score` context executes scripts as if they were executed inside a `script_score` function in
`function_score` query.

The following parameters may be specified in `context_setup` for a score context:

document:: Contains the document that will be temporarily indexed in-memory and is accessible from the script.
index:: The name of an index containing a mapping that is compatible with the document being indexed.
query:: If `_score` is used in the script then a query can specify that it will be used to compute a score.

*Example*

[source,console]
----------------------------------------------------------------
PUT /my-index
{
  "mappings": {
    "properties": {
      "field": {
        "type": "keyword"
      },
      "rank": {
        "type": "long"
      }
    }
  }
}


POST /_scripts/painless/_execute
{
  "script": {
    "source": "doc['rank'].value / params.max_rank",
    "params": {
      "max_rank": 5.0
    }
  },
  "context": "score",
  "context_setup": {
    "index": "my-index",
    "document": {
      "rank": 4
    }
  }
}
----------------------------------------------------------------

Response:

[source,console-result]
--------------------------------------------------
{
  "result": 0.8
}
--------------------------------------------------

{'fraction_non_alphanumeric': 0.24931693989071038, 'fraction_numerical': 0.004439890710382513, 'mean_word_length': 1.718131188118812, 'pattern_counts': {'":': 72, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6613021', 'n_tokens_mistral': 2234, 'n_tokens_neox': 2152, 'n_words': 839}