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::.

A bucket may instead be a mask (CIDR): IPv4 masks compare the 32-bit address against the prefix (10.0.0.0/8, 192.168.0.0/16), while IPv6 masks compare the full 128 bits — and under an IPv6 mask an IPv4 literal is compared as its zero-padded 32-bit value, not as ::ffff:-mapped, per the official specification’s semantics for mixed families.

Every declared range returns exactly one bucket, in declaration order, even at doc_count: 0. The bucket key is your label, the mask string verbatim ("10.0.0.0/8"), or the built "<from>-<to>" form with * for omitted sides.

Example #

The demo dataset has no IP-typed field (hosts are names like web-01), so the bucket is structurally valid but empty:

On an ip field, each bucket counts the addresses inside its subnet.

Use cases #

• Subnet attribution. Count requests per /16 or /24 to see which network segments generate traffic — one declared mask per segment, one bucket per mask, zeros included.
• Private versus public split. 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 versus an unbounded catch-all bucket gives the internal/external ratio in a single response.
• Security triage. Ring-fence a suspect block (from/to bounds around the offending addresses) and watch its share per time window under a date_histogram parent.
• Mixed-family inventories. Because comparison happens on the v4-mapped 128-bit number, one aggregation can bucket IPv4 and IPv6 clients together without family-specific queries.

Parameters for ip_range #

• field
  (Required, string) IP-typed field you wish to aggregate (string values; non-IP strings are skipped).
• ranges
  (Required, object array) Buckets as { "mask": "cidr" } or { "from": "ip", "to": "ip" } (from inclusive, to exclusive); key names a bucket.
• aggs
  (Optional, object) Nested sub-aggregations, computed per bucket.

Related #

• range — the numeric-field sibling.
• date_range — named bands over date fields.
• geo_distance — rings around a point, the geo sibling of this family.