Milvus
Zilliz
별표45.7K데모 예약하기시작하기
홈페이지
  • 홈
  • 문서

  • 사용자 안내서

  • 스키마 및 데이터 필드

  • StructArray

  • StructArray 필드에 데이터 삽입

StructArray 필드에 데이터 삽입

각 엔티티가 정렬된 구조화된 요소 목록을 포함하는 경우, StructArray 필드에 데이터를 삽입합니다. 삽입 페이로드에서 StructArray 필드는 객체 배열로 표현됩니다. 각 객체는 하나의 Struct 요소를 나타내며, 컬렉션 스키마에 정의된 Struct 하위 필드 이름을 사용합니다.

이 페이지에서는 ‘StructArray 필드 생성’의 tech_articles 컬렉션을 사용합니다. 각 엔티티는 기술 문서이며, ‘ chunks ’ 필드는 문서 청크를 Struct 요소로 저장합니다.

시작하기 전에

컬렉션 스키마에 이미 chunks StructArray 필드가 포함되어 있는지 확인하십시오.

필드유형삽입 값
doc_idINT64기사 ID.
titleVARCHAR기사 제목.
categoryVARCHAR기사 카테고리.
title_vectorFLOAT_VECTOR기사 수준 임베딩.
chunksARRAY청크 객체 목록.

chunks 에 포함된 각 객체는 Struct 스키마를 따라야 합니다.

하위 필드유형삽입 값
textVARCHAR청크 텍스트.
sectionVARCHARindex, search, filter 와 같은 섹션 이름.
pageINT64페이지 번호 또는 논리적 위치.
quality_scoreFLOAT청크 수준 점수.
has_codeBOOL청크에 코드가 포함되어 있는지 여부.
emb_list_vectorFLOAT_VECTOREmbeddingList 검색을 위해 작성된 벡터.
embFLOAT_VECTOR요소 수준 검색을 위해 작성된 벡터.

삽입 페이로드에서 ` chunks `는 값이 Struct 객체 배열인 일반 필드입니다. 각 객체 내부에서는 ` text ` 및 ` emb`와 같은 하위 필드 이름을 사용합니다. ` chunks[text] ` 또는 ` chunks[emb]`와 같은 경로 구문은 삽입 후 인덱스를 생성하거나, 검색을 실행하거나, 필터를 구축하거나, 출력 필드를 지정할 때만 사용하십시오.

삽입 페이로드의 구조를 이해하세요

chunks 값은 Struct 요소의 배열입니다. 각 요소는 키가 하위 필드 이름인 객체입니다.

{
  "doc_id": 1,
  "title": "StructArray indexing patterns",
  "category": "index",
  "title_vector": [0.12, 0.08, 0.32, 0.48],
  "chunks": [
    {
      "text": "Create one index for each vector subfield.",
      "section": "index",
      "page": 1,
      "quality_score": 0.96,
      "has_code": false,
      "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
      "emb": [0.10, 0.20, 0.30, 0.40]
    },
    {
      "text": "Use MAX_SIM metrics for EmbeddingList search.",
      "section": "index",
      "page": 2,
      "quality_score": 0.91,
      "has_code": true,
      "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
      "emb": [0.16, 0.24, 0.35, 0.45]
    }
  ]
}

emb_list_vector emb 는 서로 다른 검색 모드를 지원하기 때문에 별도의 벡터 하위 필드입니다. EmbeddingList 검색은 StructArray 필드의 모든 벡터를 하나의 임베딩 목록으로 취급하며, 메트릭을 포함한 엔티티 수준 결과를 반환합니다. 요소 수준 검색은 각 Struct 요소를 독립적으로 검색하며, 일치하는 요소의 오프셋을 반환할 수 있습니다. 이 예제에서는 단순화를 위해 두 필드 모두에 동일한 벡터 값을 저장합니다. 실전 애플리케이션에서는 두 검색 모드 모두 동일한 청크 임베딩을 사용하는 경우 두 하위 필드에 동일한 임베딩을 저장하거나, 두 검색 모드가 서로 다른 표현 방식을 사용하는 경우 서로 다른 임베딩을 저장할 수 있습니다. MAX_SIM*

행 삽입

client.insert() 를 사용하여 StructArray 값을 포함하는 행을 삽입합니다.

from pymilvus import MilvusClient

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

data = [
    {
        "doc_id": 1,
        "title": "StructArray indexing patterns",
        "category": "index",
        "title_vector": [0.12, 0.08, 0.32, 0.48],
        "chunks": [
            {
                "text": "Create one index for each vector subfield.",
                "section": "index",
                "page": 1,
                "quality_score": 0.96,
                "has_code": False,
                "emb_list_vector": [0.10, 0.20, 0.30, 0.40],
                "emb": [0.10, 0.20, 0.30, 0.40],
            },
            {
                "text": "Use MAX_SIM metrics for EmbeddingList search.",
                "section": "index",
                "page": 2,
                "quality_score": 0.91,
                "has_code": True,
                "emb_list_vector": [0.16, 0.24, 0.35, 0.45],
                "emb": [0.16, 0.24, 0.35, 0.45],
            },
        ],
    },
    {
        "doc_id": 2,
        "title": "Filtered StructArray search",
        "category": "filter",
        "title_vector": [0.20, 0.18, 0.22, 0.40],
        "chunks": [
            {
                "text": "Use element_filter to match scalar conditions within the same Struct element.",
                "section": "filter",
                "page": 1,
                "quality_score": 0.93,
                "has_code": True,
                "emb_list_vector": [0.21, 0.18, 0.33, 0.44],
                "emb": [0.21, 0.18, 0.33, 0.44],
            },
            {
                "text": "MATCH_LEAST checks how many elements satisfy a predicate.",
                "section": "filter",
                "page": 2,
                "quality_score": 0.88,
                "has_code": False,
                "emb_list_vector": [0.24, 0.22, 0.31, 0.39],
                "emb": [0.24, 0.22, 0.31, 0.39],
            },
        ],
    },
    {
        "doc_id": 3,
        "title": "Element-level search with offsets",
        "category": "search",
        "title_vector": [0.33, 0.11, 0.29, 0.37],
        "chunks": [
            {
                "text": "Element-level search can return the offset of the matched Struct element.",
                "section": "search",
                "page": 1,
                "quality_score": 0.95,
                "has_code": False,
                "emb_list_vector": [0.32, 0.14, 0.28, 0.41],
                "emb": [0.32, 0.14, 0.28, 0.41],
            }
        ],
    },
]

result = client.insert(
    collection_name="tech_articles",
    data=data,
)

print(result)

null 허용 StructArray 필드에 삽입

chunks 필드가 nullable인 경우, 엔티티는 전체 chunks 필드를 null로 설정할 수 있습니다. Python에서는 ` None `를 사용하여 null 값을 나타냅니다.

client.insert(
    collection_name="tech_articles",
    data=[
        {
            "doc_id": 10,
            "title": "Article without chunks yet",
            "category": "draft",
            "title_vector": [0.05, 0.10, 0.15, 0.20],
            "chunks": None,
        }
    ],
)

Nullable StructArray 필드에 유효한 StructArray 값이 포함된 경우, 해당 값 내의 모든 하위 필드는 null이거나 유효한 값을 가져야 합니다. 일부 하위 필드는 null로, 다른 하위 필드는 유효한 값으로 설정된 엔티티를 삽입하면 오류가 발생합니다.

경고 Nullable StructArray 필드는 Milvus v3.0.x에서만 사용할 수 있습니다. 기존 컬렉션에 StructArray 필드를 동적으로 추가하는 경우, 추가된 필드는 nullable이어야 하며, 기존 엔티티는 새 필드의 모든 하위 필드에 대해 ` null `를 반환해야 합니다.

삽입된 데이터 유효성 검사

컬렉션을 쿼리하여 StructArray 필드 또는 선택한 하위 필드를 반환할 수 있습니다.

rows = client.query(
    collection_name="tech_articles",
    filter="doc_id in [1, 2, 3]",
    output_fields=[
        "doc_id",
        "title",
        "chunks[text]",
        "chunks[section]",
        "chunks[quality_score]",
    ],
)

for row in rows:
    print(row)

chunks[text] 와 같은 StructArray 필드 경로는 쿼리, 검색, 필터링 또는 인덱스 생성 시에만 사용하십시오. 삽입 페이로드는 여전히 chunks 아래의 중첩된 객체를 사용해야 합니다.

삽입 규칙

규칙설명
StructArray 필드에는 객체 배열을 사용하십시오.chunks 의 값은 목록이며, 목록의 각 항목은 Struct 요소입니다.
각 Struct 요소 내부에서 하위 필드 이름을 사용하십시오.{"text": "...", "emb": [...]} 는 {"chunks[text]": "..."} 가 아닌 chunks 안에 삽입하십시오.
Struct 스키마와 일치시켜야 합니다.각 Struct 요소는 Struct 스키마에 정의된 하위 필드를 사용해야 합니다.
벡터 차원을 일치시켜야 합니다.벡터 값은 해당 벡터 하위 필드에 대해 구성된 dim 와 일치해야 합니다.
max_capacity 을 준수해야 합니다.하나의 엔티티에 포함된 Struct 요소의 수는 StructArray 필드의 max_capacity 을 초과해서는 안 됩니다.
별도의 검색 모드에는 별도의 벡터 하위 필드를 사용하십시오.EmbeddingList 검색과 요소 수준 검색이 모두 필요한 경우, 두 벡터 하위 필드 모두에 벡터 값을 작성하십시오.
null 는 필드가 null 허용일 때만 사용하십시오.null이 허용되지 않는 StructArray 필드에는 유효한 StructArray 값이 필요합니다.

흔히 저지르는 실수

  • 삽입 페이로드에서 chunks[text] 와 같은 필드 경로를 사용하는 경우.

  • Struct 요소에서 필수 하위 필드를 생략하는 경우.

  • 잘못된 차원의 벡터를 삽입하는 경우.

  • max_capacity 에서 허용하는 것보다 더 많은 Struct 요소를 삽입하는 경우.

  • 동일한 StructArray 값 내의 다른 하위 필드는 유효한데, 하나의 하위 필드만 null 로 설정하는 경우.

  • 벡터를 emb_list_vector 에만 기록한 후, chunks[emb] 에서 요소 수준 검색을 실행하려고 시도하는 경우.

  • 벡터를 emb 에만 기록한 후, chunks[emb_list_vector] 에서 EmbeddingList 검색을 실행하려는 경우.

다음 단계

  1. chunks[emb_list_vector], chunks[emb] 및 스칼라 하위 필드에 대한 인덱스를 생성하려면 StructArray 필드 인덱싱을 참조하십시오.

  2. StructArray 벡터 하위 필드를 검색하려면 ‘StructArray를 사용한 기본 벡터 검색’을 참조하십시오.

  3. null 허용 동작 및 버전별 제한 사항을 확인하려면 ‘StructArray 제한 사항’을 참조하십시오.

번역DeepL

목차 목록

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

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

시작하기
피드백

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