객체 조회의 선택, 정렬과 페이지 조건
객체 데이터는 속성 API 이름과 값을 담은 맵입니다. 기본 키와 API 이름, RID 같은 메타데이터의 접두사는 조회 방식에 따라 다릅니다. 속성값의 JSON 표현은 단일 객체 조회를 따릅니다.
속성과 로드 수준
속성을 고르는 입력은 각 요청에 정의된 select 또는 selectV2를 사용합니다. 둘 다 제공하는 요청에서는 하나만 지정합니다. selectV2는 속성 식별자로 구조체 필드와 로드 수준을 선택할 수 있습니다. 기본 키는 반환 대상에 유지됩니다. 알 수 없는 속성 이름을 지정하면 PropertiesNotFound 오류가 발생합니다.
객체 집합 로드에서 벡터 속성은 select로 명시해야 반환합니다. null 값인 속성은 결과에서 생략합니다. excludeRid로 RID 조회를 생략하면 OSv2에서 성능이 개선될 수 있습니다.
defaultLoadLevel은 배열 축약이나 구조체 주 값 추출을 지정합니다. 속성별 noLoadLevel을 사용하면 그 속성에는 기본 로드 수준을 적용하지 않습니다. 해당 속성 유형에 적용할 수 없는 로드 수준은 무시합니다.
loadOntologyDefinedDerivedProperties의 기본값은 true입니다. 속성을 명시적으로 선택하지 않았을 때만 온톨로지 정의 파생 속성(OTDP)의 반환에 영향을 줍니다. select나 selectV2를 지정하면 선택한 속성을 반환합니다. 다중 유형 및 객체/인터페이스 로드에서 OTDP로 구현된 인터페이스 속성도 이 플래그로 제외하지 않습니다. OTDP 옵션은 실험적 기능이며 아직 일반 제공 기능이 아닙니다.
GET 목록의 정렬 문자열
List Objects와 List Linked Objects의 orderBy는 쉼표로 구분한 문자열입니다. 속성 앞에는 properties. 또는 p.를 붙이고, 방향은 :asc 또는 :desc로 지정합니다. 방향을 생략하면 오름차순입니다.
orderBy=properties.lastName:asc
orderBy=properties.lastName,properties.firstName,properties.age:desc
orderBy=p.lastName:asc
POST 검색과 로드의 정렬 객체
속성 또는 관련도로 결과를 정렬합니다. fields를 제공하면 orderType은 fields로 설정됩니다. 전체 orderBy를 생략하면 순서를 지정하지 않습니다. relevance는 텍스트 검색 또는 최근접 이웃의 일치 정도에 따른 점수 내림차순이며, 그 밖의 질의에서는 순서를 지정하지 않습니다. 관련도 정렬은 페이지 사이의 순서를 보장하지 않아 중복이나 누락이 발생할 수 있습니다. 완전성이 필요하면 한 페이지 범위에서 처리합니다. 비용이 클 수 있으므로 필요한 경우에 사용합니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
orderType | enum | 선택 | 허용값: fields, relevance. | |
fields | list<SearchOrderingV2> | 선택 |
fields의 구조
배열 항목은 SearchOrderingV2이며 자료형은 object입니다.
| 이름 | 자료형 | 필수 여부 | 의미와 조건 | 예시 값 |
|---|---|---|---|---|
field | string | 필수 | 속성의 API 이름입니다. Get Object Type 또는 Ontology Manager에서 확인합니다. | |
direction | string | 선택 | 정렬 방향은 asc 또는 desc입니다. |
페이지 크기와 스냅샷
| 조회 방식 | 페이지 크기 조건 |
|---|---|
| List Objects, List Linked Objects | 기본값은 1,000입니다. 페이지가 요청한 크기보다 작거나 클 수 있으며, 결과가 더 있으면 적어도 한 항목을 반환합니다. |
| Search Objects와 세 객체 집합 로드 API | pageSize는 상한입니다. 객체 크기가 내부 메모리 한도에 도달하면 더 적은 객체를 반환할 수 있습니다. |
페이지의 항목 수만 보고 마지막 페이지로 판단하지 않습니다. nextPageToken이 있으면 해당 요청의 pageToken에 전달합니다. 첫 페이지에는 토큰을 넣지 않습니다.
snapshot의 기본값은 false입니다. 이 모드에서는 페이지를 읽는 동안 데이터가 바뀌어 결과가 중복되거나 누락될 수 있습니다. true로 설정하면 페이지 조회를 시작하기 전의 일관된 상태를 사용합니다. 관련도 정렬의 페이지 간 순서 제한도 함께 확인해야 합니다.
Object Storage V1 기반 객체에 대해 목록과 객체 집합 로드 API는 누적 최대 10,000개를 반환합니다. 10,000개를 반환한 뒤 결과가 더 남은 상태에서 다음 페이지를 요청하면 ObjectsExceededLimit이 발생합니다. OSv2에는 이 10,000개 누적 반환 제한을 적용하지 않습니다. 별도의 검색 및 실행 제한은 API 사용 한도를 따릅니다.
메모리 실행과 미디어 참조
executeInMemoryOnly를 지원하는 요청에서 true를 지정하면 메모리 안에서 계산할 수 없는 요청은 오류로 종료됩니다. 기본값은 false입니다.
referenceSigningOptions.signMediaReferences는 사용 중단 권고 필드이며 true와 false 모두 무시합니다. 미디어 집합 뷰 기반의 단일 미디어 참조는 기본적으로 서명되며, 반환된 token으로 미디어 항목에 직접 접근할 수 있습니다. 호출자는 해당 객체에 접근할 권한이 필요하고 상위 미디어 집합의 조회 권한은 필요하지 않습니다. 미디어 참조 배열은 서명하지 않습니다.