IP range aggregation

IP range aggregation #

A multi-bucket aggregation like range, but for IP addresses — buckets are CIDR masks or from/to IP bounds. It answers network-shape questions: which subnet does this traffic belong to, and how much of it is in the private ranges versus the internet.

How it works #

The field’s string values are parsed into 128-bit numbers, with IPv4 mapped into the IPv6 space as ::ffff:a.b.c.d — an order-preserving numeric comparison. From/to buckets are half-open on that number (from inclusive, to exclusive), so IPv4 and IPv6 bounds interoperate; 10.0.0.0 sorts before 192.168.0.0 sorts before 2001:db8::.

Percentiles aggregation

Percentiles aggregation #

A multi-value metrics aggregation that calculates one or more percentiles over numeric values extracted from the aggregated documents.

Percentiles show the point at which a certain percentage of observed values occur. For example, the 95th percentile is the value which is greater than 95% of the observed values.

Percentiles are often used to find outliers. In normal distributions, the 0.13th and 99.87th percentiles represents three standard deviations from the mean. Any data which falls outside three standard deviations is often considered an anomaly.

Cumulative sum aggregation

Cumulative sum aggregation #

A parent pipeline aggregation adding a running total column to each bucket — the metric plus every earlier bucket’s. A histogram says what each period brought in; the cumulative sum says where the whole span stands at every point along it, without a second query or client-side arithmetic.

"running": { "cumulative_sum": { "buckets_path": "revenue" } }

How it works #

cumulative_sum is declared inside the multi-bucket aggregation it decorates, next to the metric it consumes. After the buckets are built, the engine walks them in order and attaches the running total to each bucket under the pipeline’s own name:

Filter aggregation

Filter aggregation #

A single-bucket aggregation that narrows the documents a nested aggregation runs on, with a query acting as the filter condition. Where the request’s query scopes everything, filter carves out one named sub-scope inside the aggregation tree — the aggregation equivalent of a WHERE clause.

How it works #

Every matching document is tested against the condition; those that pass form the bucket. The response is a single-bucket object carrying the filtered doc_count plus any nested aggregation results:

Percentile ranks aggregation

Percentile ranks aggregation #

A multi-value metrics aggregation that answers the inverse of percentiles: for each value you provide, what percentage of documents is at or below it.

How it works #

The engine collects every value of the field and sorts it once. For each requested value v, the rank is the fraction of collected values that are less than or equal to v:

rank(v) = count(value <= v) / n * 100

The comparison is inclusive — a document exactly at v counts toward its own rank, so the rank of the maximum value is 100, not 100 − 1/n. With no values at all (empty result set, or every document missing the field) each rank is null.

Boxplot aggregation

Boxplot aggregation #

A multi-value metrics aggregation producing the five-number summary of a distribution: minimum, lower quartile (q1), median (q2), upper quartile (q3) and maximum, plus whiskers.

How it works #

The engine collects and sorts the values of the field, then:

• min / max are the observed extremes (after missing substitution).
• q1, q2, q3 are the 25th, 50th and 75th percentiles, computed with the same TDigest arithmetic percentiles uses — weight-1 centroids at (i + 0.5) / n with linear interpolation between the two bracketing values. A quartile can therefore land between observed values (q2 of the sale prices is 22.5, between 15 and 30).
• The whiskers extend from the quartiles by 1.5 × IQR, where IQR = q3 − q1, and are clamped to the data: lower = max(q1 − 1.5·IQR, min), upper = min(q3 + 1.5·IQR, max). Values beyond the unclamped whisker positions are the conventional boxplot outliers.

Clamping means on a compact distribution the whiskers simply touch the extremes — over the teaching sales prices the whiskers land exactly on min and max. If no document has a value for the field, all seven numbers are 0.

Cumulative cardinality aggregation

Cumulative cardinality aggregation #

A parent pipeline aggregation reporting a running total of a per-bucket distinct count — typically a cardinality metric — answering “how many unique values have been counted up to and including each bucket”.

"seen_so_far": {
  "cumulative_cardinality": { "buckets_path": "buyers" }
}

How it works #

cumulative_cardinality is declared inside the multi-bucket aggregation it decorates, next to the metric it consumes. The engine walks the finished buckets in order and attaches the running total of the referenced values under the pipeline’s own name — mechanically the same accumulation as cumulative_sum; only the intended input (a per-bucket distinct count) differs.

Filters aggregation

Filters aggregation #

A multi-bucket aggregation where each bucket is defined by a named filter — all filters run over the same document set, giving per-filter counts (and nested sub-aggregations) side by side. It is the aggregation form of a KPI panel: one request, several named slices.

How it works #

The filters object maps bucket names to query clauses. Every matching document is tested against EVERY filter independently, so buckets may overlap — a document counts toward each filter it satisfies, and toward none when it satisfies none. Bucket counts therefore do not sum to the hit total in general.

Adjacency matrix aggregation

Adjacency matrix aggregation #

A multi-bucket aggregation returning every named filter’s document set plus their pairwise INTERSECTIONS — the cross product view of several filters. Where filters answers each filter separately, this one also tells you how much they overlap, which is exactly what co-occurrence analysis needs.

How it works #

Each named filter is evaluated against every candidate document, so a document can carry several filter flags at once. The engine then emits one bucket per non-empty filter (keyed by its name) and one bucket per non-empty pair, keyed a&b with the two names in alphabetical order. Intersections beyond pairs — no a&b&c triples — are not computed, and empty buckets are skipped entirely, so the bucket count tops out at n·(n−1)/2 + n.

Serial diff aggregation

Serial diff aggregation #

A parent pipeline aggregation computing the difference between each bucket’s metric and the bucket lag positions back — a differencing transform that turns a trending or seasonal series into its own period-over-period change.

"wowl": { "serial_diff": { "buckets_path": "revenue", "lag": 2 } }

How it works #

serial_diff is declared inside the multi-bucket aggregation it decorates, next to the metric it consumes. After the buckets are built, the engine walks them in order and attaches current − value_lag_buckets_back to each bucket under the pipeline’s own name: