가변 폭 히스토그램 집계

가변 폭 히스토그램 집계 (Variable width histogram aggregation)

variable_width_histogram 집계는 숫자 필드의 값을 목표 개수의 버킷으로 나누는데, 버킷의 폭이 데이터에 적응해요. 버킷 경계는 값을 클러스터링하여 파생되므로, 값 범위에서 밀집된 부분은 좁은 버킷으로 나뉘고 희소한 부분은 넓은 버킷으로 덮여요. 히스토그램 집계의 고정 간격이 거의 비어 있는 버킷을 많이 만들거나 거의 모든 문서를 담는 소수의 버킷을 만드는 고르지 않게 분포된 데이터에 이 집계를 사용하세요.

각 샤드는 수집한 첫 initial_buffer 값들을 버퍼링한 뒤 정렬하고, 이를 shard_size의 4분의 3과 같은 수의 초기 클러스터로 나눠요. 각 나머지 값은 가장 가까운 클러스터에 할당되는데, 단 값이 모든 클러스터의 이웃 중심점 사이 평균 거리의 두 배보다 멀리 떨어져 있고 샤드가 shard_size보다 적은 클러스터를 보유하고 있는 경우에는 새 클러스터를 시작해요. 조정 노드는 모든 샤드의 클러스터를 수집하고, 버킷이 남을 때까지 중심점이 가장 가까운 두 클러스터를 반복적으로 병합해요.

출처: 문서

본문

파라미터

variable_width_histogram 집계는 다음과 같은 파라미터를 받아요.

파라미터	필수/선택	데이터 타입	설명
`field`	필수	String	집계할 숫자 필드예요. `field` 또는 `script` 중 하나를 제공해요.
`buckets`	선택	Integer	목표 버킷 개수예요. `0`보다 커야 하며 `search.max_buckets` 설정을 초과할 수 없어요. 값이 그만큼의 클러스터로 분리되지 않으면 응답에 요청한 것보다 적은 버킷이 포함될 수 있어요. 기본값은 `10`이에요.
`shard_size`	선택	Integer	각 샤드가 결과를 조정 노드로 보내기 전에 구축하는 클러스터 개수예요. `1`보다 커야 해요. 값이 클수록 각 샤드에서 더 작은 클러스터가 생성되어 최종 버킷 간의 겹침이 줄고 버킷 경계가 더 정확하게 배치되지만, 샤드에서 사용되는 메모리와 조정 노드로 전송되는 데이터의 양이 증가해요. 기본값은 `buckets`에 50을 곱한 값이에요.
`initial_buffer`	선택	Integer	각 샤드가 초기 클러스터 경계를 계산하기 전에 버퍼링하는 값의 개수예요. `buckets`보다 크거나 같아야 해요. 버퍼가 클수록 데이터의 더 대표적인 표본에서 초기 경계를 파생하지만 메모리를 더 많이 사용해요. 기본값은 `shard_size`에 10을 곱한 값과 50000 중 더 작은 값이에요.
`script`	선택	Object	집계할 숫자 값을 생성하는 스크립트예요. `field` 또는 `script` 중 하나를 제공해요.
`missing`	선택	Number	대상 필드가 없는 문서에 할당할 값이에요. 기본적으로 누락된 문서는 무시돼요.
`format`	선택	String	`min`, `key`, `max`에 적용되는 DecimalFormat 형식 문자열이에요. 추가 `min_as_string`, `key_as_string`, `max_as_string` 응답 필드에 형식화된 출력을 반환해요.

예제

다음 예제는 e-커머스 주문 합계를 다섯 개의 가변 폭 버킷으로 그룹화해요:

GET /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "price_buckets": {
      "variable_width_histogram": {
        "field": "taxful_total_price",
        "buckets": 5
      }
    }
  }
}

예제 응답

{
  "took": 17,
  "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_buckets": {
      "buckets": [
        {
          "min": 6.98828125,
          "key": 59.14907207464146,
          "max": 105.46875,
          "doc_count": 3835
        },
        {
          "min": 105.46875,
          "key": 139.096796875,
          "max": 229.5,
          "doc_count": 800
        },
        {
          "min": 229.5,
          "key": 247.11111111111111,
          "max": 304.0,
          "doc_count": 27
        },
        {
          "min": 304.0,
          "key": 318.4,
          "max": 308.0,
          "doc_count": 5
        },
        {
          "min": 308.0,
          "key": 563.25,
          "max": 2250.0,
          "doc_count": 8
        }
      ]
    }
  }
}

가격 범위에서 붐비는 낮은 구간을 덮는 버킷은 폭이 수십 달러인 반면, 마지막 버킷은 가장 높은 소수 주문을 담기 위해 거의 $2,000에 이릅니다.

예제: 하위 집계 중첩하기 (Nesting a subaggregation)

다른 버킷 집계처럼 variable_width_histogram은 하위 집계를 받아들여요. 다음 예제는 각 가격 버킷에서 주문된 평균 품목 수를 계산해요:

GET /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "price_buckets": {
      "variable_width_histogram": {
        "field": "taxful_total_price",
        "buckets": 3
      },
      "aggs": {
        "avg_quantity": {
          "avg": {
            "field": "total_quantity"
          }
        }
      }
    }
  }
}

응답에는 각 버킷에 하위 집계 결과가 포함돼요:

{
  "aggregations": {
    "price_buckets": {
      "buckets": [
        {
          "min": 6.98828125,
          "key": 73.45130757286513,
          "max": 246.0,
          "doc_count": 4649,
          "avg_quantity": {
            "value": 2.1559475155947516
          }
        },
        {
          "min": 246.0,
          "key": 281.9166666666667,
          "max": 370.0,
          "doc_count": 24,
          "avg_quantity": {
            "value": 2.7083333333333335
          }
        },
        {
          "min": 393.0,
          "key": 1321.5,
          "max": 2250.0,
          "doc_count": 2,
          "avg_quantity": {
            "value": 1.5
          }
        }
      ]
    }
  }
}

응답 본문 필드 (Response body fields)

다음 표는 응답 본문 필드를 나열해요.

필드	데이터 타입	설명
`buckets`	Array	`key`를 기준으로 오름차순 정렬된 가변 폭 버킷들이에요.
`buckets.min`	Double	버킷의 하한이에요.
`buckets.key`	Double	버킷에 있는 값들의 평균이에요.
`buckets.max`	Double	버킷의 상한이에요.
`buckets.doc_count`	Integer	버킷의 문서 수예요.
`buckets.min_as_string`	String	`format`에 따라 형식화된 버킷의 하한이에요. `format`이 설정된 경우에만 반환돼요.
`buckets.key_as_string`	String	`format`에 따라 형식화된 버킷 값들의 평균이에요. `format`이 설정된 경우에만 반환돼요.
`buckets.max_as_string`	String	`format`에 따라 형식화된 버킷의 상한이에요. `format`이 설정된 경우에만 반환돼요.

제한 사항 (Limitations)

variable_width_histogram 집계에는 다음과 같은 제한 사항이 있어요:

집계가 둘 이상의 버킷을 수집하는 부모 집계 내부에 중첩될 수 없어요. terms, histogram, range 또는 filters 부모 집계는 다음 오류를 반환해요:

[variable_width_histogram] cannot be nested inside an aggregation that collects more than a single bucket.

filter, global, nested 같은 단일 버킷 부모 집계는 지원돼요.
top_hits처럼 문서 점수를 요구하는 하위 집계가 있는 경우, 집계가 nested 집계의 자식으로 실행될 수 없어요. 이 조합은 오류를 반환해요.
keyed 파라미터가 지원되지 않으므로 버킷은 항상 배열로 반환돼요.
min 및 max 경계는 근사치예요. 클러스터를 병합하는 동안 OpenSearch는 중심점이 멀리 떨어져 있으면 경계가 겹치는 두 클러스터를 별도의 버킷으로 남겨둘 수 있어요. 그런 다음 두 버킷 사이의 경계를 겹침의 중간점으로 설정하므로, 경계가 반드시 데이터에 존재하는 값일 필요는 없고, 하위 버킷이 경계가 나타내는 것보다 더 많은 값을 보유하고 상위 버킷은 더 적은 값을 보유해요. 이렇게 버킷의 max를 낮추면 버킷의 자체 key(버킷에 있는 값들의 평균)보다 낮아질 수 있어요. 첫 번째 예제 응답의 네 번째 버킷은 이런 이유로 max가 308.0인데 key가 318.4로 보고돼요. 이 병합 단계는 다중 샤드 인덱스뿐만 아니라 단일 샤드 인덱스에서도 실행돼요.
버킷은 연속적이지 않아요. 각 버킷의 경계는 버킷이 보유한 가장 작고 큰 값이므로, 데이터에 공백이 있으면 인접 버킷 사이에 간격으로 나타나요. 하위 집계 예제 응답에서 한 버킷은 370.0에서 끝나고 다음 버킷은 393.0에서 시작해요.
버킷 경계는 이상치에 민감해요. 몇 개의 극단값이 버킷을 데이터의 넓은 범위에 걸쳐 늘릴 수 있어요. 첫 번째 예제 응답의 마지막 버킷은 8건의 주문을 담기 위해 308.0에서 2250.0까지 확장돼요.
버킷 경계는 각 샤드가 값을 수집하는 순서에 따라 달라지므로, 값 분포가 동일하게 유지되어도 세그먼트가 병합되거나 문서가 추가됨에 따라 변경될 수 있어요.

더 알아보기 (Learn more)

OpenSearch 공식 문서