This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Date histogram aggregations

The date_histogram aggregation uses date math to generate histograms for time-series data.

For example, you can find how many hits your website gets per month:

  1. GET opensearch_dashboards_sample_data_logs/_search
  2. {
  3.   "size": 0,
  4.   "aggs": {
  5.     "logs_per_month": {
  6.       "date_histogram": {
  7.         "field": "@timestamp",
  8.         "interval": "month"
  9.       }
  10.     }
  11.   }
  12. }

copy

Example response

  1. ...
  2. "aggregations" : {
  3.   "logs_per_month" : {
  4.     "buckets" : [
  5.       {
  6.         "key_as_string" : "2020-10-01T00:00:00.000Z",
  7.         "key" : 1601510400000,
  8.         "doc_count" : 1635
  9.       },
  10.       {
  11.         "key_as_string" : "2020-11-01T00:00:00.000Z",
  12.         "key" : 1604188800000,
  13.         "doc_count" : 6844
  14.       },
  15.       {
  16.         "key_as_string" : "2020-12-01T00:00:00.000Z",
  17.         "key" : 1606780800000,
  18.         "doc_count" : 5595
  19.       }
  20.     ]
  21.   }
  22. }
  23. }

The response has three months worth of logs. If you graph these values, you can see the peak and valleys of the request traffic to your website month over month.