StructArray 필드 생성

하나의 엔티티에 구조화된 요소들의 정렬된 목록을 포함해야 할 때 StructArray 필드를 생성합니다. StructArray 필드는 요소 유형이 Struct인 Array 필드입니다. 각 Struct 요소는 동일한 스키마를 따르며, 스칼라 하위 필드, 벡터 하위 필드 또는 둘 다를 포함할 수 있습니다.

이 페이지에서는 Struct 스키마를 정의하고, 이를 StructArray 필드로 추가하며, 향후 검색 및 필터링을 위해 하위 필드를 선택하고, 데이터를 삽입하거나 인덱싱하기 전에 적용되는 스키마 규칙을 이해하는 방법을 설명합니다.

시작하기 전에

이 페이지에서는 tech_articles 라는 컬렉션을 사용합니다. 각 엔티티는 하나의 기술 문서를 나타내며, chunks 필드는 청크 수준 데이터를 Struct 요소로 저장합니다.

필드	유형	목적
`doc_id`	`INT64`	문서의 기본 키입니다.
`title`	`VARCHAR`	기사 제목.
`category`	`VARCHAR`	기사 수준의 카테고리.
`title_vector`	`FLOAT_VECTOR`	기사 수준의 벡터 필드로, 이후 하이브리드 검색 예제에서 사용됩니다.
`chunks`	`ARRAY`	청크 수준의 텍스트, 메타데이터 및 임베딩을 저장하는 StructArray 필드.

chunks StructArray 필드에는 다음 하위 필드가 포함됩니다.

하위 필드	유형	용도
`text`	`VARCHAR`	청크 텍스트.
`section`	`VARCHAR`	`index`, `search`, `filter` 와 같은 섹션 이름.
`page`	`INT64`	청크의 페이지 번호 또는 논리적 위치.
`quality_score`	`FLOAT`	스칼라 필터링 및 범위 예제에서 사용되는 청크 수준 점수.
`has_code`	`BOOL`	청크에 코드가 포함되어 있는지 여부.
`emb_list_vector`	`FLOAT_VECTOR`	`MAX_SIM*` 메트릭을 사용한 EmbeddingList 검색을 위한 벡터 하위 필드.
`emb`	`FLOAT_VECTOR`	일반 벡터 메트릭을 사용하는 요소 수준 검색을 위한 벡터 하위 필드.

벡터 필드 또는 벡터 하위 필드는 하나의 인덱스만 허용합니다. EmbeddingList 검색과 요소 수준 검색이 모두 필요한 경우, 두 개의 별도 벡터 하위 필드를 정의하십시오. 이 예에서 chunks[emb_list_vector] 는 EmbeddingList 검색용이고, chunks[emb] 는 요소 수준 검색용입니다.

지원되는 하위 필드 데이터 유형

StructArray 필드는 각 Struct 하위 필드에 대해 하나의 배열 값을 저장합니다. Struct 스키마를 정의할 때는 지원되는 스칼라 및 벡터 계열에서 하위 필드 유형을 선택하십시오.

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 필드를 포함할 수 없습니다.

버전별 지원, null 허용 동작 및 기타 제한 사항에 대해서는 StructArray 제한 사항을 참조하십시오.

StructArray 필드가 포함된 컬렉션 만들기

StructArray 필드를 생성하려면 먼저 각 요소에서 사용되는 Struct 스키마를 정의하십시오. 그런 다음 Array 필드를 추가하고 해당 요소 유형을 Struct로 설정하십시오.

컬렉션 스키마를 생성합니다.
기본 키 및 기사 수준 필드와 같은 컬렉션 수준 필드를 추가합니다.
StructArray 필드 내에 저장될 요소에 대한 Struct 스키마를 생성합니다.
Struct 스키마에 스칼라 및 벡터 하위 필드를 추가합니다.
element_type=DataType.STRUCT 를 사용하여 Array 필드를 추가합니다.
struct_schema 을 Struct 스키마로 설정합니다.
max_capacity 을 설정하여 각 엔티티가 필드에 저장할 수 있는 Struct 요소의 수를 제한합니다.

from pymilvus import MilvusClient, DataType

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus",
)

schema = client.create_schema(
    auto_id=False,
    enable_dynamic_field=False,
)

# Collection-level fields.
schema.add_field(
    field_name="doc_id",
    datatype=DataType.INT64,
    is_primary=True,
)
schema.add_field(
    field_name="title",
    datatype=DataType.VARCHAR,
    max_length=512,
)
schema.add_field(
    field_name="category",
    datatype=DataType.VARCHAR,
    max_length=128,
)
schema.add_field(
    field_name="title_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Struct schema used by each element in the StructArray field.
chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=65535,
)
chunk_schema.add_field(
    field_name="section",
    datatype=DataType.VARCHAR,
    max_length=128,
)
chunk_schema.add_field(
    field_name="page",
    datatype=DataType.INT64,
)
chunk_schema.add_field(
    field_name="quality_score",
    datatype=DataType.FLOAT,
)
chunk_schema.add_field(
    field_name="has_code",
    datatype=DataType.BOOL,
)

# Vector subfield for EmbeddingList search.
chunk_schema.add_field(
    field_name="emb_list_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Vector subfield for element-level search.
chunk_schema.add_field(
    field_name="emb",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

# Add the StructArray field.
schema.add_field(
    field_name="chunks",
    datatype=DataType.ARRAY,
    element_type=DataType.STRUCT,
    struct_schema=chunk_schema,
    max_capacity=1000,
)

client.create_collection(
    collection_name="tech_articles",
    schema=schema,
)

StructArray 필드 경로 이해

StructArray 필드를 생성한 후에는 structArray[subfield] 경로 구문을 사용하여 해당 하위 필드를 참조하십시오. 인덱스를 생성하거나, 벡터 하위 필드를 검색하거나, 하위 필드를 출력하거나, 스칼라 필터를 구축할 때 이 구문을 사용하십시오.

경로	의미	일반적인 사용법
`chunks[text]`	각 Struct 요소 내부의 `text` 하위 필드.	출력 필드 또는 스칼라 필터링.
`chunks[section]`	각 청크에 대한 섹션 레이블.	스칼라 필터링.
`chunks[quality_score]`	청크 수준의 품질 점수.	스칼라 필터링 또는 스칼라 인덱스.
`chunks[emb_list_vector]`	임베딩 목록으로 사용되는 벡터 하위 필드.	`MAX_SIM*` 를 사용한 EmbeddingList 검색.
`chunks[emb]`	각 Struct 요소가 독립적으로 사용하는 벡터 하위 필드.	요소 수준의 벡터 검색.

StructArray 필드를 null 허용 가능하게 만들기

Milvus v3.0.x는 nullable StructArray 필드를 지원합니다. nullable StructArray 필드를 사용하면 엔티티가 StructArray 필드 전체에 대해 null 를 저장할 수 있습니다.

schema.add_field(
    field_name="chunks",
    datatype=DataType.ARRAY,
    element_type=DataType.STRUCT,
    struct_schema=chunk_schema,
    max_capacity=1000,
    nullable=True,
)

경고 Nullable StructArray 필드는 Milvus v3.0.x에서만 사용할 수 있습니다. Nullable StructArray 필드의 경우, 엔티티는 유효한 StructArray 값을 제공하거나 전체 필드를 null 로 설정할 수 있습니다. 유효한 StructArray 값을 삽입할 때는 모든 하위 필드가 null이거나 유효한 값을 가져야 합니다. 일부 하위 필드는 null로, 다른 하위 필드는 유효한 값으로 설정된 엔티티를 삽입하면 오류가 발생합니다. 자세한 내용은 StructArray 제한 사항을 참조하십시오.

기존 컬렉션에 StructArray 필드 추가

Milvus v3.0.x는 기존 컬렉션에 StructArray 필드를 추가하는 기능을 지원합니다. 컬렉션에 이미 존재하는 엔티티에는 새 필드의 값이 없으므로, 추가되는 StructArray 필드는 null 허용형이어야 합니다.

기존 컬렉션에 StructArray 필드를 추가하려면 먼저 Struct 스키마를 정의해야 합니다. 그런 다음 ` add_collection_struct_field() `를 호출하고 ` nullable=True`를 설정합니다.

chunk_schema = client.create_struct_field_schema()
chunk_schema.add_field(
    field_name="text",
    datatype=DataType.VARCHAR,
    max_length=65535,
)
chunk_schema.add_field(
    field_name="section",
    datatype=DataType.VARCHAR,
    max_length=128,
)
chunk_schema.add_field(
    field_name="page",
    datatype=DataType.INT64,
)
chunk_schema.add_field(
    field_name="quality_score",
    datatype=DataType.FLOAT,
)
chunk_schema.add_field(
    field_name="has_code",
    datatype=DataType.BOOL,
)
chunk_schema.add_field(
    field_name="emb_list_vector",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)
chunk_schema.add_field(
    field_name="emb",
    datatype=DataType.FLOAT_VECTOR,
    dim=4,
)

client.add_collection_struct_field(
    collection_name="tech_articles",
    field_name="chunks",
    struct_schema=chunk_schema,
    max_capacity=1000,
    nullable=True,
)

StructArray 필드가 추가된 후, 기존 엔티티는 새 필드의 모든 하위 필드에 대해 ` null `를 반환합니다.

StructArray 필드가 생성된 후에는 해당 기존 StructArray 필드에 새로운 하위 필드를 추가할 수 없습니다. 나중에 추가 요소 속성이 필요한 경우, ` drop_collection_field() `를 호출하여 StructArray 필드를 삭제한 다음, 업데이트된 Struct 스키마를 사용하여 새로운 StructArray 필드를 추가하십시오.

client.drop_collection_field(
    collection_name="tech_articles",
    field_name="chunks",
)

client.add_collection_struct_field(
    collection_name="tech_articles",
    field_name="chunks",
    struct_schema=updated_chunk_schema,
    max_capacity=1000,
    nullable=True,
)

스키마 규칙

규칙	설명
Struct는 Array 요소 유형으로 사용됩니다.	`element_type=STRUCT` 를 사용하여 StructArray 필드를 Array 필드로 생성하십시오. Struct를 최상위 컬렉션 필드로 생성하지 마십시오.
모든 요소는 하나의 스키마를 공유합니다.	동일한 StructArray 필드 내의 모든 Struct 요소는 해당 필드에 대해 정의된 Struct 스키마를 따릅니다.
`max_capacity` 는 필수입니다.	이 필드는 각 엔티티가 StructArray 필드에 저장할 수 있는 Struct 요소의 수를 제한합니다.
지원되는 하위 필드 유형만 사용할 수 있습니다.	StructArray에서 지원하는 스칼라 및 벡터 하위 필드 유형을 사용하십시오. JSON, Geometry, Text, Timestamptz, SparseFloatVector 또는 중첩된 Struct/Array 하위 필드는 정의하지 마십시오.
벡터 하위 필드는 검색 전에 인덱스가 필요합니다.	벡터 검색을 실행하기 전에 `chunks[emb_list_vector]` 또는 `chunks[emb]` 와 같은 경로에 인덱스를 생성하십시오.
벡터 하위 필드 하나당 인덱스는 하나만 있어야 합니다.	EmbeddingList 검색과 요소 수준 검색이 모두 필요한 경우, 두 개의 별도 벡터 하위 필드를 생성하십시오.
기존 StructArray 하위 필드는 고정되어 있습니다.	StructArray 필드를 생성한 후에는 동일한 StructArray 필드에 더 이상 하위 필드를 추가할 수 없습니다.
Struct 내에서는 함수가 지원되지 않습니다.	StructArray 필드 내의 필드나 하위 필드에 대한 함수를 정의하지 마십시오.
스칼라 하위 필드는 필터 요구 사항에 부합해야 합니다.	`section`, `quality_score` 또는 `has_code` 와 같은 필드는 나중에 필터링, 그룹화 또는 출력이 필요한 경우에만 추가하십시오.

흔히 저지르는 실수

DataType.STRUCT 를 Array 필드의 요소 유형으로 사용하는 대신 최상위 컬렉션 필드로 생성하는 경우.
StructArray 필드에 max_capacity 를 설정하는 것을 잊는 경우.
JSON, Geometry, Text, Timestamptz, SparseFloatVector, 중첩된 Array, 중첩된 Struct 또는 Array-of-Struct와 같이 지원되지 않는 하위 필드 유형을 정의하는 경우.
String 를 하위 필드 유형으로 사용하는 경우. VARCHAR 를 사용하고 max_length 를 설정하십시오.
EmbeddingList 검색과 요소 수준 검색 모두에 하나의 벡터 하위 필드를 사용하는 경우.
벡터 하위 필드만 추가하고, section, quality_score 또는 has_code 와 같이 필터링에 필요한 스칼라 하위 필드를 생략하는 경우.
벡터 하위 필드를 $[...] 스칼라 술어 입력으로 취급합니다. 벡터 검색에는 벡터 하위 필드를 사용하고, 스칼라 술어에는 스칼라 하위 필드를 사용합니다.
필드가 생성된 후에도 기존 StructArray 필드에 새로운 하위 필드를 추가할 수 있다고 가정합니다.
필수 경로 구문인 chunks[emb] 또는 chunks[emb_list_vector] 대신 chunks.emb 또는 chunks.emb_list_vector 을 사용합니다.
Nullable StructArray의 동작을 모든 대상 버전에서 지원되는 것으로 간주합니다.

다음 단계

StructArray 필드에 중첩된 데이터를 삽입하려면 StructArray 필드에 데이터 삽입을 참조하십시오.
벡터 및 스칼라 인덱스를 생성하려면 StructArray 필드 인덱싱을 참조하십시오.
StructArray 벡터 하위 필드를 검색하려면 StructArray를 사용한 기본 벡터 검색을 참조하십시오.
지원되는 데이터 유형, null 허용 동작 및 버전별 제한 사항을 확인하려면 ‘StructArray 제한 사항’을 참조하십시오.

번역 DeepL

관리형 Milvus를 무료로 사용해 보세요

Zilliz Cloud는 번거로움이 없으며, Milvus 기반으로 10배 더 빠릅니다.

시작하기

피드백

이 페이지가 도움이 되었나요?