Run a script

POST also GET /_scripts/painless/_execute

Runs a script and returns a result. Use this API to build and test scripts, such as when defining a script for a runtime field. This API requires very few dependencies and is especially useful if you don't have permissions to write documents on a cluster.

The API uses several contexts, which control how scripts are run, what variables are available at runtime, and what the return type is.

Each context requires a script, but additional parameters depend on the context you're using for that script.

Request

context enum PainlessContext · default: painless_test

The context that the script should run in. NOTE: Result ordering in the field contexts is not guaranteed.

Supported values include:

painless_test: The default context if no other context is specified.
filter: Treats scripts as if they were run inside a script query.
score: Treats scripts as if they were run inside a script_score function in a function_score query.
boolean_field: The context for boolean fields. The script returns a true or false response.
date_field: The context for date fields. emit takes a long value and the script returns a sorted list of dates.
double_field: The context for double numeric fields. The script returns a sorted list of double values.
geo_point_field: The context for geo-point fields. emit takes two double parameters, the latitude and longitude values, and the script returns an object in GeoJSON format containing the coordinates for the geo point.
ip_field: The context for ip fields. The script returns a sorted list of IP addresses.
keyword_field: The context for keyword fields. The script returns a sorted list of string values.
long_field: The context for long numeric fields. The script returns a sorted list of long values.
composite_field: The context for composite runtime fields. The script returns a map of values.

Values: painless_test filter score boolean_field date_field double_field geo_point_field ip_field keyword_field long_field composite_field

context_setup {} PainlessContextSetup

Additional parameters for the context. NOTE: This parameter is required for all contexts except painless_test, which is the default if no value is provided for context.

script string Script

The Painless script to run.

Response

application/json

Examples

Run POST /_scripts/painless/_execute. The painless_test context is the default context. It runs scripts without additional 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.

Request Console 1 / 8 languages

Console Kibana Dev Tools

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

JavaScript Elasticsearch JavaScript Client

const response = await client.scriptsPainlessExecute({
  script: {
    source: "params.count / params.total",
    params: {
      count: 100,
      total: 1000,
    },
  },
});

Python Elasticsearch Python Client

resp = client.scripts_painless_execute(
    script={
        "source": "params.count / params.total",
        "params": {
            "count": 100,
            "total": 1000
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_scripts/painless/_execute" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": {
      "source": "params.count / params.total",
      "params": {
        "count": 100,
        "total": 1000
      }
    }
  }'

Java Elasticsearch Java Client

client.scriptsPainlessExecute(s -> s
    .script(sc -> sc
        .source(so -> so
            .scriptString("params.count / params.total")
        )
        .params(Map.of("total", JsonData.fromJson("1000"),"count", JsonData.fromJson("100")))
    )
);

C# Elasticsearch .NET Client

var response = await client
    .ScriptsPainlessExecuteAsync<MyDocument, MyDocument>(d1 => d1
        .Script(d2 => d2
            .Params(new Dictionary<string, object>()
            {
                { "count", 100 },
                { "total", 1000 }
            })
            .Source("params.count / params.total")
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->scriptsPainlessExecute([
    "body" => [
        "script" => [
            "source" => "params.count / params.total",
            "params" => [
                "count" => 100,
                "total" => 1000,
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.scripts_painless_execute(
  body: {
    "script": {
      "source": "params.count / params.total",
      "params": {
        "count": 100,
        "total": 1000
      }
    }
  }
)

Response

{
  "result": "0.1"
}

Run POST /_scripts/painless/_execute with a filter context. It treats scripts as if they were run 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.

Request Console 1 / 2 languages

Console Kibana Dev Tools

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

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_scripts/painless/_execute" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": {
    "source": "doc['\''field'\''].value.length() <= params.max_length",
    "params": {
      "max_length": 4
    }
  },
  "context": "filter",
  "context_setup": {
    "index": "my-index-000001",
    "document": {
      "field": "four"
    }
  }
}'

Response

{
  "result": true
}

Run POST /_scripts/painless/_execute with a score context. It treats scripts as if they were run inside a script_score function in a function_score query.

Request Console 1 / 2 languages

Console Kibana Dev Tools

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

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_scripts/painless/_execute" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "script": {
    "source": "doc['\''rank'\''].value / params.max_rank",
    "params": {
      "max_rank": 5.0
    }
  },
  "context": "score",
  "context_setup": {
    "index": "my-index-000001",
    "document": {
      "rank": 4
    }
  }
}'

Response

{
  "result": 0.8
}

Request { context , context_setup , script , }

Response

Request