Memasukkan Data ke dalam Bidang StructArray

Masukkan data ke dalam bidang StructArray ketika setiap entitas berisi daftar terurut dari elemen-elemen terstruktur. Dalam payload penyisipan, bidang StructArray direpresentasikan sebagai array objek. Setiap objek mewakili satu elemen Struct dan menggunakan nama subbidang Struct yang didefinisikan dalam skema koleksi.

Halaman ini menggunakan koleksi ` tech_articles ` dari "Membuat Bidang StructArray". Setiap entitas adalah artikel teknis, dan bidang ` chunks ` menyimpan potongan artikel sebagai elemen Struct.

Sebelum memulai

Pastikan skema koleksi sudah berisi bidang StructArray " chunks ".

Bidang	Jenis	Nilai sisipan
doc_id	INT64	ID artikel.
title	VARCHAR	Judul artikel.
category	VARCHAR	Kategori artikel.
title_vector	FLOAT_VECTOR	Embedding tingkat artikel.
chunks	ARRAY	Daftar objek chunk.

Setiap objek dalam ` chunks ` harus mengikuti skema Struct.

Subbidang	Tipe	Nilai sisipan
text	VARCHAR	Teks chunk.
section	VARCHAR	Nama bagian, seperti index, search, atau filter.
page	INT64	Nomor halaman atau posisi logis.
quality_score	FLOAT	Skor tingkat chunk.
has_code	BOOL	Apakah potongan tersebut berisi kode.
emb_list_vector	FLOAT_VECTOR	Vektor yang ditulis untuk pencarian EmbeddingList.
emb	FLOAT_VECTOR	Vektor yang ditulis untuk pencarian tingkat elemen.

Pahami bentuk payload penyisipan

Nilai ` chunks ` adalah array elemen `Struct`. Setiap elemen adalah objek yang kuncinya berupa nama subbidang.

{
  "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 dan ` emb ` adalah subbidang vektor terpisah karena keduanya mendukung mode pencarian yang berbeda. Pencarian `EmbeddingList` memperlakukan semua vektor dalam bidang `StructArray` sebagai satu daftar embedding dan mengembalikan hasil tingkat entitas dengan metrik ` MAX_SIM* `. Pencarian tingkat elemen mencari setiap elemen `Struct` secara independen dan dapat mengembalikan offset elemen yang cocok. Contoh ini menyimpan nilai vektor yang sama di kedua bidang demi kesederhanaan. Dalam aplikasi produksi, Anda dapat menyimpan embedding yang sama di kedua subbidang jika kedua mode pencarian menggunakan chunk embedding yang sama, atau menyimpan embedding yang berbeda jika kedua mode pencarian menggunakan representasi yang berbeda.

Menyisipkan baris

Gunakan ` client.insert() ` untuk menyisipkan baris yang berisi nilai `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)

Menyisipkan ke bidang StructArray yang dapat bernilai null

Jika bidang ` chunks ` bersifat nullable, sebuah entitas dapat menetapkan seluruh bidang ` chunks ` ke `null`. Dalam Python, gunakan ` None ` untuk mewakili nilai `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,
        }
    ],
)

Ketika bidang StructArray yang dapat bernilai null berisi nilai StructArray yang valid, semua subbidang dalam nilai tersebut harus bernilai null atau memiliki nilai yang valid. Menyisipkan entitas dengan beberapa subbidang yang ditetapkan ke null dan yang lainnya ditetapkan ke nilai yang valid akan mengakibatkan kesalahan.

Memvalidasi data yang dimasukkan

Anda dapat melakukan kueri terhadap koleksi dan mengembalikan bidang StructArray atau subbidang yang dipilih.

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)

Gunakan jalur bidang StructArray, seperti chunks[text], hanya saat Anda melakukan kueri, pencarian, penyaringan, atau pembuatan indeks. Payload yang disisipkan tetap harus menggunakan objek bersarang di bawah chunks.

Aturan penyisipan

Aturan	Penjelasan
Gunakan array objek untuk bidang StructArray.	Nilai chunks adalah daftar, dan setiap item dalam daftar tersebut merupakan elemen Struct.
Gunakan nama subbidang di dalam setiap elemen Struct.	Masukkan ` {"text": "...", "emb": [...]} ` di dalam ` chunks`, bukan ` {"chunks[text]": "..."}`.
Sesuaikan dengan skema Struct.	Setiap elemen Struct harus menggunakan subfield yang didefinisikan dalam skema Struct.
Sesuaikan dimensi vektor.	Nilai vektor harus sesuai dengan dim yang dikonfigurasi untuk subbidang vektornya.
Patuhi batasan ukuran ( max_capacity).	Jumlah elemen Struct dalam satu entitas tidak boleh melebihi batas maksimum ( max_capacity ) dari bidang StructArray.
Gunakan subbidang vektor terpisah untuk mode pencarian yang berbeda.	Jika pencarian EmbeddingList dan pencarian tingkat elemen diperlukan, tulis nilai vektor ke kedua subbidang vektor tersebut.
Gunakan null hanya jika bidang tersebut dapat bernilai null.	Bidang StructArray yang tidak boleh bernilai null memerlukan nilai StructArray yang valid.

Kesalahan umum

• Menggunakan jalur bidang seperti chunks[text] dalam muatan penyisipan.

• Mengabaikan subbidang yang wajib dari elemen Struct.

• Menyisipkan vektor dengan dimensi yang salah.

• Menyisipkan elemen Struct lebih banyak daripada yang diizinkan oleh max_capacity.

• Hanya menetapkan satu subfield ke null sementara subfield lain dalam nilai StructArray yang sama masih valid.

• Menulis vektor hanya ke ` emb_list_vector ` dan kemudian mencoba menjalankan pencarian tingkat elemen pada ` chunks[emb]`.

• Menulis vektor hanya ke ` emb ` dan kemudian mencoba menjalankan pencarian EmbeddingList pada ` chunks[emb_list_vector]`.

Langkah selanjutnya

1. Untuk membuat indeks untuk chunks[emb_list_vector], chunks[emb], dan subbidang skalar, baca Indeks Bidang StructArray.

2. Untuk melakukan pencarian pada subbidang vektor StructArray, baca " Basic Vector Search with StructArray".

3. Untuk meninjau perilaku nullable dan batasan khusus versi, baca " StructArray Limits".