IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Painless Debugging Appendix A: Deleted pages »

› ›

Painless execute API

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Painless execute API

edit

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.

Table 1. Parameters

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

edit

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

Painless test context

edit

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:

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

Response:

{
  "result": "0.1"
}

Filter context

edit

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

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:

{
  "result": true
}

Score context

edit

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

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:

{
  "result": 0.8
}

« Painless Debugging Appendix A: Deleted pages »