Script contexts

A script runs in a script context. The context determines the variables the script receives, the value it must return, and the permitted languages. A script that is valid in one context is often invalid in another, which is why a script that works as a script field can fail when moved into an update.

Context is the unit that several other features are defined against. Compilation limits and caches are tracked per context, script.allowed_contexts restricts scripting by context, and a stored script can be compiled against a named context when you save it.

Listing the contexts in your cluster

Installed plugins register their own contexts, so the authoritative list is the one your cluster reports. To list all contexts in your cluster, use the Get Script Contexts API:

GET _script_context

Each entry names a context and lists its methods. The execute method provides the script’s return type and any arguments passed to it, and each get method corresponds to a variable the script can read:

{
  "contexts": [
    {
      "name": "aggregation_selector",
      "methods": [
        {
          "name": "execute",
          "return_type": "boolean",
          "params": []
        },
        {
          "name": "getParams",
          "return_type": "java.util.Map",
          "params": []
        }
      ]
    }
  ]
}

The response is long, because it covers every context. To list the context names alone, use the filter_path query parameter:

GET _script_context?filter_path=contexts.name

Contexts by task

The following sections group the contexts by task. The params variable is available in every context and is omitted from the descriptions.

Search and scoring

The following table lists the contexts that run during a search.

The score context supplies _score as well as returning a score, so a script can build on the relevance that the query computed. See Accessing the relevance score.

Aggregations

The following table lists the aggregation contexts.

The four scripted metric contexts run in sequence and communicate through state, which aggs_init creates, aggs_map fills per document, aggs_combine reduces per shard, and aggs_reduce receives as the list states.

Ingestion and updates

The following table lists the contexts that run while a document is indexed or updated.

The document-modifying contexts expose document data through ctx. The doc variable is unavailable, so a script that references it in an update fails to compile. See Update scripts.

Templates and testing

The following table lists the remaining general-purpose contexts.

Plugin contexts

The following table lists contexts registered by plugins. They appear only when the corresponding plugin is installed.

Language support by context

Painless runs in every context. The special-purpose languages are restricted, so a script in one of them fails outside its supported contexts. Use the Get Script Languages API to see the mapping for your cluster:

GET _script_language

The following table summarizes the languages you can write scripts in.

The expression language is unavailable in update, ingest, and string_sort because it cannot read the _source and cannot return a string. See Limitations.

Writing a script for a context

Matching your script to the context means supplying the right return value and using the variables that context provides. The derived_field context illustrates both: it returns void and reports its value by calling emit() instead of returning it.

The following search defines a derived field that labels each product by price tier, using the scripting-products index created in Test setup:

GET scripting-products/_search
{
  "_source": false,
  "derived": {
    "price_tier": {
      "type": "keyword",
      "script": { "source": "emit(doc['price'].value >= 200 ? 'premium' : 'standard')" }
    }
  },
  "query": { "match_all": {} },
  "sort": [{ "sku": "asc" }],
  "fields": ["price_tier"]
}

Each result carries the emitted value:

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4,
      "relation": "eq"
    },
    "max_score": null,
    "hits": [
      {
        "_index": "scripting-products",
        "_id": "3",
        "_score": null,
        "fields": {
          "price_tier": [
            "standard"
          ]
        },
        "sort": [
          "ACC-2001"
        ]
      },
      {
        "_index": "scripting-products",
        "_id": "1",
        "_score": null,
        "fields": {
          "price_tier": [
            "premium"
          ]
        },
        "sort": [
          "AUD-1001"
        ]
      },
      {
        "_index": "scripting-products",
        "_id": "2",
        "_score": null,
        "fields": {
          "price_tier": [
            "standard"
          ]
        },
        "sort": [
          "AUD-1002"
        ]
      },
      {
        "_index": "scripting-products",
        "_id": "4",
        "_score": null,
        "fields": {
          "price_tier": [
            "premium"
          ]
        },
        "sort": [
          "DSP-3001"
        ]
      }
    ]
  }
}

Compiling a stored script against a context

Naming a context when you store a script makes OpenSearch compile it immediately, so a script that is invalid for that context fails on the store request rather than on the first search that uses it. See Working with stored scripts.

Restricting and configuring by context

The following settings operate on contexts:

• script.allowed_contexts limits the cluster to a named set of contexts, which reduces where a script can run at all. See Restricting the allowed contexts.
• script.context.<context>.max_compilations_rate, .cache_max_size, and .cache_expire configure compilation and caching for one context without affecting the others. See Script context settings.

Related documentation

• Painless language reference
• Accessing document fields in scripts
• Get Script Contexts API