Date range 집계
Date range 집계
date_range 집계를 사용해 날짜 경계로 정의된 버킷에 문서를 그룹화해요. date_range 집계는 숫자 range 집계처럼 동작하지만, ISO 8601 날짜와 epoch 밀리초 외에도 date math를 허용해요.
다음 사항을 주의하세요:
- from은 포함(inclusive), to는 제외(exclusive)예요.
- 열린 버킷을 만들려면 from 또는 to를 생략해요.
- date math는 반올림을 지원해요. 예:
now-7d/d(7일 전 하루의 시작).
출처: 문서
본문
파라미터 (Parameters)
date_range 집계가 받는 파라미터 표예요.
| 파라미터 | 필수 | 설명 |
|---|---|---|
| field | 예 | 집계할 날짜 필드. |
| ranges | 예 | 비어 있지 않은 범위 객체의 배열. 각 객체는 from 및/또는 to 중 적어도 하나의 경계를 지정해야 해요. |
| ranges[].from | from 또는 to 중 하나 필수 | 하한 포함 경계. |
| ranges[].to | from 또는 to 중 하나 필수 | 상한 제외 경계. |
| ranges[].key | 아니요 | 버킷의 레이블. |
| format | 아니요 | 응답의 *_as_string 필드를 제어해요, 예: yyyy-MM-dd. |
| time_zone | 아니요 | date math나 반올림을 평가할 때 사용하는 IANA 존 또는 UTC 오프셋, 예: Europe/Dublin, +01:00. |
| keyed | 아니요 | true면 배열 대신 key를 키로 한 객체를 반환해요. |
| missing | 아니요 | 필드가 없는 문서에 대해 대체할 값. |
from과 to의 허용 값 (Accepted values for from and to)
from과 to의 다음 값이 허용돼요:
- ISO 8601 문자열:
"2025-10-01T00:00:00Z","2025-10-01" - Date math:
"now-7d/d","now+1M/M","2025-09-01||/M" - Epoch 밀리초:
1756684800000
날짜 문자열에서 구성 요소가 생략되면 누락된 부분은 기본값으로 채워져요. 예를 들어 "2025-10"은 2025년 10월의 시작으로 처리돼요.
예제: 세 개의 슬라이딩 윈도우 (Three sliding windows)
다음 예제는 date math와 yyyy-MM-dd 출력 형식을 사용해 세 개의 버킷(지난 7일, 이전 7일, 더 오래된 것)을 만들어요:
GET my-index/_search
{
"size": 0,
"aggs": {
"by_range": {
"date_range": {
"field": "@timestamp",
"format": "yyyy-MM-dd",
"ranges": [
{ "from": "now-7d/d", "to": "now+1d/d", "key": "last_7d" },
{ "from": "now-14d/d", "to": "now-7d/d", "key": "prev_7d" },
{ "to": "now-14d/d", "key": "older" }
]
}
}
}
}
예제 응답:
"aggregations": {
"by_range": {
"buckets": [
{
"key": "older",
"to": 1758067200000,
"to_as_string": "2025-09-17",
"doc_count": 1
},
{
"key": "prev_7d",
"from": 1758067200000,
"from_as_string": "2025-09-17",
"to": 1758672000000,
"to_as_string": "2025-09-24",
"doc_count": 2
},
{
"key": "last_7d",
"from": 1758672000000,
"from_as_string": "2025-09-24",
"to": 1759363200000,
"to_as_string": "2025-10-02",
"doc_count": 2
}
]
}
}
예제: 커스텀 문자열 형식의 지난 10일 버킷 (Bucket for the last 10 days with a custom string format)
다음 요청은 지난 10개 달력일을 덮는 단일 버킷을 만들어요. 10일 전 하루의 시작(now-10d/d)에서 시작해 내일의 시작(now+1d/d, 제외)에서 끝나요. format은 문서 일치에 영향을 주지 않고 응답의 *_as_string 필드에만 영향을 줘요:
GET my-index/_search
{
"size": 0,
"aggs": {
"last_10_days": {
"date_range": {
"field": "@timestamp",
"format": "yyyy-MM",
"ranges": [ { "from": "now-10d/d", "to": "now+1d/d" } ]
}
}
}
}
예제: 키드 응답과 커스텀 키 (Keyed response and custom keys)
다음 요청은 다운스트림 처리를 쉽게 하도록 레이블별로 구성된 객체를 반환해요:
GET my-index/_search
{
"size": 0,
"aggs": {
"keyed_ranges": {
"date_range": {
"field": "@timestamp",
"keyed": true,
"ranges": [
{ "from": "now-1d/d", "to": "now+1d/d", "key": "today" },
{ "to": "now-1d/d", "key": "before_today" }
]
}
}
}
}
예제 응답:
"aggregations": {
"keyed_ranges": {
"buckets": {
"before_today": {
"to": 1759190400000,
"to_as_string": "2025-09-30T00:00:00.000Z",
"doc_count": 4
},
"today": {
"from": 1759190400000,
"from_as_string": "2025-09-30T00:00:00.000Z",
"to": 1759363200000,
"to_as_string": "2025-10-02T00:00:00.000Z",
"doc_count": 1
}
}
}
}
예제: 시간대가 있는 epoch 밀리초 (Epoch milliseconds with a time zone)
필드 값이 epoch 밀리초로 제공된 경우에도 from과 to 파라미터를 숫자로 제공할 수 있어요. 예를 들어 다음 요청에서 time_zone은 date math와 경계 평가에 영향을 줘요:
GET my-index/_search
{
"size": 0,
"aggs": {
"local_ranges": {
"date_range": {
"field": "event_time",
"time_zone": "Europe/Dublin",
"format": "epoch_millis",
"ranges": [
{ "from": "1697328000000", "to": "1697932800000", "key": "week_sample" }
]
}
}
}
}
예제: 누락된 날짜 처리 (Handling missing dates)
missing을 사용해 기본값을 대체함으로써 값이 없는 문서를 버킷으로 라우팅해요:
GET my-index/_search
{
"size": 0,
"aggs": {
"dated_or_undated": {
"date_range": {
"field": "@timestamp",
"missing": "1970-01-01",
"ranges": [
{ "to": "2000-01-01", "key": "undated_or_old" },
{ "from": "2000-01-01", "key": "dated_recent" }
]
}
}
}
}