버킷 스크립트 집계

버킷 스크립트 집계 (Bucket script aggregation)

bucket_script 집계는 버킷 집합에 걸쳐 버킷별 숫자 계산을 수행하기 위해 스크립트를 실행하는 부모(parent) 파이프라인 집계예요. bucket_script 집계를 사용해 버킷화된 집계의 여러 메트릭에 대해 사용자 지정 숫자 계산을 수행할 수 있어요. 예를 들어 다음과 같은 작업을 할 수 있어요:

  • 파생 및 복합 메트릭 계산하기
  • if/else 문을 사용한 조건부 로직 적용하기
  • 사용자 지정 점수 메트릭 같은 비즈니스 특정 KPI 계산하기

출처: 문서

본문

파라미터

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

파라미터 필수/선택 데이터 타입 설명
buckets_path 필수 Object 스크립트에서 사용할 메트릭을 식별하는, 변수 이름을 버킷화된 메트릭에 매핑한 맵이에요. 메트릭은 숫자여야 해요. 스크립트 변수(Script variables) 섹션을 참고하세요.
script 필수 String 또는 Object 실행할 스크립트예요. 인라인 스크립트, 저장된 스크립트 또는 스크립트 파일일 수 있어요. 스크립트는 buckets_path 파라미터에 정의된 변수 이름에 접근할 수 있어요. 숫자 값을 반환해야 해요.
gap_policy 선택 String 누락 데이터에 적용할 정책이에요. 유효한 값은 skip과 insert_zeros예요. 기본값은 skip이에요. 데이터 공백(Data gaps) 문서를 참고하세요.
format 선택 String DecimalFormat 형식 문자열이에요. 집계의 value_as_string 파라미터에 형식화된 출력을 반환해요.

스크립트 변수 (Script variables)

buckets_path 파라미터는 스크립트 변수 이름을 부모 집계의 메트릭에 매핑해요. 이 변수들은 스크립트에서 사용할 수 있어요.

bucket_script 및 bucket_selector 집계의 경우 buckets_path 파라미터는 여러 버킷 메트릭을 참조해야 하므로 문자열이 아니라 객체예요. buckets_path의 문자열 버전에 대한 설명은 파이프라인 집계(Pipeline aggregations) 페이지를 참고하세요.

다음 buckets_path는 sales_sum 메트릭을 total_sales 스크립트 변수에, item_count 메트릭을 item_count 스크립트 변수에 매핑해요:

"buckets_path": {
  "total_sales": "sales_sum",
  "item_count": "item_count"
}

매핑된 변수는 params 컨텍스트에서 접근할 수 있어요. 예를 들어:

  • params.total_sales
  • params.item_count

인라인 스크립팅 활성화 (Enabling inline scripting)

script 파라미터를 사용해 스크립트를 추가해요. 스크립트는 인라인, 파일 또는 인덱스에 있을 수 있어요. 인라인 스크립팅을 활성화하려면 config 폴더의 opensearch.yml 파일에 다음이 포함되어야 해요:

script.inline: on

예제

다음 예제는 OpenSearch Dashboards e-커머스 샘플 데이터에서 한 달 간격의 날짜 히스토그램을 생성해요. total_sales 하위 집계는 매월 판매된 모든 품목의 세금 포함 가격을 합산해요. vendor_count 집계는 매월 고유 판매업체의 총 수를 세어요. 마지막으로 avg_vendor_spend 집계는 인라인 스크립트를 사용해 매월 판매업체당 평균 지출액을 계산해요:

GET opensearch_dashboards_sample_data_ecommerce/_search
{
  "size": 0,
  "aggs": {
    "sales_per_month": {
      "date_histogram": {
        "field": "order_date",
        "calendar_interval": "month"
      },
      "aggs": {
        "total_sales": {
          "sum": {
            "field": "taxful_total_price"
          }
        },
        "vendor_count": {
          "cardinality": {
            "field": "products.manufacturer.keyword"
          }
        },
        "avg_vendor_spend": {
          "bucket_script": {
            "buckets_path": {
              "sales": "total_sales",
              "vendors": "vendor_count"
            },
            "script": "params.sales / params.vendors",
            "format": "$#,###.00"
          }
        }
      }
    }
  }
}

예제 응답

집계는 형식화된 월별 평균 판매업체 지출액을 반환해요:

{
  "took": 6,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 4675,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "sales_per_month": {
      "buckets": [
        {
          "key_as_string": "2025-03-01T00:00:00.000Z",
          "key": 1740787200000,
          "doc_count": 721,
          "vendor_count": {
            "value": 21
          },
          "total_sales": {
            "value": 53468.1484375
          },
          "avg_vendor_spend": {
            "value": 2546.1023065476193,
            "value_as_string": "$2,546.10"
          }
        },
        {
          "key_as_string": "2025-04-01T00:00:00.000Z",
          "key": 1743465600000,
          "doc_count": 3954,
          "vendor_count": {
            "value": 21
          },
          "total_sales": {
            "value": 297415.98046875
          },
          "avg_vendor_spend": {
            "value": 14162.665736607143,
            "value_as_string": "$14,162.67"
          }
        }
      ]
    }
  }
}

더 알아보기 (Learn more)