Date histogram 집계

Date histogram 집계

date_histogram 집계는 date math를 사용해 문서를 시간 기반 버킷으로 그룹화해요. 시간/일/월 단위로 메트릭을 집계하거나, 트래픽 추세를 차트로 그리거나, 시계열 대시보드를 채우는 데 사용해요.

출처: 문서

본문

올바른 간격 선택 (Choose the right interval)

date_histogram은 두 가지 간격 스타일을 지원해요:

• calendar_interval — 버킷을 일, 월, 연도 같은 달력 경계에 맞춰요. 실제 달력 기간에 초점을 맞출 때 사용해요. 예시 값: "day", "1M", "year".
• fixed_interval — SI 단위로 측정된 정확한 기간을 사용해요. 버킷은 일광 절약 시간이나 월 길이와 무관하게 항상 같은 길이예요. 예시 값: "5m", "12h", "30d".

이전 버전의 interval 필드는 호환성을 위해 유지되지만 더 이상 권장되지 않아요(deprecated). 대신 calendar_interval이나 fixed_interval을 사용하세요.

예제: 월별 버킷 (calendar interval)

달력 월별로 문서 수를 집계해요:

GET opensearch_dashboards_sample_data_logs/_search
{
  "size": 0,
  "aggs": {
    "logs_per_month": {
      "date_histogram": {
        "field": "@timestamp",
        "calendar_interval": "1M"
      }
    }
  }
}

예제: 균일한 시간별 버킷 (fixed interval)

일광 절약 시간 변경과 무관하게 정확히 1시간의 고정 간격으로 버킷을 검색해요:

GET my-logs/_search
{
  "size": 0,
  "aggs": {
    "by_hour": {
      "date_histogram": {
        "field": "timestamp",
        "fixed_interval": "1h"
      }
    }
  }
}

예제: 시간대 사용 (Use a time zone)

기본적으로 버킷 생성은 UTC로 이루어져요. time_zone을 설정해 버킷 경계를 특정 시간대에 맞추세요.

Europe/Dublin을 사용해 일별 버킷을 검색해요:

GET my-logs/_search
{
  "size": 0,
  "aggs": {
    "by_day_ie": {
      "date_histogram": {
        "field": "timestamp",
        "calendar_interval": "day",
        "time_zone": "Europe/Dublin"
      }
    }
  }
}

예제: offset으로 버킷 시작 시간 이동 (Shift bucket start times using an offset)

offset 파라미터를 사용해 버킷 경계를 앞뒤로 이동시켜요. 예를 들어 자정자정 대신 06:0006:00에 걸친 "보고일(reporting day)"을 정의할 수 있어요:

GET my-logs/_search
{
  "size": 0,
  "aggs": {
    "by_day_shifted": {
      "date_histogram": {
        "field": "timestamp",
        "calendar_interval": "day",
        "offset": "+6h"
      }
    }
  }
}

예제: 빈 버킷 포함 (Include empty buckets)

min_doc_count를 0으로 설정하고 extended_bounds에 범위를 제공하면 전체 시간 창에 걸쳐 빈 버킷을 반환해요.

마지막 24시간 동안 데이터가 없는 시간을 포함해 1시간 고정 간격의 버킷을 검색해요:

GET my-logs/_search
{
  "size": 0,
  "aggs": {
    "last_24h": {
      "date_histogram": {
        "field": "timestamp",
        "fixed_interval": "1h",
        "min_doc_count": 0,
        "extended_bounds": {"min": "now-24h", "max": "now"}
      }
    }
  }
}

예제: 범위를 엄격히 제한 (Strictly limit the range)

hard_bounds는 히스토그램을 지정된 최소/최대 시간 범위로 엄격히 제한해요. 이 범위 밖에는 데이터가 존재하더라도 버킷이 생성되지 않아요.

2025-09-01T00:00:00Z와 2025-09-01T06:00:00Z 사이의 기간에 대해 30분 고정 간격의 버킷을 검색해요:

GET my-logs/_search
{
  "size": 0,
  "aggs": {
    "strict_range": {
      "date_histogram": {
        "field": "timestamp",
        "fixed_interval": "30m",
        "hard_bounds": {"min": "2025-09-01T00:00:00Z", "max": "2025-09-01T06:00:00Z"}
      }
    }
  }
}

예제: keyed로 버킷 맵 반환 (Return a map of buckets using keyed)

keyed: true를 설정하면 버킷을 형식이 지정된 날짜 문자열로 키가 지정된 객체로 반환해요:

GET my-logs/_search
{
  "size": 0,
  "aggs": {
    "per_month": {
      "date_histogram": {
        "field": "timestamp",
        "calendar_interval": "1M",
        "format": "yyyy-MM-dd",
        "keyed": true
      }
    }
  }
}

예제 응답:

{
  "aggregations": {
    "per_month": {
      "buckets": {
        "2025-01-01": {"key_as_string": "2025-01-01", "key": 1735689600000, "doc_count": 3},
        "2025-02-01": {"key_as_string": "2025-02-01", "key": 1738368000000, "doc_count": 2}
      }
    }
  }
}

예제: 누락된 날짜를 고정 값으로 처리 (Treat missing dates as a fixed value)

missing 파라미터를 사용해 값이 없는 문서를 제공된 날짜의 합성 버킷에 할당해요:

GET articles/_search
{
  "size": 0,
  "aggs": {
    "published_per_year": {
      "date_histogram": {
        "field": "publish_date",
        "calendar_interval": "year",
        "missing": "2000-01-01"
      }
    }
  }
}

예제: 버킷 정렬 (Sort buckets)

기본적으로 버킷은 _key 기준 오름차순으로 정렬되어 반환돼요. 필요하다면 order 파라미터를 사용해 내림차순으로 변경하세요.

가장 최근 월이 먼저 오도록 버킷을 검색해요:

GET my-logs/_search
{
  "size": 0,
  "aggs": {
    "recent_months": {
      "date_histogram": {
        "field": "timestamp",
        "calendar_interval": "1M",
        "order": {"_key": "desc"}
      }
    }
  }
}

버킷 수 기준으로 정렬해요 (내림차순):

GET my-logs/_search
{
  "size": 0,
  "aggs": {
    "busiest_hours": {
      "date_histogram": {
        "field": "timestamp",
        "fixed_interval": "1h",
        "order": {"_count": "desc"}
      }
    }
  }
}

예제: 스크립트 기반 값 소스 (Scripted value source)

Painless 스크립트를 사용해 date_histogram의 버킷 생성에 쓰이는 날짜 값을 동적으로 생성하거나 수정할 수 있어요. 이는 쿼리 시점에 복잡한 날짜 로직을 처리할 수 있는 유연성을 제공해요. 자세한 내용은 Painless scripting language를 참고하세요.

date_histogram 집계는 date 객체나 문자열과 직접 동작하지 않아요. 각 문서의 타임스탬프를 나타내는 단일 숫자 값이 필요해요. 이 값은 epoch 밀리초, 즉 1970년 1월 1일 00:00:00 UTC 이후 경과한 밀리초 수를 나타내는 long 정수여야 해요. 제공하는 모든 스크립트는 이 타입의 값을 반환해야 해요. 스크립트를 사용한 다음 예제는 "field": "timestamp"를 사용한 이전 예제와 동일하게 동작하면서도 date 필드에 대해 올바른 반환 타입을 생성해요:

GET my-logs/_search
{
  "size": 0,
  "aggs": {
    "by_hour_script": {
      "date_histogram": {
        "script": {
          "lang": "painless",
          "source": "return doc['timestamp'].value.toInstant().toEpochMilli();"
        },
        "fixed_interval": "1h"
      }
    }
  }
}

파라미터 (Parameters)

date_histogram 집계는 다음 파라미터를 지원해요.

더 알아보기 (Learn more)

• OpenSearch 공식 문서