Introduction to Painless

Painless is a secure, performant, and flexible scripting language designed specifically for Elasticsearch. As the default scripting language for Elasticsearch, Painless lets you safely customize search behavior, data processing, and operations workflows across your Elastic Stack deployments.

Painless was introduced in Elasticsearch 5.0 as a replacement for Groovy, with improved security and performance compared to previous scripting solutions. Built on the Java Virtual Machine (JVM), Painless provides the familiar syntax of Java while improving the security boundaries with guardrails and a sandbox environment.

Unlike general scripting languages, Painless is purpose-built for Elasticsearch, enabling native performance while preventing unauthorized access to system resources. This architecture makes Painless both powerful for data manipulation and safe for production environments.

Common use cases include creating new fields based on existing data, calculating time differences between dates, extracting structured data from log messages, and implementing custom business logic in search scoring. For more examples, refer to our step-by-step tutorials.

Painless enables scripting in various contexts throughout Elasticsearch, such as:

• Custom search scoring based on business requirements
• Runtime field creation that calculates values during query execution
• Real-time filtering and transformation without reindexing data

• Transform documents during indexing
• Parse and extract structured data from unstructured fields
• Calculate metrics and summaries from your data

• Monitor data patterns and trigger alerts with Watcher solutions
• Transform alert payloads for targeted notifications and actions

You can write Painless scripts inline for quick operations or create reusable functions for your data operation. Here’s a sample Painless script applied to data transformation:

String productTitle(String manufacturer, String productName) {
  return manufacturer + " - " + productName;
}

return productTitle("Elitelligence", "Winter jacket");

This script demonstrates a few facets of Painless scripting:

• Function definition: Custom productTitle function with typed parameters
• Data types: String and integer parameter handling
• Return values: Function returns formatted string output

Painless provides three core benefits across all scripting contexts:

• Security: Fine-grained allowlists that prevent access to restricted Java APIs.
• Performance: Direct compilation to bytecode eliminates interpretation overhead and leverages JVM optimization.
• Flexibility: Wide range of scripting syntax and contexts across Elasticsearch, from search scoring to data processing to operational processing.

You can use Painless in multiple contexts throughout Elasticsearch:

• Dev Tools Console: for interactive script development and testing
• Ingest pipelines: for data transformation during indexing
• Search queries: for custom scoring and script fields
• Runtime fields: for dynamic field creation
• Update API: for document modification
• Watcher: for alert conditions and actions

Write your first Painless script by trying out our guide or jump into one of our tutorials for real-world examples using sample data.

For complete syntax and language features, refer to the Painless language specification.

Once you get started, refer to Debug Painless scripts in Elasticsearch for helpful tips about how to resolve common scripting errors.