V2 객체 집합 정의
ObjectSet은 온톨로지에서 어떤 객체를 선택할지 표현하는 정의입니다. type으로 집합 구성 방식을 구분하며 여러 방식은 다른 ObjectSet을 재귀적으로 입력받습니다. Ontology SQL의 tableProviders처럼 객체 집합을 입력받는 API에서 사용할 수 있습니다.
기본 집합과 조합
| type | 필드와 필수 여부 | 의미 |
|---|---|---|
base | 필수 objectType: string | 객체 유형 API 이름으로 기본 집합 선택 |
static | 선택적 objects: list<ObjectRid> | 지정한 객체 RID들로 집합 구성 |
reference | 필수 reference: string | 기존 객체 집합 참조 |
union | 선택적 objectSets: list<ObjectSet> | 입력 집합의 합집합 |
intersect | 선택적 objectSets: list<ObjectSet> | 입력 집합의 교집합 |
subtract | 선택적 objectSets: list<ObjectSet> | 집합 차 연산 |
filter | 필수 objectSet: ObjectSet, where: SearchJsonQueryV2 | 입력 집합에 검색 조건 적용 |
searchAround | 필수 objectSet: ObjectSet, link: string | 입력 객체에서 링크를 따라 연결된 객체 선택 |
interfaceLinkSearchAround | 필수 objectSet: ObjectSet, interfaceLink: string | 인터페이스 링크를 따라 연결된 객체 선택 |
ObjectRid는 객체의 고유 리소스 식별자이며 다른 Foundry API에서도 사용할 수 있습니다. static.objects에는 객체 기본 키 대신 객체 RID를 사용합니다. 링크와 인터페이스 링크의 API 이름은 Ontology Manager에서 확인합니다.
{"type": "base", "objectType": "exampleAircraft"}
filter.where의 28가지 검색 조건은 값 비교와 문자열, 상대 날짜, 공간 조건 및 논리 조합을 제공합니다.
인터페이스와 형 변환
| type | 필드와 필수 여부 | 동작 |
|---|---|---|
interfaceBase | 필수 interfaceType: string, 선택적 includeAllBaseObjectProperties: boolean | 지정 인터페이스를 구현하는 객체 선택 |
asType | 필수 entityType: string, objectSet: ObjectSet | 객체 유형 또는 인터페이스 유형으로 변환 |
asBaseObjectTypes | 필수 objectSet: ObjectSet | 각 객체의 기반 객체 유형으로 변환 |
interfaceBase는 기본적으로 해당 인터페이스 속성을 구현하는 속성만 반환합니다. includeAllBaseObjectProperties를 켜면 인터페이스의 공유 속성 유형(SPT)을 명시적으로 구현하지 않은 속성까지 기반 객체의 모든 속성을 반환합니다.
asType.entityType은 객체 유형 또는 인터페이스의 API 이름입니다. 지정한 객체 유형과 다르거나 지정한 인터페이스를 구현하지 않는 객체는 결과에서 제외합니다. asBaseObjectTypes는 인터페이스 속성에 한정하지 않고 각 기반 객체의 모든 속성을 반환하도록 변환합니다.
파생 속성과 메서드 입력
withProperties에는 필수 objectSet과 선택적 derivedProperties 맵이 있습니다. 맵의 키는 반환할 파생 속성 API 이름이고 값은 DerivedPropertyDefinition입니다. 이 기능은 실험적이며 아직 일반 제공 기능이 아닙니다.
methodInput은 MethodObjectSet 정의의 루트를 나타내며 추가 필드가 없습니다. 이 기능도 실험적이며 아직 일반 제공 기능이 아닙니다. selection 같은 메서드 객체 집합 정의에서 입력 기준을 표현할 때 사용합니다.
최근접 이웃
nearestNeighbors는 입력 벡터나 텍스트와 가까운 객체를 선택합니다. 대상 속성은 벡터 유형이어야 하며 온톨로지에서 유사도 함수와 근사 최근접 이웃(ANN) 검색을 구성해야 합니다.
| 필드 | 자료형 | 필수 여부 | 조건 |
|---|---|---|---|
objectSet | ObjectSet | 필수 | 검색할 입력 집합 |
propertyIdentifier | PropertyIdentifier | 필수 | 벡터 속성 선택 |
numNeighbors | integer | 필수 | 1 이상 500 이하 |
similarityThreshold | double | 선택 | 0 이상 1 이하인 유사도 임계값 |
query | vector 또는 text 구분자 객체 | 필수 | 검색할 벡터 또는 자동 임베딩할 텍스트 |
대상 문서가 요청한 수보다 적으면 있는 만큼 반환합니다. 결과에는 지정한 유사도 임계값을 넘는 객체만 포함합니다. 유사도 1은 동일함을, 0은 가장 낮은 유사도를 뜻합니다.
query.type: vector의 value는 선택적인 double 목록입니다. 벡터는 해당 속성에 정의된 임베딩 모델에 맞아야 하며 저장된 벡터와 차원 수가 같아야 합니다. query.type: text에는 필수 문자열 value를 넣으며, 해당 속성에 구성한 임베딩 모델로 자동 변환합니다.
{
"type": "nearestNeighbors",
"objectSet": {"type": "base", "objectType": "Document"},
"propertyIdentifier": {"type": "property", "apiName": "embedding"},
"numNeighbors": 5,
"query": {"type": "text", "value": "inspection record"}
}
가상 Document 유형의 embedding 속성에 ANN과 임베딩 모델을 구성한 예시입니다. 속성 선택의 구조체 및 로드 수준 변형은 PropertyIdentifier를 따릅니다.
관련도 점수
관련도 정렬을 제공하는 객체 집합 조회에서 orderBy의 orderType을 relevance로 설정하면 최근접 이웃 결과에 0이 아닌 점수를 반환합니다. 점수가 있는 결과는 점수 내림차순이며 같은 점수가 여러 객체에 있을 수 있습니다.
최근접 이웃 집합을 최근접 이웃이 아닌 집합과 합집합, 차집합 또는 교집합으로 조합하면 점수를 반환하지 않습니다. 이 점수 규칙은 해당 정렬 입력을 제공하는 조회 API의 계약입니다. 객체 집합을 SQL 테이블 제공자로 전달할 때는 SQL 실행 엔드포인트의 요청과 결과 형식을 사용합니다.