Percentiles bucket 집계

percentiles_bucket 집계는 버킷된 지표의 백분위수 위치(percentile placement)를 계산하는 형제(sibling) 집계예요. 근사값이나 보간 없이 백분위수를 정확히 계산해요.

출처: 문서

본문

percentiles_bucket 집계는 버킷된 지표의 백분위수 위치를 계산하는 형제(sibling) 집계입니다.

percentiles_bucket 집계는 근사값이나 보간 없이 백분위수를 정확히 계산합니다. 각 백분위수는 대상 백분위수보다 작거나 같은 가장 가까운 값으로 반환됩니다.

percentiles_bucket 집계는 대규모 데이터셋에서도 값 목록 전체를 일시적으로 메모리에 유지해야 합니다. 반면 percentiles 지표 집계는 메모리를 덜 사용하지만 백분위수를 근사합니다.

지정한 지표는 숫자여야 하며, 형제로 사용하는 집계는 다중 버킷(multi-bucket) 집계여야 합니다.

파라미터

avg_bucket 집계는 다음 파라미터를 받습니다.

파라미터	필수/선택	데이터 타입	설명
`buckets_path`	필수	String	집계할 집계 버킷들의 경로입니다. Buckets path를 참고하세요.
`gap_policy`	선택	String	누락된 데이터에 적용할 정책입니다. 유효한 값은 `skip`과 `insert_zeros`이며 기본값은 `skip`입니다. Data gaps를 참고하세요.
`format`	선택	String	`DecimalFormat` 서식 문자열입니다. 집계의 `value_as_string` 속성에 서식이 적용된 출력을 반환합니다.
`percents`	선택	List	출력에 포함할 임의 개수의 숫자 백분율 값 목록입니다. 유효한 값은 0.0 이상 100.0 이하입니다. 기본값은 `[1.0, 5.0, 25.0, 50.0, 75.0, 95.0, 99.0]`입니다.
`keyed`	선택	Boolean	출력을 키-값 쌍 객체의 배열 대신 사전(dictionary)으로 서식화할지 여부입니다. 기본값은 `true`(키-값 쌍으로 서식화)입니다.

예제

다음 예제는 OpenSearch Dashboards e-commerce 샘플 데이터에서 1주일 간격의 날짜 히스토그램을 만듭니다. sum 서브 집계가 매주 taxful_total_price를 더합니다. 마지막으로 percentiles_bucket 집계가 이 합계들에서 매주 백분위수 값을 계산합니다.

POST /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "weekly_sales": {
      "date_histogram": {
        "field": "order_date",
        "calendar_interval": "week"
      },
      "aggs": {
        "total_price": {
          "sum": {
            "field": "taxful_total_price"
          }
        }
      }
    },
    "percentiles_monthly_sales": {
      "percentiles_bucket": {
        "buckets_path": "weekly_sales>total_price"
      }
    }
  }
}

예제 응답

집계는 주간 가격 합계에 대한 기본 백분위수 값을 반환합니다.

{
  "took": 4,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "weekly_sales": {
      "buckets": [
        {
          "key_as_string": "2025-03-24T00:00:00.000Z",
          "key": 1742774400000,
          "doc_count": 582,
          "total_price": {
            "value": 41455.5390625
          }
        },
        {
          "key_as_string": "2025-03-31T00:00:00.000Z",
          "key": 1743379200000,
          "doc_count": 1048,
          "total_price": {
            "value": 79448.60546875
          }
        },
        {
          "key_as_string": "2025-04-07T00:00:00.000Z",
          "key": 1743984000000,
          "doc_count": 1048,
          "total_price": {
            "value": 78208.4296875
          }
        },
        {
          "key_as_string": "2025-04-14T00:00:00.000Z",
          "key": 1744588800000,
          "doc_count": 1073,
          "total_price": {
            "value": 81277.296875
          }
        },
        {
          "key_as_string": "2025-04-21T00:00:00.000Z",
          "key": 1745193600000,
          "doc_count": 924,
          "total_price": {
            "value": 70494.2578125
          }
        }
      ]
    },
    "percentiles_monthly_sales": {
      "values": {
        "1.0": 41455.5390625,
        "5.0": 41455.5390625,
        "25.0": 70494.2578125,
        "50.0": 78208.4296875,
        "75.0": 79448.60546875,
        "95.0": 81277.296875,
        "99.0": 81277.296875
      }
    }
  }
}

예제: 옵션

다음 예제는 이전 예제와 같은 데이터를 사용하되 다음 차이점을 두고 백분위수를 계산합니다.

percents 파라미터가 25번째, 50번째, 75번째 백분위수만 계산하도록 지정합니다.
format 파라미터를 사용해 문자열 서식 출력을 추가합니다.
keyed 파라미터를 false로 설정해 결과를 키-값 쌍 객체(문자열 값 추가 포함)로 표시합니다.

예제는 다음과 같습니다.

POST /opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "weekly_sales": {
      "date_histogram": {
        "field": "order_date",
        "calendar_interval": "week"
      },
      "aggs": {
        "total_price": {
          "sum": {
            "field": "taxful_total_price"
          }
        }
      }
    },
    "percentiles_monthly_sales": {
      "percentiles_bucket": {
        "buckets_path": "weekly_sales>total_price",
        "percents": [25.0, 50.0, 75.0],
        "format": "$#,###.00",
        "keyed": false
      }
    }
  }
}

예제 응답: 옵션

옵션들이 집계의 출력을 수정합니다.

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "weekly_sales": {
      "buckets": [
        {
          "key_as_string": "2025-03-24T00:00:00.000Z",
          "key": 1742774400000,
          "doc_count": 582,
          "total_price": {
            "value": 41455.5390625
          }
        },
        {
          "key_as_string": "2025-03-31T00:00:00.000Z",
          "key": 1743379200000,
          "doc_count": 1048,
          "total_price": {
            "value": 79448.60546875
          }
        },
        {
          "key_as_string": "2025-04-07T00:00:00.000Z",
          "key": 1743984000000,
          "doc_count": 1048,
          "total_price": {
            "value": 78208.4296875
          }
        },
        {
          "key_as_string": "2025-04-14T00:00:00.000Z",
          "key": 1744588800000,
          "doc_count": 1073,
          "total_price": {
            "value": 81277.296875
          }
        },
        {
          "key_as_string": "2025-04-21T00:00:00.000Z",
          "key": 1745193600000,
          "doc_count": 924,
          "total_price": {
            "value": 70494.2578125
          }
        }
      ]
    },
    "percentiles_monthly_sales": {
      "values": [
        {
          "key": 25,
          "value": 70494.2578125,
          "25.0_as_string": "$70,494.26"
        },
        {
          "key": 50,
          "value": 78208.4296875,
          "50.0_as_string": "$78,208.43"
        },
        {
          "key": 75,
          "value": 79448.60546875,
          "75.0_as_string": "$79,448.61"
        }
      ]
    }
  }
}

더 알아보기 (Learn more)

OpenSearch 공식 문서