Membuat Bidang StructArray

Buat bidang StructArray jika suatu entitas perlu berisi daftar terurut dari elemen-elemen terstruktur. Bidang StructArray adalah bidang Array yang tipe elemennya adalah Struct. Setiap elemen Struct mengikuti skema yang sama dan dapat berisi subbidang skalar, subbidang vektor, atau keduanya.

Halaman ini menunjukkan cara mendefinisikan skema Struct, menambahkannya sebagai bidang StructArray, memilih subbidang untuk pencarian dan penyaringan di kemudian hari, serta memahami aturan skema yang berlaku sebelum Anda menyisipkan atau mengindeks data.

Sebelum Anda mulai

Halaman ini menggunakan koleksi bernama tech_articles. Setiap entitas mewakili satu artikel teknis, dan bidang chunks menyimpan data tingkat chunk sebagai elemen Struct.

Bidang	Tipe	Tujuan
doc_id	INT64	Kunci utama untuk artikel.
title	VARCHAR	Judul artikel.
category	VARCHAR	Kategori tingkat artikel.
title_vector	FLOAT_VECTOR	Bidang vektor tingkat artikel, yang akan digunakan nanti dalam contoh pencarian hibrida.
chunks	ARRAY	Bidang StructArray yang menyimpan teks tingkat chunk, metadata, dan embedding.

Bidang StructArray " chunks " berisi subbidang berikut.

Subbidang	Jenis	Tujuan
text	VARCHAR	Teks chunk.
section	VARCHAR	Nama bagian, seperti index, search, atau filter.
page	INT64	Nomor halaman atau posisi logis dari potongan tersebut.
quality_score	FLOAT	Skor tingkat potongan yang digunakan dalam penyaringan skalar dan contoh rentang.
has_code	BOOL	Apakah potongan tersebut berisi kode.
emb_list_vector	FLOAT_VECTOR	Subbidang vektor untuk pencarian EmbeddingList dengan metrik MAX_SIM*.
emb	FLOAT_VECTOR	Subbidang vektor untuk pencarian tingkat elemen dengan metrik vektor biasa.

Tipe data subbidang yang didukung

Bidang StructArray menyimpan satu nilai array untuk setiap subbidang Struct. Saat Anda mendefinisikan skema Struct, pilih tipe subbidang dari keluarga skalar dan vektor yang didukung.

Tipe fisik subbidang Struct	Dukungan	Catatan
Array	Didukung	Tentukan subbidang sebagai ` DataType.BOOL`.
Array	Didukung	Tentukan subbidang sebagai DataType.INT8, DataType.INT16, DataType.INT32, atau DataType.INT64.
Array	Didukung	Tentukan subbidang sebagai DataType.FLOAT atau DataType.DOUBLE.
Array	Didukung	Tentukan subbidang sebagai DataType.VARCHAR dan tetapkan max_length.
ArrayOfVector	Didukung	Tentukan subbidang sebagai DataType.FLOAT_VECTOR dan tetapkan dim.
ArrayOfVector	Didukung	Tentukan subbidang sebagai DataType.FLOAT16_VECTOR dan atur dim.
ArrayOfVector	Didukung	Tentukan subbidang sebagai DataType.BFLOAT16_VECTOR dan atur dim.
ArrayOfVector	Didukung	Tentukan subbidang sebagai DataType.INT8_VECTOR dan atur dim.
ArrayOfVector	Didukung	Tentukan subbidang sebagai DataType.BINARY_VECTOR dan atur dim.
ArrayOfVector	Tidak didukung	Subbidang vektor sparse tidak didukung dalam bidang StructArray.
Array	Tidak didukung	Gunakan " VARCHAR", bukan " String".
Array	Tidak didukung	Subbidang JSON tidak didukung dalam bidang StructArray.
Array	Tidak didukung	Subbidang geometri dan fungsi GIS tidak didukung dalam bidang StructArray.
Array	Tidak didukung	Subbidang teks tidak didukung dalam bidang StructArray.
Array	Tidak didukung	Subbidang timestamptz dan ekspresi berbasis waktu tidak didukung dalam bidang StructArray.
Array, ArrayOfVector, Struct, atau ArrayOfStruct	Tidak didukung	Bidang StructArray tidak boleh berisi array bersarang, array vektor bersarang, bidang Struct bersarang, atau bidang Array-of-Struct bersarang.

Untuk dukungan versi tertentu, perilaku nullable, dan batasan lainnya, lihat Batasan StructArray.

Buat koleksi dengan bidang StructArray

Untuk membuat bidang StructArray, pertama-tama tentukan skema Struct yang digunakan oleh setiap elemen. Kemudian tambahkan bidang Array dan tetapkan tipe elemennya ke Struct.

1. Buat skema koleksi.

2. Tambahkan bidang tingkat koleksi, seperti kunci utama dan bidang tingkat artikel.

3. Buat skema Struct untuk elemen yang disimpan di dalam bidang StructArray.

4. Tambahkan subbidang skalar dan vektor ke skema Struct.

5. Tambahkan bidang Array dengan nilai ` element_type=DataType.STRUCT`.

6. Tetapkan ` struct_schema ` ke skema Struct.

7. Tetapkan ` max_capacity ` untuk membatasi jumlah elemen Struct yang dapat disimpan oleh setiap entitas di dalam bidang tersebut.

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,
)

Memahami jalur bidang StructArray

Setelah Anda membuat bidang StructArray, rujuk subbidangnya dengan sintaks jalur ` structArray[subfield] `. Gunakan sintaks ini saat Anda membuat indeks, mencari subbidang vektor, mengeluarkan subbidang, atau membuat filter skalar.

Jalur	Arti	Penggunaan umum
chunks[text]	Subbidang ` text ` di dalam setiap elemen Struct.	Bidang keluaran atau penyaringan skalar.
chunks[section]	Label bagian untuk setiap chunk.	Penyaringan skalar.
chunks[quality_score]	Skor kualitas tingkat chunk.	Penyaringan skalar atau indeks skalar.
chunks[emb_list_vector]	Subbidang vektor yang digunakan sebagai daftar embedding.	Pencarian EmbeddingList dengan MAX_SIM*.
chunks[emb]	Subbidang vektor yang digunakan oleh setiap elemen Struct secara independen.	Pencarian vektor pada tingkat elemen.

Jadikan bidang StructArray dapat bernilai null

Milvus v3.0.x mendukung bidang StructArray yang dapat bernilai null. Bidang StructArray yang dapat bernilai null memungkinkan suatu entitas menyimpan nilai ` null ` untuk seluruh bidang StructArray tersebut.

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

Menambahkan bidang StructArray ke koleksi yang sudah ada

Milvus v3.0.x mendukung penambahan bidang StructArray ke koleksi yang sudah ada. Bidang StructArray yang ditambahkan harus dapat bernilai null, karena entitas yang sudah ada dalam koleksi tersebut belum memiliki nilai untuk bidang baru tersebut.

Untuk menambahkan bidang StructArray ke koleksi yang sudah ada, tentukan skema Struct terlebih dahulu. Kemudian panggil ` add_collection_struct_field() ` dan atur ` 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,
)

Setelah bidang StructArray ditambahkan, entitas yang sudah ada akan mengembalikan ` null ` untuk bidang baru tersebut di seluruh subbidangnya.

Setelah bidang StructArray dibuat, Anda tidak dapat menambahkan subbidang baru ke bidang StructArray yang sudah ada tersebut. Jika Anda memerlukan atribut elemen tambahan di kemudian hari, panggil ` drop_collection_field() ` untuk menghapus bidang StructArray tersebut, lalu tambahkan bidang StructArray baru dengan skema Struct yang telah diperbarui.

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,
)

Aturan skema

Aturan	Penjelasan
Struct digunakan sebagai tipe elemen Array.	Buat bidang StructArray sebagai bidang Array dengan element_type=STRUCT. Jangan buat Struct sebagai bidang koleksi tingkat atas.
Semua elemen berbagi satu skema.	Setiap elemen Struct dalam bidang StructArray yang sama mengikuti skema Struct yang telah ditentukan untuk bidang tersebut.
max_capacity diperlukan.	Ini membatasi jumlah elemen Struct yang dapat disimpan oleh setiap entitas dalam bidang StructArray.
Hanya tipe subbidang yang didukung yang diperbolehkan.	Gunakan tipe subbidang skalar dan vektor yang didukung oleh StructArray. Jangan mendefinisikan subbidang JSON, Geometry, Text, Timestamptz, SparseFloatVector, atau subbidang Struct / Array bersarang.
Subbidang vektor memerlukan indeks sebelum pencarian.	Buat indeks pada jalur seperti chunks[emb_list_vector] atau chunks[emb] sebelum menjalankan pencarian vektor.
Satu subfield vektor memiliki satu indeks.	Jika Anda memerlukan pencarian EmbeddingList dan pencarian tingkat elemen, buat dua subbidang vektor terpisah.
Subbidang StructArray yang sudah ada bersifat tetap.	Setelah membuat bidang StructArray, jangan berharap dapat menambahkan subbidang lain ke bidang StructArray yang sama.
Fungsi tidak didukung di dalam Struct.	Jangan mendefinisikan fungsi untuk bidang atau subbidang di dalam bidang StructArray.
Subbidang skalar harus sesuai dengan kebutuhan filter.	Tambahkan bidang seperti section, quality_score, atau has_code hanya jika Anda perlu memfilter, mengelompokkan, atau menampilkannya nanti.

Kesalahan umum

• Membuat ` DataType.STRUCT ` sebagai bidang koleksi tingkat atas alih-alih menggunakannya sebagai tipe elemen dari bidang Array.

• Lupa menetapkan ` max_capacity ` pada bidang `StructArray`.

• Mendefinisikan tipe subbidang yang tidak didukung, seperti JSON, Geometry, Text, Timestamptz, SparseFloatVector, Array bersarang, Struct bersarang, atau Array-of-Struct.

• Menggunakan ` String ` sebagai tipe subbidang. Gunakan ` VARCHAR ` dan atur ` max_length`.

• Menggunakan satu subbidang vektor untuk pencarian EmbeddingList dan pencarian tingkat elemen.

• Hanya menambahkan subbidang vektor dan mengabaikan subbidang skalar yang diperlukan untuk penyaringan, seperti section, quality_score, atau has_code.

• Memperlakukan subbidang vektor sebagai masukan predikat skalar $[...]. Gunakan subbidang vektor untuk pencarian vektor, dan subbidang skalar untuk predikat skalar.

• Mengasumsikan subbidang baru dapat ditambahkan ke bidang StructArray yang sudah ada setelah bidang tersebut dibuat.

• Menggunakan chunks.emb atau chunks.emb_list_vector alih-alih sintaks jalur yang diwajibkan chunks[emb] atau chunks[emb_list_vector].

• Menganggap perilaku StructArray yang dapat bernilai null tersedia di setiap versi target.

Langkah selanjutnya

1. Untuk menyisipkan data bersarang ke dalam bidang StructArray, baca Menyisipkan Data ke dalam Bidang StructArray.

2. Untuk membuat indeks vektor dan skalar, baca " Index StructArray Fields".

3. Untuk mencari subbidang vektor StructArray, baca " Pencarian Vektor Dasar dengan StructArray".

4. Untuk meninjau tipe data yang didukung, perilaku nullable, dan batasan khusus versi, baca " Batasan StructArray".