V1 객체 집계 함수와 그룹화

객체 집계는 지정한 속성의 최솟값, 평균 같은 지표를 계산합니다. aggregation에 여러 함수를 넣을 수 있으며 함수의 나열 순서는 최종 결과에 영향을 주지 않습니다. groupBy를 여러 개 지정하면 해당 목록의 순서에 따라 그룹별 결과를 계산합니다. 선택적 query로 검색 조건을 적용하여 집계 대상을 제한할 수 있습니다.

POST /api/v1/ontologies/{ontologyRid}/objects/{objectType}/aggregate

집계 함수

각 집계는 type으로 구분합니다. count를 제외한 함수는 properties.{propertyApiName} 형식의 필수 문자열 field를 받습니다. 모든 함수의 name은 선택적 문자열이며 응답의 지표 이름을 지정합니다.

다음은 tenure, price, name 속성을 가진 가상 객체 유형에서 여러 집계를 요청하는 예시입니다. count는 field 없이 객체 수를 셉니다. 나머지 다섯 함수는 대상 속성의 null 값을 계산에서 제외합니다.

{
  "aggregation": [
    {"type": "count", "name": "total_count"},
    {"type": "max", "field": "properties.tenure", "name": "longest_tenure"},
    {"type": "min", "field": "properties.tenure", "name": "shortest_tenure"},
    {"type": "sum", "field": "properties.price", "name": "total_price"},
    {"type": "avg", "field": "properties.tenure", "name": "average_tenure"},
    {"type": "approximateDistinct", "field": "properties.name", "name": "distinct_name_count"}
  ]
}

그룹 수 제한과 제외 항목

가상 직원 데이터를 부서별로 묶어 최대 재직 기간을 구하는 요청입니다. maxGroupCount: 1로 결과 그룹 수를 제한했습니다.

{
  "aggregation": [
    {"type": "max", "field": "properties.tenure", "name": "longest_tenure"}
  ],
  "groupBy": [
    {"type": "exact", "field": "properties.department", "maxGroupCount": 1}
  ]
}

가상 집계 응답:

{
  "excludedItems": 20,
  "data": [
    {
      "metrics": [{"name": "longest_tenure", "value": 7}],
      "group": {"properties.department": "marketing"}
    }
  ]
}

data의 각 항목은 한 그룹입니다. 서로 다른 그룹이 maxGroupCount보다 많으면 일부 객체가 결과에서 제외되고 그 객체 수가 excludedItems에 반영됩니다. 위 예시의 20은 제외된 부서 수가 아니라 제외된 직원 수입니다.

exact

정확한 속성값으로 객체를 그룹화하며 모든 속성 유형을 지원합니다. field는 필수 문자열이고 maxGroupCount는 선택적 integer입니다. maxGroupCount의 기본값은 10,000입니다. 해당 속성이 null인 객체는 제외합니다.

{
  "aggregation": [{"type": "count", "name": "total_count"}],
  "groupBy": [
    {"type": "exact", "field": "properties.country", "maxGroupCount": 10}
  ]
}

fixedWidth

일정한 폭으로 값을 나누어 그룹화합니다. 필수 field 문자열과 필수 fixedWidth integer를 사용합니다. 지원 속성 유형은 byte, decimal, double, float, integer, long입니다. null 값은 제외합니다.

{
  "aggregation": [{"type": "count", "name": "total_count"}],
  "groupBy": [
    {"type": "fixedWidth", "field": "properties.age", "fixedWidth": 2}
  ]
}

ranges

지정한 범위들로 그룹을 나눕니다. field는 필수이고 ranges는 선택적인 AggregationRange 목록입니다. 지원 속성 유형은 byte, date, decimal, double, float, integer, long, timestamp입니다. null 값은 제외합니다.

대표적인 구간 표현은 시작값을 포함하는 gte와 끝값을 제외하는 lt입니다. 2023-01-01 이상, 2023-02-01 미만인 생일 구간에는 1월 31일이 들어가고 2월 1일은 들어가지 않습니다. 다음은 세 달을 각각 구분하는 요청입니다.

{
  "aggregation": [{"type": "count", "name": "total_count"}],
  "groupBy": [
    {
      "type": "ranges",
      "field": "properties.birthday",
      "ranges": [
        {"gte": "2020-01-01", "lt": "2020-02-01"},
        {"gte": "2020-02-01", "lt": "2020-03-01"},
        {"gte": "2020-03-01", "lt": "2020-04-01"}
      ]
    }
  ]
}

AggregationRange 자료형에 정의된 선택적 경계 필드는 다음과 같습니다. 각 값은 해당 속성의 값 표현을 사용합니다.

duration

date 또는 timestamp 속성을 시간 구간으로 그룹화합니다. field와 ISO 8601 기간 문자열 duration은 모두 필수입니다. null 값은 제외합니다.

P2DT3H4M5S는 2일 3시간 4분 5초, 즉 183,845초입니다. PT1H2M34S는 3,754초이고 PT15M은 15분입니다. date 속성은 P3D처럼 일 단위 그룹화만 지원하며 PT3H 같은 시간 단위를 사용하지 않습니다. timestamp 속성은 일, 시간, 분, 초를 지원하므로 PT10M이나 P3DT4H5M6S를 사용할 수 있습니다.

응답의 그룹 이름은 구간의 시작값입니다. reportDate를 P2D로 묶었을 때 2022-10-01 그룹에는 10월 1일과 2일이 포함됩니다.

{
  "aggregation": [{"type": "min", "field": "properties.stockPrice"}],
  "groupBy": [
    {"type": "duration", "field": "properties.reportDate", "duration": "P2D"}
  ]
}

가상 주가 집계 응답:

{
  "excludedItems": 0,
  "data": [
    {
      "group": {"properties.reportDate": "2022-10-01"},
      "metrics": [{"name": "min_stockPrice", "value": 200.04}]
    },
    {
      "group": {"properties.reportDate": "2022-10-03"},
      "metrics": [{"name": "min_stockPrice", "value": 198.51}]
    },
    {
      "group": {"properties.reportDate": "2022-10-05"},
      "metrics": [{"name": "min_stockPrice", "value": 197.3}]
    }
  ]
}

null 처리

속성을 지정한 groupBy에서는 그 속성이 null인 객체를 그룹 계산에서 제외합니다. 속성을 지정한 aggregation에서도 해당 속성이 null인 객체를 계산에서 제외합니다. 따라서 결과에는 null 그룹이나 null 지표값이 포함되지 않습니다.