elasticsearch
Loading

Painless contexts

Serverless Stack

In Painless, a context defines where and how your script runs in Elasticsearch. Each context determines three key aspects: which variables are available to your script (such as doc, ctx, or _source), which Java classes and methods your script can access for security, and what type of value your script should return.

Contexts are runtime environments that determine script behavior within specific Elasticsearch operations. Unlike traditional scripting languages, where code runs consistently everywhere, Painless scripts are context-aware: the same syntax can access different variables and produce different results depending on the Elasticsearch operation that calls it.

Painless supports scripting across numerous Elasticsearch operations, from search scoring to document processing to aggregation calculations. Each operation requires different capabilities; search scripts need read-only field access, while ingest scripts need document modification abilities. This diversity of requirements creates the need for specialized contexts.

Contexts ensure appropriate access and capabilities for each Elasticsearch operation while maintaining security and performance by providing exactly the inputs and APIs needed for a specific task through fine-grained allowlists and optimized data access patterns.

For example, search scoring contexts provide document fields as input and generate numerical scores as output, while ingest contexts provide documents as input for modification and generate transformed documents as output. Even if some contexts appear to be similar, each has tools and restrictions designed for a specific purpose.

Contexts determine how you can access document data in Painless scripts:

doc values:
Read-only field access using columnar storage for search, aggregation, and sorting context
ctx access:
Document modification capabilities in update, ingest, and reindex context
_source access:
Complete document JSON for runtime fields and transformations
params
User-defined parameters passed into scripts, available across all contexts

For detailed data access patterns and examples, refer to Painless syntax-context bridge.

While Painless supports more than twenty specific contexts, they operate within four categories.

Document Processing
Transform and extract data from existing documents without modifying the original content. Use runtime fields, ingest processors, and field scripts to create computed fields or parse log data.
Document Modification
Change or update document context permanently in the index. Use update scripts, update by query, and reindex scripts to modify fields or restructure documents.
Search Enhancement
Customize search behavior, scoring, or sorting without changing the indexed documents. Use filter scripts, and sort scripts for custom relevance or dynamic filtering.
Advanced Operations
Implement specialized functionality such as custom aggregations or monitoring conditions. Use metric aggregation, bucket aggregation, and Watcher scripts for complex calculations and alerting.
Name Painless documentation Elasticsearch documentation
Runtime field Painless documentation Elasticsearch documentation
Field Painless documentation Elasticsearch documentation
Ingest processor Painless documentation Elasticsearch documentation
Filter Painless documentation Elasticsearch documentation
Score Painless documentation Elasticsearch documentation
Sort Painless documentation Elasticsearch documentation
Update Painless documentation Elasticsearch documentation
Update by query Painless documentation Elasticsearch documentation
Reindex Painless documentation Elasticsearch documentation
Similarity Painless documentation Elasticsearch documentation
Weight Painless documentation Elasticsearch documentation
Minimum should match Painless documentation Elasticsearch documentation
Metric aggregation initialization Painless documentation Elasticsearch documentation
Metric aggregation map Painless documentation Elasticsearch documentation
Metric aggregation combine Painless documentation Elasticsearch documentation
Metric aggregation reduce Painless documentation Elasticsearch documentation
Bucket script aggregation Painless documentation Elasticsearch documentation
Bucket selector aggregation Painless documentation Elasticsearch documentation
Watcher condition Painless documentation Elasticsearch documentation
Watcher transform Painless documentation Elasticsearch documentation

Before using a Painless context, configure the example data. Each context example is configured to operate on this data.