Sandboxed scripting — scripted_metric, script_fields, script_score

Sandboxed scripting — scripted_metric, script_fields, script_score #

Scripts landed across the whole request path — the engine runs the examples from the Elasticsearch docs unmodified. The engine is Rhai rather than Painless, but doc['x'].value, _score and params.<name> mean what they mean there.

Aggregations. scripted_metric runs your own four-phase map/reduce — init_script, map_script, combine_script, reduce_script — with per-segment states folded at the end. The single-value metric aggs (sum, avg, min, max, cardinality) accept a script in place of a field ( details), and pipeline aggregations keep their buckets_path arithmetic.

Max bucket aggregation

Max bucket aggregation #

A sibling pipeline aggregation identifying the largest per-bucket metric value — e.g. the best-performing group. Bucket aggregations can sort their own output, but only inside one request’s bucket list; max_bucket lifts the winning number out as a single headline metric next to the breakdown.

"best_seller": { "max_bucket": { "buckets_path": "per_type>revenue" } }

How it works #

max_bucket is declared next to the bucket aggregation it consumes and runs after every regular aggregation — including the distributed merge — has finished. It walks the parent’s finished buckets, collects one number per bucket, and returns their maximum as a single-value metric ({"value": 1800}) placed alongside the parent. Only the value is returned — not which bucket produced it; read the parent’s bucket list (or sort it with bucket_sort) when you need the winner’s key.

Min aggregation

Min aggregation #

A single-value metrics aggregation that keeps track and returns the minimum value among numeric values extracted from the aggregated documents. It answers “how low does this field go” over any query — the floor of a price range, the earliest timestamp in a window, the cheapest item that matches a filter.

How it works #

The engine walks the matching documents once, keeping the smallest value seen; any larger value costs one comparison. Values are coerced to doubles as they are read — integers, floats and booleans (true = 1, false = 0) qualify, non-numeric values such as keyword strings do not.

Significant terms aggregation

Significant terms aggregation #

A multi-bucket aggregation returning terms that are unusually frequent in the current scope (foreground) compared with the whole index (background) — the classic “what’s special about this subset” query.

In this engine significant_terms currently approximates that idea by foreground frequency: it ranks the scope’s values by their in-scope doc_count, without computing background statistics. Nest it under a query or a parent bucket to scope the foreground set; the values that dominate that scope come out on top.

Range aggregation

Range aggregation #

A multi-bucket aggregation over numeric fields where each bucket is a user-defined range. It answers “how many documents fall in each band?” — the bands are yours to name and place, unlike the regular grid of histogram.

How it works #

Each range is a half-open window: from is inclusive, to is exclusive, and either side may be omitted for unbounded. A document whose value v satisfies from <= v < to counts in that range — and because the test is per range, overlapping definitions put one document in several buckets at once.

Stats bucket aggregation

Stats bucket aggregation #

A sibling pipeline aggregation returning count/min/max/avg/sum of a metric across buckets — the stats of the per-bucket values. One call replaces four: where avg_bucket, min_bucket and max_bucket each reduce the bucket list to a single number, stats_bucket returns the whole summary object beside the aggregation it describes.

"day_stats": { "stats_bucket": { "buckets_path": "per_day>revenue" } }

How it works #

stats_bucket is declared next to the bucket aggregation it consumes and runs after every regular aggregation — including the distributed merge — has finished. It walks the parent’s finished buckets, collects one number per bucket, and emits the stats result object over that sample:

Sum aggregation

Sum aggregation #

A single-value metrics aggregation that sums up numeric values that are extracted from the aggregated documents. It turns “how much in total” into one number — revenue, bytes, durations, counts of units — without shipping the matching documents anywhere.

How it works #

The engine walks the matching documents once, adding each value to a running total. Values are coerced to doubles as they are read — integers, floats and booleans (true = 1, false = 0) contribute, non-numeric values such as keyword strings do not.

Date range aggregation

Date range aggregation #

A multi-bucket aggregation like range, but for date fields. Each bucket is a from/to period you name — “before the launch”, “launch week”, “after” — which is the shape reporting questions naturally take, rather than the uniform grid of date_histogram.

How it works #

Bounds are epoch milliseconds: from accepts a number (or a numeric string) and is inclusive, to is exclusive, and either may be omitted for an open-ended period. Date strings like "2024-06-04" are not parsed by the aggregation — convert them to epoch millis first (the teaching examples below show the constants).

Extended stats bucket aggregation

Extended stats bucket aggregation #

A sibling pipeline aggregation extending stats_bucket with variance, standard deviation and their sampling variants of the per-bucket metric distribution. Use it when the spread of the per-bucket numbers matters — how uneven the days or categories are — not just their min/avg/max envelope.

"day_xstats": {
  "extended_stats_bucket": { "buckets_path": "per_day>revenue" }
}

How it works #

extended_stats_bucket is declared next to the bucket aggregation it consumes and runs after every regular aggregation — including the distributed merge — has finished. It walks the parent’s finished buckets, collects one number per bucket, and emits an extended_stats-shaped result over that sample:

Value count aggregation

Value count aggregation #

A single-value metrics aggregation that counts the number of values that are extracted from the aggregated documents. Typically, this aggregator will be used in conjunction with other single-value aggregations. For example, when computing the avg one might be interested in the number of values the average is computed over.

value_count does not de-duplicate values, so even if a field has duplicates each value will be counted individually.