Rate aggregation #

A single-value metrics aggregation that reduces a numeric field inside date_histogram buckets (per-interval totals), intended for counters that accumulate over time.

How it works #

rate reads one field and reduces it per bucket, with three reduction modes selected by mode:

• sum (default) — the bucket’s total of the field; identical to sum.
• value_count — how many values the field has in the bucket.
• avg — the bucket’s mean of the field.

If field is omitted entirely, the aggregation counts the documents in the bucket (the value_count shape over _doc).

The unit option (second, minute, hour, day, week, month, quarter, year; default month) is accepted for compatibility, but this engine does not rescale per-bucket values by the interval length: each bucket reports its own sum/value_count/avg as-is. Buckets whose interval is a calendar month (or any other width) therefore compare by raw totals; normalize by interval length downstream if you need per-unit rates.

Example #

Outside a histogram, rate equals sum — here the total amount, 6750. Inside a date_histogram it returns each bucket’s total:

POST /sales/_search
{
  "aggs": {
    "per_month": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "month"
      },
      "aggs": {
        "amount_rate": {
          "rate": {
            "field": "amount"
          }
        }
      }
    }
  }
}

Response (first buckets of the 16-month teaching window):

{
  ...
  "aggregations": {
    "per_month": {
      "buckets": [
        {
          "key_as_string": "2024-01-01T00:00:00.000Z",
          "key": 1704067200000,
          "doc_count": 8,
          "amount_rate": {
            "value": 270.0
          }
        },
        {
          "key_as_string": "2024-02-01T00:00:00.000Z",
          "key": 1706745600000,
          "doc_count": 7,
          "amount_rate": {
            "value": 495.0
          }
        },
        ...
      ]
    }
  }
}

Use cases #

• Per-interval counters. Events, bytes, errors or revenue per day or month — the canonical date_histogram + rate pairing that keeps dashboards from re-issuing one sum query per bucket.
• Counting events when there is no field. Omit field and each bucket reports its document count — requests per day, orders per week.
• Ratios by composition. A rate with mode: "value_count" as the numerator and a sibling rate on a filtered field as the denominator give error-rate-style fractions per interval.
• Per-bucket averages. mode: "avg" answers “average order value per month” in the same one aggregation, without a separate avg sub-agg.

Parameters for rate #

• field
  (Optional, string) Numeric field to reduce; omit to count documents.
• mode
  (Optional, string) Reduction over the bucket’s values: sum (the default), value_count, or avg.
• unit
  (Optional, string) Date histogram unit (second … year, default month). Accepted for compatibility; values are not rescaled by interval length.

Related #

• sum — the same total without the histogram framing.
• value_count — mode: "value_count" in one call.
• avg — mode: "avg" in one call.
• date_histogram — the bucketing this aggregation is designed to live in.