파생 속성 연산 참조
파생 속성(Derived property)은 연결된 객체(Object)의 값을 선택하거나 집계하고, 런타임 정의형에서는 산술 및 날짜 표현식으로 결과를 계산합니다. 정의 방식과 보안을 먼저 정한 뒤 결과 자료형에 맞는 연산을 선택합니다.
집계
링크(Link) 탐색 중 하나라도 여러 객체에 도달할 수 있으면 집계가 필요합니다. 링크 기반 선택이나 집계 안에 다른 파생 정의를 중첩하지 않습니다. 원본 속성까지 직접 탐색한 뒤 계산하며, 계산 결과를 다시 사용하려면 아래의 표현식 선언 순서를 따릅니다.
| Ontology Manager 이름 | Ontology SDK 이름 | 입력 속성 자료형 | 결과 |
|---|---|---|---|
| Count | $count | 대상 속성 없음 | Long |
| Average | avg | 수치형 | Double |
| Sum | sum | 수치형 | 확장된 수치형 |
| Minimum | min | 수치형, 문자열, Boolean, date, timestamp | 원본과 같음 |
| Maximum | max | 수치형, 문자열, Boolean, date, timestamp | 원본과 같음 |
| Approximate cardinality | approximateDistinct | 수치형, 문자열, Boolean, date, timestamp | Long |
| Exact cardinality | exactDistinct | 수치형, 문자열, Boolean, date, timestamp | Long |
| Collect list | collectList | vector를 제외한 자료형 | 원소 자료형의 배열 |
| Collect set | collectSet | vector를 제외한 자료형 | 원소 자료형의 배열 |
| Ontology Manager에서 제공하지 않음 | approximatePercentile | 수치형 | 원본과 같음, 런타임 정의형 전용 |
수치형에는 byte, short, integer, long, float, double과 decimal이 포함됩니다. 속성을 받는 집계는 해당 자료형의 단일 값 또는 배열을 사용할 수 있습니다. 배열 입력은 펼쳐서 계산하므로 array<integer>의 백분위 결과도 integer입니다.
합산 결과 자료형
Sum은 오버플로 위험을 줄이기 위해 다음과 같이 자료형을 확장합니다.
| 원본 | 결과 |
|---|---|
| short, integer | long |
| long | long |
| float | double |
| double | double |
| decimal | 필요하면 정밀도를 늘리고 소수 자릿수를 줄인 decimal |
목록과 집합의 수집 규칙
Collect list는 중복을 유지하고 Collect set은 중복을 제거합니다. Collect set은 중복을 먼저 제거한 뒤 개수 제한을 적용하므로 제한은 서로 다른 값의 개수입니다. 해당 속성의 값이 없는 객체는 건너뛰며 결과 배열 안에 null을 넣지 않습니다.
반환 개수의 기본값은 10, 최대값은 100입니다. 이 값은 표시할 결과를 제한하며 필터, 정렬과 집계가 평가하는 전체 값 집합을 제한하지 않습니다.
리듀서(Reducer)를 정의하지 않았다면 수집한 값의 순서를 보장하지 않습니다. 리듀서를 정의하면 대표 값 축소를 적용하지 않고 배열을 반환하는 경우에도 그 규칙으로 값을 정렬합니다. 리듀서는 표시나 인터페이스 구현에 사용할 대표 값을 고르지만 질의에 사용하는 전체 배열을 바꾸지 않습니다.
벡터 속성은 파생 속성에서 집계하거나 직접 선택할 수 없으며 파생 속성의 결과로 벡터를 만들 수도 없습니다.
런타임 표현식
산술 및 날짜 표현식은 런타임 정의형에만 있으며 @osdk/client 2.4.0 이상이 필요합니다. 정적 리터럴은 표현식에서 지원하지 않습니다.
기본 속성이나 앞에서 선언한 링크 선택 및 집계 결과를 조합할 수 있습니다. 첫 withProperties 호출에 선언한 파생 속성은 다음 withProperties 호출의 표현식에서 참조합니다. 같은 호출에 함께 선언했거나 뒤에서 선언할 계산을 참조하지 않습니다. 링크 선택 및 집계가 다른 파생 속성에서 직접 값을 가져오는 구성과도 구분합니다.
| 수치 연산 | 동작 |
|---|---|
| add | 두 값을 더합니다. |
| subtract | 첫 값에서 두 번째 값을 뺍니다. |
| multiply | 두 값을 곱합니다. |
| divide | 첫 값을 두 번째 값으로 나눕니다. |
| max | 두 값 중 큰 값을 반환합니다. |
| min | 두 값 중 작은 값을 반환합니다. |
| abs | 절댓값을 반환합니다. |
| negate | 부호를 반대로 바꿉니다. |
| 날짜 및 시각 연산 | 동작 |
|---|---|
| min | 두 값 중 이른 값을 반환합니다. |
| max | 두 값 중 늦은 값을 반환합니다. |
| extractPart | DAYS, MONTHS, QUARTERS 또는 YEARS를 추출합니다. |
직접 선택과 집계의 구분
| 링크 경로 | 선택 방식 |
|---|---|
| 모든 단계에서 최대 한 객체에 도달 | 속성을 직접 선택하거나 집계할 수 있습니다. |
| 어느 단계라도 여러 객체에 도달 가능 | 집계해야 합니다. |
| 다대다 링크 포함 | 항상 집계해야 하며 직접 선택할 수 없습니다. |
| 외래 키(Foreign key)가 배열인 일대다 링크 포함 | 어느 방향으로 탐색해도 여러 객체에 도달할 수 있으므로 집계해야 합니다. |
기본 속성과의 차이
| 작업 | 지원 및 조건 |
|---|---|
| 결과 반환 | 지원합니다. TypeScript OSDK에서 온톨로지 정의형은 $select에 명시합니다. withProperties로 추가한 런타임 정의형은 $select를 생략하면 기본 반환되며, $select를 사용하면 필요한 이름을 포함합니다. |
| 필터 | 결과 자료형에 맞는 정확 일치, 범위, 접두어, 구문, 전체 텍스트, 지리 및 상대 날짜 필터를 지원합니다. |
| 정렬 | 지원합니다. Workshop에서 파생 속성을 사용하는 객체 집합을 정렬하면 집합이 200행으로 제한됩니다. |
| 집계 및 Group by | 지원합니다. |
| 다른 파생 속성에서 참조 | 표현식의 앞선 선언 결과 사용을 지원합니다. 링크 선택과 집계는 다른 파생 속성을 원본으로 삼지 않고 실제 원본까지 직접 탐색합니다. |
| 액션 및 함수로 편집 | 읽기 전용이므로 지원하지 않습니다. |
| 기본 키 또는 링크 유형의 외래 키 | 지원하지 않습니다. |
집계별 상대 비용
값을 결과에 포함하여 불러오는 비용은 대체로 집계 요청과 비슷합니다. 파생 값으로 필터링하거나 정렬하는 검색은 더 많은 후보를 계산해야 하므로 비용이 커질 수 있습니다. 실제 사용량의 단위와 귀속은 온톨로지 질의 사용량에서 확인합니다.
| 집계 | 불러오기 비용 | 검색 비용 | 선택 기준 |
|---|---|---|---|
| Count | 낮음 | 높음 | 연결 객체 수에 영향을 받습니다. |
| Sum, Average, Minimum, Maximum | 낮음 | 높음 | 평가할 원본 및 연결 객체 수를 줄입니다. |
| Approximate cardinality | 낮음 | 높음 | 정확한 개수가 필수가 아니면 우선 검토합니다. |
| Exact cardinality | 보통 | 높음 | 정확도가 필요하고 추가 지연을 수용할 때 사용합니다. |
| Approximate percentile | 낮음 | 높음 | 런타임 정의형에만 있습니다. |
| Collect list, Collect set | 낮음 | 낮음 | 원본 속성 인덱스로 검색을 밀어낼 수 있습니다. 비용은 표시 개수보다 연결 객체 수에 영향을 받습니다. |
연결 객체 집합을 먼저 필터링하면 집계 대상을 줄일 수 있습니다. 탐색 횟수와 관계의 카디널리티(Cardinality)가 중간 결과 크기를 어떻게 늘리는지도 확인합니다. 지연을 수용하기 어려운 규모라면 미리 계산한 값을 사용하는 설계와 갱신 책임을 비교합니다.