Date Histogram Aggregation

While the basic histogram aggregation works with numeric data, the date histogram aggregation is used for time-based data. This allows you to group documents by date intervals, such as days, weeks, or months.

Example Dataset

Let’s add some time-based sales data to our sales index:

{
  "sale_id": 4,
  "product": "Smartphone",
  "category": "electronics",
  "price": 500,
  "quantity": 3,
  "timestamp": "2023-01-01T10:00:00Z"
},
{
  "sale_id": 5,
  "product": "Headphones",
  "category": "electronics",
  "price": 50,
  "quantity": 10,
  "timestamp": "2023-01-02T12:00:00Z"
},
{
  "sale_id": 6,
  "product": "Shoes",
  "category": "clothing",
  "price": 70,
  "quantity": 4,
  "timestamp": "2023-01-03T14:00:00Z"
}

Query

Let’s group sales by day using the timestamp field:

GET /sales/_search
{
  "size": 0,
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "timestamp",
        "calendar_interval": "day"
      }
    }
  }
}

Output:

{
  "took": 15,
  "timed_out": false,
  "_shards": {
    "total": 5,
    "successful": 5,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 6,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "sales_over_time": {
      "buckets": [
        {
          "key_as_string": "2023-01-01T00:00:00.000Z",
          "key": 1672531200000,
          "doc_count": 2
        },
        {
          "key_as_string": "2023-01-02T00:00:00.000Z",
          "key": 1672617600000,
          "doc_count": 2
        },
        {
          "key_as_string": "2023-01-03T00:00:00.000Z",
          "key": 1672704000000,
          "doc_count": 2
        }
      ]
    }
  }
}

In this example, the aggregation named sales_over_time groups sales into daily intervals. Each bucket represents a day and contains the number of sales for that day.

Elasticsearch is a powerful search and analytics engine that allows for efficient data analysis through its rich aggregation framework. Among the various aggregation types, histogram aggregation is particularly useful for grouping data into intervals, which is essential for understanding the distribution and trends within your data.

In this article, we will delve into data histogram aggregation in Elasticsearch, explain its use cases, and provide detailed examples to help you master this powerful feature.