Auto-interval date histogram 집계
Auto-interval date histogram 집계
간격을 직접 지정해야 하는 date histogram 집계와 비슷하지만, auto_date_histogram은 여러 개의 버킷을 만들어내는 집계로, 지정한 버킷 수와 데이터의 시간 범위에 따라 자동으로 날짜 히스토그램 버킷을 생성해요. 실제 반환되는 버킷 수는 항상 지정한 버킷 수보다 작거나 같아요. 이 집계는 시계열 데이터를 다룰 때 특히 유용하며, 간격 크기를 직접 지정하지 않고도 다양한 시간 간격으로 데이터를 시각화하거나 분석할 수 있게 해줘요.
출처: 문서
본문
간격 (Intervals)
버킷 간격은 반환되는 버킷 수가 요청한 수보다 작거나 같도록 수집된 데이터를 기반으로 선택돼요.
다음 표는 각 시간 단위에 대해 반환될 수 있는 간격 목록이에요.
| 단위 | 간격 |
|---|---|
| 초 (Seconds) | 1, 5, 10, 30의 배수 |
| 분 (Minutes) | 1, 5, 10, 30의 배수 |
| 시 (Hours) | 1, 3, 12의 배수 |
| 일 (Days) | 1, 7의 배수 |
| 월 (Months) | 1, 3의 배수 |
| 년 (Years) | 1, 5, 10, 20, 50, 100의 배수 |
집계가 너무 많은 버킷(예: 일 단위 버킷)을 반환하면, OpenSearch는 관리 가능한 결과를 만들기 위해 버킷 수를 자동으로 줄여요. 요청한 일 단위 버킷 수를 그대로 반환하는 대신 약 1/7 비율로 줄여요. 예를 들어 70개의 버킷을 요청했는데 데이터에 일 단위 간격이 너무 많다면, OpenSearch는 단 10개의 버킷만 반환하고 데이터를 더 큰 간격(예: 주 단위)으로 묶어 결과가 너무 많아지는 것을 방지해요. 이렇게 하면 집계를 최적화하고 데이터가 너무 많을 때 과도한 세부사항을 막을 수 있어요.
예제 (Example)
다음 예제에서는 블로그 게시물을 담은 인덱스를 검색해요.
먼저 이 인덱스에 대해 매핑을 만들고 date_posted 필드를 date 타입으로 지정해요:
PUT blogs
{
"mappings" : {
"properties" : {
"date_posted" : {
"type" : "date",
"format" : "yyyy-MM-dd"
}
}
}
}
다음으로, 다음 문서들을 blogs 인덱스에 색인해요:
PUT blogs/_doc/1
{
"name": "Semantic search in OpenSearch",
"date_posted": "2022-04-17"
}
PUT blogs/_doc/2
{
"name": "Sparse search in OpenSearch",
"date_posted": "2022-05-02"
}
PUT blogs/_doc/3
{
"name": "Distributed tracing with Data Prepper",
"date_posted": "2022-04-25"
}
PUT blogs/_doc/4
{
"name": "Observability in OpenSearch",
"date_posted": "2023-03-23"
}
auto_date_histogram 집계를 사용하려면 날짜나 타임스탬프 값을 담은 필드를 지정해요. 예를 들어 블로그 게시물을 date_posted 기준으로 두 개의 버킷으로 집계하려면 다음 요청을 보내요:
GET /blogs/_search
{
"size": 0,
"aggs": {
"histogram": {
"auto_date_histogram": {
"field": "date_posted",
"buckets": 2
}
}
}
}
예제 응답 (Example response)
응답은 블로그 게시물이 두 개의 버킷으로 집계되었음을 보여줘요. 간격은 자동으로 1년으로 설정되어, 2022년 게시물 3개가 한 버킷에, 2023년 게시물 1개가 다른 버킷에 담겨요:
{
"took": 20,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 4,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"histogram": {
"buckets": [
{
"key_as_string": "2022-01-01",
"key": 1640995200000,
"doc_count": 3
},
{
"key_as_string": "2023-01-01",
"key": 1672531200000,
"doc_count": 1
}
],
"interval": "1y"
}
}
}
반환되는 버킷 (Returned buckets)
각 버킷은 다음 정보를 포함해요:
{
"key_as_string": "2023-01-01",
"key": 1672531200000,
"doc_count": 1
}
OpenSearch에서 날짜는 내부적으로 epoch 이후의 밀리초 타임스탬프를 나타내는 64비트 정수로 저장돼요. 집계 응답에서 각 버킷 키는 이런 타임스탬프로 반환돼요. key_as_string 값은 format 파라미터를 기반으로 날짜 문자열로 형식이 지정된 동일한 타임스탬프를 보여줘요. doc_count 필드에는 버킷 내 문서 수가 담겨 있어요.
파라미터 (Parameters)
Auto-interval date histogram 집계는 다음 파라미터를 받아요.
| 파라미터 | 데이터 타입 | 설명 |
|---|---|---|
| field | String | 집계할 필드. 날짜나 타임스탬프 값을 포함해야 해요. field 또는 script 중 하나는 필수예요. |
| buckets | Integer | 원하는 버킷 수. 반환되는 버킷 수는 원하는 수보다 작거나 같아요. 선택 사항. 기본값은 10이에요. |
| minimum_interval | String | 사용할 최소 간격. 최소 간격을 지정하면 집계 처리가 더 효율적으로 될 수 있어요. 유효한 값은 year, month, day, hour, minute, second예요. 선택 사항. |
| time_zone | String | 버킷 생성과 반올림에 기본값(UTC)이 아닌 다른 시간대를 사용하도록 지정해요. time_zone 파라미터는 -04:00 같은 UTC 오프셋이나 America/New_York 같은 IANA 시간대 ID로 지정할 수 있어요. 선택 사항. 기본값은 UTC예요. 자세한 내용은 Time zone을 참고하세요. |
| format | String | 버킷 키를 나타내는 날짜를 반환할 때 사용할 형식. 선택 사항. 기본값은 필드 매핑에서 지정된 형식이에요. 자세한 내용은 Date format을 참고하세요. |
| script | String | 값을 버킷으로 집계하는 데 사용하는 문서 수준 또는 값 수준 스크립트. field 또는 script 중 하나는 필수예요. |
| missing | String | 필드 값이 없는 문서를 처리하는 방법을 지정해요. 기본적으로 이런 문서는 무시돼요. missing 파라미터에 날짜 값을 지정하면 필드 값이 없는 모든 문서가 지정된 날짜가 있는 버킷으로 수집돼요. |
날짜 형식 (Date format)
format 파라미터를 지정하지 않으면 필드 매핑에 정의된 형식이 사용돼요 (위 응답에서 볼 수 있듯이). 형식을 수정하려면 format 파라미터를 지정해요:
GET /blogs/_search
{
"size": 0,
"aggs": {
"histogram": {
"auto_date_histogram": {
"field": "date_posted",
"format": "yyyy-MM-dd HH:mm:ss"
}
}
}
}
key_as_string 필드는 이제 지정된 형식으로 반환돼요:
{
"key_as_string": "2023-01-01 00:00:00",
"key": 1672531200000,
"doc_count": 1
}
또는 내장된 날짜 형식 중 하나를 지정할 수도 있어요:
GET /blogs/_search
{
"size": 0,
"aggs": {
"histogram": {
"auto_date_histogram": {
"field": "date_posted",
"format": "basic_date_time_no_millis"
}
}
}
}
key_as_string 필드는 이제 지정된 형식으로 반환돼요:
{
"key_as_string": "20230101T000000Z",
"key": 1672531200000,
"doc_count": 1
}
시간대 (Time zone)
기본적으로 날짜는 UTC로 저장되고 처리돼요. time_zone 파라미터를 사용하면 버킷 생성에 다른 시간대를 지정할 수 있어요. time_zone 파라미터는 -04:00 같은 UTC 오프셋이나 America/New_York 같은 IANA 시간대 ID로 지정할 수 있어요.
예를 들어, 다음 문서들을 인덱스에 색인해요:
PUT blogs1/_doc/1
{
"name": "Semantic search in OpenSearch",
"date_posted": "2022-04-17T01:00:00.000Z"
}
PUT blogs1/_doc/2
{
"name": "Sparse search in OpenSearch",
"date_posted": "2022-04-17T04:00:00.000Z"
}
먼저 시간대를 지정하지 않고 집계를 실행해요:
GET /blogs1/_search
{
"size": 0,
"aggs": {
"histogram": {
"auto_date_histogram": {
"field": "date_posted",
"buckets": 2,
"format": "yyyy-MM-dd HH:mm:ss"
}
}
}
}
응답은 2022년 4월 17일 자정 UTC에서 시작하는 두 개의 3시간 버킷을 포함해요:
{
"took": 6,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 2,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"histogram": {
"buckets": [
{
"key_as_string": "2022-04-17 01:00:00",
"key": 1650157200000,
"doc_count": 1
},
{
"key_as_string": "2022-04-17 04:00:00",
"key": 1650168000000,
"doc_count": 1
}
],
"interval": "3h"
}
}
}
이제 time_zone을 -02:00으로 지정해요:
GET /blogs1/_search
{
"size": 0,
"aggs": {
"histogram": {
"auto_date_histogram": {
"field": "date_posted",
"buckets": 2,
"format": "yyyy-MM-dd HH:mm:ss",
"time_zone": "-02:00"
}
}
}
}
응답은 시작 시간이 2시간 이동된 두 개의 버킷을 포함하며, 2022년 4월 16일 23:00에 시작해요:
{
"took": 17,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 2,
"relation": "eq"
},
"max_score": null,
"hits": []
},
"aggregations": {
"histogram": {
"buckets": [
{
"key_as_string": "2022-04-16 23:00:00",
"key": 1650157200000,
"doc_count": 1
},
{
"key_as_string": "2022-04-17 02:00:00",
"key": 1650168000000,
"doc_count": 1
}
],
"interval": "3h"
}
}
}
일광 절약 시간(DST) 변경이 있는 시간대를 사용할 때, 전환 지점 근처의 버킷 크기는 이웃 버킷의 크기와 약간 다를 수 있어요.