Elasticsearch Scripting Explained: Compute Fields, Custom Scoring, Best Practices

Introduction

Elasticsearch scripts are a powerful tool for performing dynamic calculations and data processing during query and indexing operations. Since version 7.6 the scripting subsystem has been optimized for greater flexibility and efficiency.

Script Usage Example

The following function_score query demonstrates how to adjust product ranking based on price, rating, stock, sales count, and an external freshness factor.

{
  "query": {
    "function_score": {
      "query": { "match_all": {} },
      "functions": [
        {
          "script_score": {
            "script": {
              "source": """
                double baseScore = _score;
                double price = doc['price'].value;
                double rating = doc['rating'].value;
                int stock = doc['stock'].value;
                long salesCount = doc['salesCount'].value;
                double priceWeight = 0.1;
                double ratingWeight = 0.3;
                double stockWeight = 0.2;
                double salesWeight = 0.1;
                double freshnessFactor = 0.3;
                double priceScore = 1.0 / (price / 100.0 + 1.0);
                double ratingScore = rating;
                double stockScore = stock < 10 ? 1.0 : (stock < 100 ? 0.9 : (stock < 500 ? 0.8 : 0.5));
                double salesScore = Math.log10(salesCount + 1);
                double freshness = params.freshness;
                double totalScore = baseScore * freshnessFactor * freshness
                                   + priceScore * priceWeight
                                   + ratingScore * ratingWeight
                                   + stockScore * stockWeight
                                   + salesScore * salesWeight;
                return totalScore;
              """,
              "params": { "freshness": 0.9 }
            }
          }
        }
      ],
      "score_mode": "sum",
      "boost_mode": "replace"
    }
  }
}

The script performs the following steps:

Initialises a base score from the document's original relevance score ( _score).

Extracts field values: price, rating, stock, and salesCount.

Defines weights for each factor.

Computes individual scores – price (inverse relation), rating (direct), stock (piecewise function), sales (log‑scaled) – and incorporates an external freshness parameter.

Aggregates the weighted scores into a final total score used for sorting.

Aggregation Script Example

The script below calculates a weighted average sales amount per product category.

POST /sales_records/_search
{
  "size": 0,
  "aggs": {
    "categories": {
      "terms": { "field": "product_category.keyword", "size": 10 },
      "aggs": {
        "weighted_sales": {
          "sum": { "script": { "source": "doc['sales_amount'].value * doc['sales_weight'].value" } }
        },
        "sum_of_weights": { "sum": { "field": "sales_weight" } },
        "weighted_average_sales": {
          "bucket_script": {
            "buckets_path": { "weightedSales": "weighted_sales", "totalWeight": "sum_of_weights" },
            "script": "params.weightedSales / params.totalWeight"
          }
        }
      }
    }
  }
}

Setting "size": 0 returns only the aggregation results. The query groups records by product_category, computes weighted sales and total weight for each bucket, then derives the weighted average using a bucket_script.

Script Execution Process

Parsing : The request containing a script is parsed according to the chosen language (e.g., Painless). Syntax and lexical analysis ensure validity.

Compilation : Some languages require compilation; Painless is interpreted but still undergoes optimisation.

Execution : The script runs in a sandboxed environment with restricted system access. It can read document fields, perform arithmetic, and call built‑in functions, influencing query results or document updates.

Caching : Parsed and compiled scripts are cached, allowing subsequent requests to reuse them without re‑parsing, improving latency.

Common Use Cases

Script fields : Dynamically generate fields at query time, e.g., total_price = doc['price'].value * doc['quantity'].value.

Custom scoring : Adjust document scores with scripts, such as multiplying likes by a weight parameter.

Update scripts : Apply complex business logic during updates, e.g., incrementing a counter field via _update_by_query.

Best Practices

Keep scripts simple and clear to avoid performance penalties and debugging difficulty.

Avoid time‑consuming operations inside scripts; offload heavy work to the application layer when possible.

Leverage script caching by reusing scripts via parameters rather than redefining them per request.

Use a safe, sandboxed language (Painless) and regularly audit scripts for security risks.