StructArray 제한 사항
StructArray 지원은 스키마 정의, 삽입 페이로드, 인덱싱, 검색 모드 및 StructArray 전용 필터에 걸쳐 있습니다. 프로덕션 환경에서 StructArray 동작을 활용하기 전에 이 페이지를 제한 사항 참조 자료로 활용하십시오.
대부분의 StructArray 제한 사항은 StructArray 스키마 모델, 벡터 하위 필드에 대해 선택한 검색 모드, 컬렉션이 실행되는 Milvus 버전의 세 가지 중 하나에서 비롯됩니다.
제한 사항 요약
| 영역 | 제한 사항 |
|---|---|
| 스키마 구조 | Struct는 Array 필드의 요소 유형으로만 사용할 수 있습니다. Struct는 최상위 컬렉션 필드로 지원되지 않습니다. |
| 하위 필드 스키마 | 동일한 StructArray 필드 내의 모든 Struct 요소는 하나의 미리 정의된 Struct 스키마를 공유합니다. |
| 용량 | max_capacity 는 필수 항목이며, 하나의 엔티티가 StructArray 필드에 저장할 수 있는 Struct 요소의 수를 제한합니다. |
| 하위 필드 변경 | StructArray 필드가 생성된 후에는 기존 StructArray 필드에 하위 필드를 추가할 수 없습니다. |
| 하위 필드 경로인덱스, 검색 대상, 출력 필드 및 필터에는 xml-ph-0001@deepl.internal와 같은 xml-ph-0000@deepl.internal 경로를 사용하십시오. | 인덱스, 검색 대상, 출력 필드 및 필터에는 chunks[emb] 와 같은 structArray[subfield] 경로를 사용하십시오. chunks.emb 는 사용하지 마십시오. |
| 삽입 형상 | StructArray 필드를 객체 배열로 삽입하십시오. 삽입 페이로드 내부에서는 경로 구문을 사용하지 마십시오. |
| 벡터 인덱스 | 벡터 필드 또는 벡터 하위 필드는 하나의 인덱스만 허용합니다. EmbeddingList 검색과 요소 수준 검색에는 별도의 벡터 하위 필드를 사용하십시오. |
| 함수 | StructArray 필드 내부의 필드나 하위 필드에서는 필드 함수가 지원되지 않습니다. |
| Nullable 필드 | Nullable StructArray 필드는 버전 제한이 있습니다. 지원되는 경우, null은 개별 Struct 요소가 아닌 전체 StructArray 필드에 적용됩니다. |
| 동적 필드 추가 | 기존 컬렉션에 StructArray 필드를 추가하는 기능은 버전에 따라 지원 여부가 다르며, 추가되는 필드는 null 허용형이어야 합니다. |
스키마 제한
| 제한 | 세부 정보 |
|---|---|
| Struct는 최상위 필드 유형이 아닙니다. | datatype=DataType.ARRAY 로 StructArray 필드를 생성하고, element_type=DataType.STRUCT 및 struct_schema 를 지정합니다. |
| 모든 요소는 하나의 스키마를 공유합니다. | StructArray 필드의 모든 Struct 요소는 동일한 하위 필드 목록과 하위 필드 데이터 유형을 따릅니다. |
max_capacity 는 필수입니다. | 하나의 엔티티에 포함된 Struct 요소의 수는 StructArray 필드에 대해 구성된 max_capacity 을 초과해서는 안 됩니다. |
| 기존 하위 필드는 고정되어 있습니다. | 기존 StructArray 필드에는 새로운 하위 필드를 추가할 수 없습니다. 하위 필드 스키마를 변경하려면 StructArray 필드를 삭제한 다음, 업데이트된 스키마로 다시 추가하십시오. |
| 중첩된 StructArray는 지원되지 않습니다. | StructArray 필드는 중첩된 Array, ArrayOfVector, Struct 또는 ArrayOfStruct 하위 필드를 포함할 수 없습니다. |
| StructArray 내부에서는 함수가 지원되지 않습니다. | StructArray 필드나 그 하위 필드에 대해 필드 함수를 정의하지 마십시오. |
스키마 생성 예제는 StructArray 필드 생성을 참조하십시오.
지원되는 하위 필드 데이터 유형
StructArray 하위 필드는 물리적 배열 스타일의 저장소에 매핑됩니다. 다음 표에는 지원되는 물리적 유형과 지원되지 않는 물리적 유형이 나열되어 있습니다.
| Struct 하위 필드의 물리적 유형 | 지원 | 참고 |
|---|---|---|
Array | 지원됨 | 서브필드를 ` DataType.BOOL` 형태로 정의하십시오. |
Array | 지원됨 | 서브필드를 DataType.INT8, DataType.INT16, DataType.INT32 또는 DataType.INT64 로 정의합니다. |
Array | 지원됨 | 서브필드를 DataType.FLOAT 또는 DataType.DOUBLE 로 정의합니다. |
Array | 지원됨서브필드를 xml-ph-0000@deepl.internal 또는 xml-ph-0001@deepl.internal로 정의합니다. | 하위 필드를 DataType.VARCHAR 로 정의하고 max_length 를 설정합니다. |
ArrayOfVector | 지원됨 | 서브 필드를 DataType.FLOAT_VECTOR 로 정의하고 dim 를 설정하십시오. |
ArrayOfVector | 지원됨 | 서브 필드를 DataType.FLOAT16_VECTOR 로 정의하고 dim 를 설정하십시오. |
ArrayOfVector | 지원됨 | 서브 필드를 DataType.BFLOAT16_VECTOR 로 정의하고 dim 를 설정하십시오. |
ArrayOfVector | 지원됨 | 서브 필드를 DataType.INT8_VECTOR 로 정의하고 dim 를 설정하십시오. |
ArrayOfVector | 지원됨 | 서브 필드를 DataType.BINARY_VECTOR 로 정의하고 dim 를 설정하십시오. |
ArrayOfVector | 지원되지 않음 | StructArray 필드에서는 스파스 벡터 하위 필드가 지원되지 않습니다. |
Array | 지원되지 않음 | String 대신 VARCHAR 을 사용하십시오. |
Array | 지원되지 않음 | StructArray 필드에서는 JSON 하위 필드가 지원되지 않습니다. |
Array | 지원되지 않음 | StructArray 필드에서는 지오메트리 하위 필드 및 GIS 함수가 지원되지 않습니다. |
Array | 지원되지 않음 | StructArray 필드에서는 텍스트 하위 필드가 지원되지 않습니다. |
Array | 지원되지 않음 | StructArray 필드에서는 Timestamptz 하위 필드 및 시간 기반 표현식이 지원되지 않습니다. |
중첩된 Array, ArrayOfVector, Struct 또는 ArrayOfStruct | 지원되지 않음 | StructArray 필드는 중첩된 배열, 벡터 배열, Struct 또는 Array-of-Struct 하위 필드를 지원하지 않습니다. |
Nullable 및 동적 스키마 제한
Nullable StructArray의 동작 및 동적 StructArray 필드 추가는 버전에 따라 제한됩니다.
| 기능 | 제한 |
|---|---|
| Nullable StructArray 필드 | Nullable StructArray 및 Nullable 벡터 배열을 지원하는 버전에서만 지원됩니다. |
| Python의 null 값 | Python에서 null StructArray 값을 삽입하려면 ` None `를 사용하십시오. ` Null ` 또는 ` null`는 사용하지 마십시오. |
| Null 적용 범위 | Null은 StructArray 필드 전체에 적용됩니다. 예를 들어, chunks=None 는 chunks 가 nullable일 때만 유효합니다. |
| 부분적으로 null인 StructArray 값 | StructArray 필드에 유효한 배열 값이 포함된 경우, 동일한 값 내에서 null인 하위 필드 배열과 유효한 하위 필드 배열을 혼합하여 사용해서는 안 됩니다. |
| StructArray 필드의 동적 추가 | 기존 컬렉션에 StructArray 필드를 추가하는 기능은 동적 StructArray 필드 지원이 포함된 버전에서만 지원됩니다. |
| 동적 추가에 대한 null 허용 요구 사항 | 기존 컬렉션에 추가된 StructArray 필드는 기존 엔티티에 새 필드의 값이 없으므로 null 허용 가능해야 합니다. |
| 동적 추가 후의 기존 엔티티 | 기존 엔티티는 추가된 StructArray 필드의 모든 하위 필드에 대해 ` null `를 반환합니다. |
Milvus v3.0.x에서는 nullable StructArray 필드, nullable 벡터 배열 및 동적 StructArray 필드 추가 기능을 사용할 수 있습니다.
nullable StructArray 필드를 사용한 삽입 예제는 StructArray 필드에 데이터 삽입을 참조하십시오.
삽입 제한
| 제한 | 세부 정보 |
|---|---|
| 페이로드 형상 | StructArray 필드를 chunks: [{"text": "...", "emb": [...]}] 와 같은 Struct 객체 배열로 삽입합니다. |
| 하위 필드 이름 | 각 Struct 객체 내부에서는 chunks[text] 와 같은 경로가 아닌, text 및 emb 와 같은 하위 필드 이름을 사용하십시오. |
| 스키마 준수 | 각 Struct 요소는 Struct 스키마와 일치해야 합니다. |
| 용량 | 하나의 엔티티에 포함된 Struct 요소의 수는 max_capacity 을 초과해서는 안 됩니다. |
| 벡터 차원 | 벡터 값은 해당 벡터 하위 필드에 대해 구성된 dim 와 일치해야 합니다. |
| 검색 모드 중복 | EmbeddingList 검색과 요소 수준 검색이 모두 필요한 경우, 벡터를 두 개의 별도 벡터 하위 필드에 작성하십시오. |
인덱스 및 메트릭 제한
StructArray 벡터 하위 필드는 EmbeddingList 검색 또는 요소 수준 검색 중 하나를 위해 인덱싱될 수 있습니다. 각 벡터 필드 또는 벡터 하위 필드는 하나의 인덱스만 허용하므로, 동일한 벡터 하위 필드에서 두 메트릭 계열을 모두 사용할 수는 없습니다.
| 검색 모드 | 메트릭 계열 | 결과 수준 |
|---|---|---|
| EmbeddingList 검색 | MAX_SIM, MAX_SIM_COSINE, MAX_SIM_IP, MAX_SIM_L2 또는 이진 MAX_SIM_* 메트릭 | 엔티티 수준 결과. |
| 요소 수준 검색 | L2, IP, COSINE, HAMMING 와 같은 일반 벡터 메트릭 또는 JACCARD | 일치하는 요소 오프셋을 포함할 수 있는 요소 수준 결과. |
두 모드가 모두 필요한 경우 별도의 벡터 하위 필드를 사용하십시오. 예를 들어, EmbeddingList 검색에는 chunks[emb_list_vector] 를, 요소 수준 검색에는 chunks[emb] 를 사용하십시오.
컬렉션 스키마를 계획할 때 StructArray 벡터 하위 필드는 벡터 하위 필드로 간주됩니다. 벡터 필드와 벡터 하위 필드의 총 개수가 대상 버전 및 서비스 계층의 제한 범위 내에 있도록 유지하십시오.
지원되는 인덱스 유형 및 메트릭 유형 행렬에 대해서는 ‘StructArray 필드 색인’을 참조하십시오.
검색 제한
| 검색 동작 | 지원 및 제한 사항 |
|---|---|
| 기본 EmbeddingList 검색 | MAX_SIM* 메트릭으로 인덱싱된 StructArray 벡터 하위 필드에서 지원됩니다. 엔티티 수준의 결과를 반환합니다. |
| 기본 요소 수준 검색 | 일반 벡터 메트릭으로 인덱싱된 StructArray 벡터 하위 필드에서 지원됩니다. 일치하는 요소의 오프셋을 반환할 수 있습니다. |
| 범위 검색 | 대상 버전의 검색 모드 및 인덱스/메트릭 지원 여부에 따라 지원됩니다. 요소 수준 StructArray 요청에 대한 하이브리드 범위 검색 동작 여부는 대상 버전을 확인하십시오. |
| 그룹화 검색 | 요소 수준 그룹화 검색은 오프셋을 반환할 수 있습니다. 요소 수준 StructArray 요청에 대한 하이브리드 검색의 그룹화 동작은 버전에 따라 다릅니다. |
| 하이브리드 검색 | 하이브리드 검색 요청은 대상 버전이 해당 검색 조합을 지원하는 경우에만 StructArray 벡터 하위 필드 요청을 포함할 수 있습니다. 각 요청은 여전히 인덱싱된 벡터 하위 필드의 메트릭 패밀리를 따릅니다. |
| 오프셋 출력 | 오프셋은 요소 수준 검색 결과에 사용할 수 있습니다. EmbeddingList 검색은 엔티티 수준 결과를 반환하며, 요소 오프셋을 주요 결과 단위로 사용하지 않습니다. |
필터 및 연산자 제한
StructArray 스칼라 필터링은 ` element_filter ` 및 ` MATCH_* ` 계열과 같은 StructArray 연산자에 의해 처리됩니다. 자세한 술어 지원 매트릭스는 StructArray 연산자 문서에 수록되어 있습니다.
개요:
$[subfield]는 StructArray 연산자 내부에서만 사용하십시오.스칼라 술어에는 스칼라 하위 필드를 사용하십시오.
$[...]스칼라 술어 입력으로 벡터 하위 필드를 사용하지 마십시오.JSON 경로 구문, JSON 함수, 배열 컨테이너 함수, 텍스트 일치 함수, 기하학/GIS 함수 및 Timestamptz 표현식은 StructArray 요소 수준 조건식에서 지원되지 않습니다.
단순한 부울 표현식 대신
$[has_code] == true와 같은 명시적인 부울 비교를 우선적으로 사용하십시오.
관련 페이지
StructArray 필드를 생성하려면 StructArray 필드 생성을 참조하십시오.
데이터를 삽입하려면 StructArray 필드에 데이터 삽입을 참조하십시오.
벡터 및 스칼라 인덱스를 생성하려면 StructArray 필드 인덱싱을 참조하십시오.
StructArray 필터 구문을 확인하려면 ‘StructArray 연산자’를 참조하십시오.
