Histogram 집계

histogram 집계는 숫자 필드의 값 범위를 고정 너비 간격으로 나누고 각 간격의 문서 수를 집계해요. 각 버킷의 키는 해당 간격의 하한을 나타내며, Math.floor((value - offset) / interval) * interval + offset으로 계산돼요.

출처: 문서

본문

파라미터 (Parameters)

histogram 집계는 다음 파라미터를 받아요.

파라미터	필수/선택	데이터 타입	설명
field	필수	String	집계할 숫자 필드.
interval	필수	Number	각 버킷의 너비. 양수여야 해요.
min_doc_count	선택	Integer	버킷이 응답에 나타나는 데 필요한 최소 문서 수. 빈 버킷을 생략하려면 1로 설정해요. 기본값은 0(빈 버킷 포함)이에요.
extended_bounds	선택	Object	해당 범위에 문서가 없어도 min부터 max까지 버킷이 존재하도록 보장해요. 경계를 넘는 버킷을 필터링하지는 않아요. 범위 밖의 버킷을 제외하려면 hard_bounds 또는 range 쿼리를 사용하세요. min과 max 값을 받아요. min_doc_count가 0일 때만 의미가 있어요.
hard_bounds	선택	Object	응답의 버킷 범위를 제한해요. min과 max 값을 받아요. 이 경계 밖의 버킷은 제외돼요.
offset	선택	Number	버킷 경계를 지정된 양만큼 이동시켜요. [0, interval) 범위에 있어야 해요. 기본값은 0이에요.
keyed	선택	Boolean	true면 버킷을 배열 대신 버킷 값으로 키가 지정된 객체로 반환해요. 기본값은 false예요.
order	선택	Object	버킷의 정렬 순서를 제어해요. _key 또는 _count를 각각 asc 또는 desc와 함께 받아요. 기본값은 `{"_key": "asc"}`예요.
missing	선택	Number	대상 필드가 없는 문서에 할당할 값으로, 해당 버킷에 배치돼요. 기본적으로 누락된 문서는 무시돼요.

단일 값 숫자 필드 대신 숫자 범위 필드를 집계할 때 문서는 하한과 상한 사이의 각 간격마다 여러 버킷에 나타날 수 있어요.

예제: 기본 히스토그램 (Basic histogram)

다음 예제는 전자상거래 주문 금액을 $50 간격으로 그룹화하고, 최소 하나의 문서를 포함하는 버킷만 표시해요:

GET /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "price_histogram": {
      "histogram": {
        "field": "taxful_total_price",
        "interval": 50,
        "min_doc_count": 1
      }
    }
  }
}

예제: offset으로 버킷 경계 이동 (Using offset to shift bucket boundaries)

offset 파라미터는 버킷 경계가 시작되는 위치를 이동시켜요. 다음 예제는 offset 10을 사용하므로 버킷이 0, 50, 100 대신 10, 60, 110에서 시작해요:

GET /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "price_histogram": {
      "histogram": {
        "field": "taxful_total_price",
        "interval": 50,
        "offset": 10,
        "min_doc_count": 1
      }
    }
  }
}

예제 응답 (Example response)

다음 응답은 기본 히스토그램 예제에 해당해요:

{
  "took": 2,
  "timed_out": false,
  "terminated_early": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "price_histogram": {
      "buckets": [
        {
          "key": 0.0,
          "doc_count": 1633
        },
        {
          "key": 50.0,
          "doc_count": 2036
        },
        {
          "key": 100.0,
          "doc_count": 724
        },
        {
          "key": 150.0,
          "doc_count": 205
        },
        {
          "key": 200.0,
          "doc_count": 53
        },
        {
          "key": 250.0,
          "doc_count": 14
        },
        {
          "key": 300.0,
          "doc_count": 7
        },
        {
          "key": 350.0,
          "doc_count": 2
        },
        {
          "key": 2250.0,
          "doc_count": 1
        }
      ]
    }
  }
}

응답 본문 필드 (Response body fields)

필드	데이터 타입	설명
buckets	Array 또는 Object	히스토그램 버킷. 기본적으로 배열로, keyed가 true면 객체로 반환돼요.
buckets.key	Double	버킷 간격의 하한.
buckets.doc_count	Integer	버킷의 문서 수.

더 알아보기 (Learn more)

OpenSearch 공식 문서