Pencocokan Pola

Dalam aplikasi pencarian berbasis agen, pencarian vektor dan pencocokan pola bergaya grep sering kali saling melengkapi. Pencarian vektor mengambil entitas yang relevan secara semantik, sedangkan pencocokan pola mempersempit hasil tersebut berdasarkan struktur string yang tepat, seperti kode kesalahan, awalan log, domain email, jalur URL, atau pengenal.

Di Milvus, Anda dapat mengekspresikan batasan pola ini dalam filter skalar menggunakan LIKE untuk pencocokan wildcard sederhana, serta =~ atau !~ untuk ekspresi reguler RE2. Anda dapat menggabungkan filter-filter ini dengan query, search, atau pencarian hibrida.

Ekspresi pencocokan pola ditulis dalam parameter filter. Misalnya, kueri berikut mencocokkan pesan log yang mengandung kode kesalahan seperti E1001:

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

res = client.query(
    collection_name="log_events",
    filter='message =~ "E[0-9]{4}"',
    output_fields=["message", "severity"],
)

Contoh-contoh pada halaman ini berfokus pada ekspresi yang ditetapkan ke ` filter`. Anda dapat menggunakan sintaks ekspresi filter yang sama dalam operasi Milvus yang menerima filter skalar, seperti ` query`, ` search`, dan pencarian hibrida.

Jenis bidang yang didukung

Pencocokan pola tersedia untuk nilai string.

Target	LIKE	Regex =~ / !~	Catatan
VARCHAR bidang	Ya	Ya	Target umum untuk pencocokan pola pada bidang string.
JSON jalur dengan tipe konversi VARCHAR	Ya	Ya	Nilai jalur JSON harus berupa string agar pencocokan berhasil. Jika Anda membuat indeks pada jalur JSON untuk percepatan, atur ` json_cast_type="varchar"`.
ARRAY<VARCHAR> elemen	Ya	Ya	Cocokkan elemen tertentu berdasarkan indeks, seperti tags[0]. Pencocokan pola tidak memindai semua elemen; pencocokan hanya berlaku untuk elemen pada indeks yang ditentukan.
Numerik, Boolean, vektor, TEXT, atau target non-VARCHAR lainnya	Tidak	Tidak	Pencocokan pola hanya tersedia untuk nilai VARCHAR, jalur JSON yang diubah menjadi string, atau elemen ARRAY<VARCHAR> yang diindeks.

Pilih LIKE atau regex

Pilih operator paling sederhana yang dapat mengekspresikan pola yang Anda butuhkan.

Jika Anda memerlukan pencocokan string yang tepat, kami menyarankan Anda menggunakan ` == ` alih-alih pencocokan pola. Gunakan ` LIKE ` atau regex hanya jika filter perlu mencocokkan suatu pola.

Persyaratan	Operator yang direkomendasikan	Contoh	Deskripsi
Kesamaan string yang tepat	==	status == "active"	Kesesuaian persis dari string active.
Kecocokan awalan sederhana	LIKE	name LIKE "Prod%"	Mencocokkan string yang dimulai dengan Prod.
Kesesuaian sufiks sederhana	LIKE	filename LIKE "%.json"	Mencocokkan string yang diakhiri dengan .json.
Kecocokan sederhana "mengandung"	LIKE	description LIKE "%vector database%"	Mencocokkan nilai yang mengandung vector database di mana saja dalam string.
Mencocokkan kode terstruktur atau pola panjang tetap	=~	code =~ "E[0-9]{4}"	Mencocokkan string yang secara peka huruf besar/kecil mengandung E diikuti oleh empat digit, seperti E1001.
Pencocokan pola tanpa membedakan huruf besar-kecil	=~ dengan (?i)	message =~ "(?i)error"	Mencocokkan error, ERROR, atau varian huruf besar-kecil lainnya.
Kecualikan nilai yang cocok dengan pola regex	!~	message !~ "^DEBUG"	Mengecualikan string yang dimulai dengan DEBUG.

Gunakan LIKE untuk pencocokan wildcard sederhana. Gunakan regex jika pola memerlukan kelas karakter, pengulangan, alternatif seperti error|failed, jangkar, atau pencocokan tanpa membedakan huruf besar-kecil.

Gunakan LIKE

Operator LIKE digunakan untuk pencocokan karakter pengganti sederhana pada nilai string. Operator ini hanya mendukung karakter pengganti berikut:

Karakter pengganti	Deskripsi
%	Mencocokkan nol atau lebih karakter.
_	Mencocokkan tepat satu karakter.

Pola LIKE yang umum

Gunakan posisi % dan _ untuk mengontrol di mana teks tetap muncul dalam string yang cocok.

Persyaratan	Pola	Contoh filter
Dimulai dengan awalan	Prod%	filter = 'name LIKE "Prod%"'
Berakhir dengan sufiks	%.json	filter = 'filename LIKE "%.json"'
Mengandung substring	%vector%	filter = 'description LIKE "%vector%"'
Mencocokkan satu karakter pada posisi tetap	AB_%	filter = 'code LIKE "AB_%"'

Perilaku pencocokan LIKE

Gunakan ` LIKE ` untuk pencocokan awalan, akhiran, mengandung, dan satu karakter pada posisi tetap. ` LIKE ` tidak mendukung kelas karakter seperti ` [0-9]`, alternatif seperti ` error|failed`, jumlah pengulangan seperti ` {4}`, jangkar seperti ` ^ ` atau ` $`, atau bendera tidak peka huruf besar-kecil seperti ` (?i)`. Gunakan regex untuk pola-pola tersebut.

Gunakan ` == ` untuk kesamaan string penuh yang tepat. Gunakan ` LIKE ` hanya jika filter memerlukan pencocokan karakter pengganti.

Mengescap karakter pengganti dalam pola LIKE

Dalam pola ` LIKE `, ` % ` mencocokkan nol atau lebih karakter, sedangkan ` _ ` mencocokkan tepat satu karakter. Untuk mencocokkan ` %`, ` _`, atau ` \ ` secara harfiah, lakukan escaping pada karakter tersebut dengan tanda backslash (\):

• name LIKE r"\%" cocok dengan nilai literal %.
• name LIKE r"\_%" cocok dengan nilai yang dimulai dengan karakter literal _.
• name LIKE r"\\%" cocok dengan nilai yang dimulai dengan tanda garis miring terbalik literal.

Literal string mentah, ditulis sebagai r"..." atau r'...', mempertahankan tanda garis miring terbalik apa adanya dalam ekspresi filter Milvus. Penggunaan literal string mentah direkomendasikan untuk LIKE dan pola regex yang mengandung tanda garis miring terbalik. Tanpa literal string mentah, literal string biasa tetap memproses urutan pelarian sebelum pola dievaluasi, sehingga mungkin diperlukan lebih banyak tanda garis miring terbalik.

Gunakan regexCompatible with Milvus 3.0.x

Gunakan filter regex jika pola memerlukan fitur ekspresi reguler seperti kelas karakter, pengulangan, alternatif, jangkar, atau pencocokan yang tidak peka huruf besar/kecil. Milvus menerapkan ekspresi reguler RE2 ke nilai string.

Sisi kanan dari =~ atau !~ harus berupa literal string.

Operator	Arti	Contoh
=~	Mencocokkan nilai yang memenuhi pola regex.	filter = 'message =~ "E[0-9]{4}"'
!~	Mengecualikan nilai-nilai yang memenuhi pola regex.	filter = 'message !~ "^DEBUG"'

Gunakan literal string mentah

Literal string mentah direkomendasikan untuk pola regex yang mengandung tanda garis miring terbalik. Dalam string mentah, yang ditulis sebagai r"..." atau r'...', tanda garis miring terbalik diteruskan ke mesin regex apa adanya. Hal ini menghindari proses pelarian (escaping) tambahan yang diperlukan oleh literal string biasa.

Contoh:

filter = 'message =~ r"\d{4}-\d{2}-\d{2}"'

Ini mencocokkan string yang berisi nilai mirip tanggal seperti 2026-07-01.

Tanpa string mentah, literal string biasa memproses urutan pelarian sebelum pola regex dievaluasi, sehingga pola seperti \d, \s, atau karakter literal yang dilindungi mungkin memerlukan tanda garis miring terbalik tambahan.

Pola regex umum

Contoh berikut menggunakan sintaks RE2 umum dalam ekspresi filter Milvus. Untuk sintaks regex lengkap, lihat referensi sintaks RE2.

Persyaratan	Pola	Contoh filter
Mengandung teks literal	error	filter = 'message =~ "error"'
Dimulai dengan awalan	^ERR	filter = 'code =~ "^ERR"'
Berakhir dengan sufiks	\.json$	filter = 'filename =~ "\\.json$"'
Cocok dengan urutan angka	[0-9]+	filter = 'message =~ "[0-9]+"'
Cocok dengan jumlah digit tetap	[0-9]{4}	filter = 'code =~ "[0-9]{4}"'
Cocok dengan domain email	@example\.com$	filter = 'email =~ "@example\\.com$"'
Mencocokkan tanpa membedakan huruf besar-kecil	(?i)error	filter = 'message =~ "(?i)error"'
Mencocokkan string lengkap	^prod-[0-9]+$	filter = 'name =~ "^prod-[0-9]+$"'

Untuk mencocokkan salah satu dari beberapa kata, gunakan alternatif dengan |:

filter = 'message =~ "error|failed|timeout"'

Saat mencocokkan karakter meta regex secara harfiah, lakukan escape pada pola regex tersebut. Misalnya, untuk mencocokkan titik harfiah (\. dalam regex), tulis \\. dalam string filter Python:

filter = 'email =~ "@gmail\\.com$"'

Catatan: Filter regex Milvus mengikuti sintaks RE2. Jika pola regex menggunakan sintaks yang tidak didukung oleh RE2 atau tidak valid, Milvus akan menolak ekspresi filter tersebut. Untuk detail mengenai karakter meta regex, bendera, dan perilaku pencocokan, lihat referensi sintaks RE2.

Perilaku pencocokan

Pencocokan substring

Pencocokan regex Milvus menggunakan semantik substring. Pola tidak perlu cocok dengan seluruh nilai bidang. Misalnya, filter berikut cocok dengan E1001 dan failed with E1001 after retry:

filter = 'message =~ "E[0-9]{4}"'

Untuk mencocokkan seluruh nilai bidang, gunakan jangkar ^ dan $:

# Match only values that are exactly E followed by four digits
filter = 'code =~ "^E[0-9]{4}$"'

Kolom VARCHAR yang dapat bernilai null

Filter regex tidak cocok dengan nilai null. Hal ini berlaku baik untuk =~ maupun !~. Jika Anda ingin mengecualikan pola regex tetapi tetap mempertahankan nilai null, tambahkan secara eksplisit OR field IS NULL:

filter = 'message !~ "^DEBUG" OR message IS NULL'

Jalur JSON

Untuk jalur JSON, filter regex berperilaku berbeda ketika jalurnya hilang, bernilai null, atau menghasilkan nilai non-string:

Filter	Menyertakan nilai yang hilang/null/bukan string?	Catatan
json_field["path"] =~ "pattern"	Tidak	Hanya cocok dengan nilai string yang memenuhi pola regex.
json_field["path"] !~ "pattern"	Ya	Mengembalikan entitas yang jalurnya hilang, null, bukan string, atau berupa string yang tidak sesuai dengan pola regex.

Mempercepat pencocokan pola dengan indeks

Milvus mendukung beberapa jenis indeks pada bidang string yang dapat digunakan bersama dengan filter " LIKE " dan filter regex pada bidang " VARCHAR " atau jalur string JSON, seperti NGRAM, STL_SORT, INVERTED, dan BITMAP. Pencocokan pola dapat berfungsi tanpa indeks, tetapi indeks dapat meningkatkan kinerja pada dataset besar.

Efektivitas indeks bergantung pada ekspresi pola, apakah Milvus dapat mengekstrak substring literal tetap, serta kardinalitas dan distribusi bidang target. Pola bergaya awalan seperti name LIKE "Prod%" mungkin lebih diuntungkan dengan strategi indeks yang berbeda dibandingkan pola infiks atau sufiks seperti description LIKE "%vector%" atau filename LIKE "%.json".

Gunakan tabel berikut sebagai titik awal, lalu lakukan pengujian kinerja dengan beban kerja Anda sendiri:

Pola atau karakteristik data	Indeks yang perlu dipertimbangkan	Catatan
Mengandung substring literal tetap, seperti message =~ "error.*timeout" atau message LIKE "%database%"	NGRAM	Berguna jika Milvus dapat mengekstrak substring literal yang bermakna dari pola tersebut. Untuk detailnya, lihat NGRAM.
Filter string awalan, tepat, atau mirip kesetaraan, terutama pada bidang dengan kardinalitas rendah hingga sedang	STL_SORT, INVERTED, atau BITMAP	Mungkin lebih efektif jika bidang memiliki nilai yang berulang atau jika filter mendekati pencocokan eksak. Untuk detailnya, lihat STL_SORT, INVERTED, dan BITMAP.
Pola regex tanpa literal tetap, atau pola yang didominasi oleh kelas karakter, token pendek, atau karakter pengganti	Lakukan pengujian kinerja sebelum mengandalkan akselerasi indeks	Pola-pola ini mungkin memberikan selektivitas indeks yang terbatas dan dapat beralih ke pemindaian yang lebih luas.