Sintaks kueri Lucene di Azure AI Search

Saat membuat kueri di Azure AI Search, Anda dapat memilih sintaks Pengurai Kueri Lucene lengkap untuk formulir kueri khusus: kartubebas, pencarian fuzzy, pencarian kedekatan, ekspresi reguler . Sebagian besar sintaks Lucene Query Parser diimplementasikan secara utuh dalam Azure AI Search, kecuali untuk *pencarian rentang, yang dibangun melalui $filter ekspresi.

Untuk menggunakan sintaks Lucene penuh, atur queryType ke full dan teruskan ekspresi kueri yang berpola untuk kartubebas, pencarian fuzzy, atau salah satu formulir kueri lainnya yang didukung oleh sintaks penuh. Di REST, ekspresi kueri disediakan dalam search parameter permintaan Search Documents (REST API).

Contoh (sintaksis penuh)

Contoh berikut adalah permintaan pencarian yang dibuat menggunakan sintaksis penuh. Contoh khusus ini menunjukkan pencarian di lapangan dan peningkatan istilah. Ini mencari hotel di mana bidang kategori berisi istilah budget. Dokumen apa pun yang berisi frasa "recently renovated" diberi peringkat lebih tinggi sebagai hasil dari nilai peningkatan istilah (3).

POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

Meskipun tidak spesifik untuk jenis kueri apa pun, parameter searchMode relevan dalam contoh ini. Setiap kali operator berada di kueri, Anda umumnya harus mengatur searchMode=all untuk memastikan bahwa semua kriteria cocok.

Untuk contoh selengkapnya, lihat Contoh sintaks kueri Lucene. Untuk detail tentang permintaan dan parameter kueri, termasuk searchMode, lihat Search Documents (REST API).

Dasar-dasar sintaksis

Sintaksis dasar berikut berlaku untuk semua kueri yang menggunakan sintaksis Lucene.

Evaluasi operator dalam konteks

Penempatan menentukan apakah simbol ditafsirkan sebagai operator atau hanya karakter lain dalam string.

Misalnya, dalam sintaks penuh Lucene, tilde (~) digunakan untuk pencarian fuzzy dan pencarian kedekatan. Ketika ditempatkan setelah frasa yang dikutip, ~ memanggil pencarian kedekatan. Ketika ditempatkan di akhir istilah, ~ memanggil pencarian fuzzy.

Dalam istilah, seperti business~analyst, karakter tidak dievaluasi sebagai operator. Dalam hal ini, dengan asumsi kueri adalah kueri istilah atau frasa, pencarian teks lengkap dengan analisis leksikal menghapus ~ dan merusak istilah business~analyst dalam dua: business ATAU analyst.

Contoh di atas adalah tilde (~), tetapi prinsip yang sama berlaku untuk setiap operator.

Pelepasan karakter khusus

Untuk menggunakan salah satu operator pencarian sebagai bagian dari teks pencarian, lepaskan karakter dengan awalan dengan satu garis miring (\). Misalnya, untuk pencarian kartubebas di https://, dengan :// merupakan bagian dari string kueri, Anda akan menentukan search=https\:\/\/*. Demikian pula, pola nomor telepon yang dilepaskan mungkin terlihat seperti ini \+1 \(800\) 642\-7676.

Karakter khusus yang perlu pelepasan meliputi:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Catatan

Meskipun pelepasan menjaga token bersama-sama, analisis leksikal selama pengindeksan dapat menghapusnya. Misalnya, penganalisis Lucene standar akan memecah kata-kata pada tanda hubung, spasi putih, dan karakter lainnya. Jika Anda memerlukan karakter khusus dalam string kueri, Anda mungkin memerlukan penganalisis yang mempertahankannya dalam indeks. Beberapa pilihan termasuk Penganalisis bahasa alami Microsoft, yang mempertahankan kata-kata yang dipenggal, atau penganalisis kustom untuk pola yang lebih kompleks. Untuk informasi selengkapnya, lihat Istilah parsial, pola, dan karakter khusus.

Mengodekan karakter tidak aman dan karakter khusus dalam URL

Pastikan semua karakter tidak aman dan karakter khusus dikodekan dalam URL. Misalnya, # adalah karakter yang tidak aman karena merupakan pengidentifikasi fragmen/jangkar dalam URL. Karakter harus dikodekan ke %23 jika digunakan dalam URL. & dan = merupakan contoh karakter yang dipesan saat memisahkan parameter dan menentukan nilai di Azure AI Search. Lihat RFC1738: Uniform Resource Locators (URL) untuk detail selengkapnya.

Karakter yang tidak aman adalah " ` < > # % { } | \ ^ ~ [ ]. Karakter khusus adalah ; / ? : @ = + &.

Operator Boolean

Anda dapat menyematkan operator Boolean dalam string kueri untuk meningkatkan presisi kecocokan. Sintaksis penuh mendukung operator teks selain operator karakter. Selalu tentukan operator boolean teks (AND, OR, NOT) di semua huruf besar.

Operator teks	karakter	Contoh	Penggunaan
AND	+	wifi AND luxury	Menentukan istilah yang harus dimuat oleh kecocokan. Dalam contoh, mesin kueri mencari dokumen yang berisi dan wifiluxury. Karakter plus (+) juga dapat digunakan langsung di depan istilah untuk membuatnya diperlukan. Misalnya, +wifi +luxury menetapkan bahwa kedua istilah harus muncul di suatu tempat di bidang dokumen tunggal.
ATAU	(tidak ada) 1	wifi OR luxury	Menemukan kecocokan saat salah satu istilah ditemukan. Dalam contoh, mesin kueri mengembalikan kecocokan pada dokumen yang berisi atau wifiluxury atau keduanya. Karena OR adalah operator konjungsi default, Anda juga bisa membiarkannya, sehingga wifi luxury setara dengan wifi OR luxury.
TIDAK	!, -	wifi –luxury	Mengembalikan kecocokan pada dokumen yang mengecualikan istilah. Misalnya, wifi –luxury mencari dokumen yang memiliki wifi istilah tetapi tidak luxury.

¹ Karakter | tidak didukung untuk operasi OR.

OPERATOR BUKAN Boolean

Penting

Operator NOT (NOT, !, atau -) berulah secara berbeda dalam sintaks penuh daripada yang dilakukannya dalam sintaks sederhana.

• Dalam sintaksis sederhana, kueri dengan negasi selalu memiliki kartubebas yang ditambahkan secara otomatis. Misalnya, kueri -luxury secara otomatis diperluas ke -luxury *.
• Dalam sintaks penuh, kueri dengan negasi tidak dapat dikombinasikan dengan kartubebas. Misalnya, kueri -luxury * tidak diizinkan.
• Dalam sintaks penuh, kueri dengan satu negasi tidak diizinkan. Misalnya, kueri -luxury tidak diizinkan.
• Dalam sintaks penuh, negasi akan berperilaku seolah-olah selalu DIAND ke kueri terlepas dari mode pencarian.
  • Misalnya, kueri wifi -luxury sintaks lengkap dalam sintaks penuh hanya mengambil dokumen yang berisi istilah wifi, lalu menerapkan negasi -luxury ke dokumen tersebut.
• Jika Anda ingin menggunakan negasi untuk mencari semua dokumen dalam indeks, sintaks sederhana dengan any mode pencarian disarankan.
• Jika Anda ingin menggunakan negasi untuk mencari subset dokumen dalam indeks, sintaks penuh, atau sintaks sederhana dengan semua mode pencarian disarankan.

Jenis Kueri	Mode Pencarian	Kueri Contoh	Perilaku
Sederhana	any	wifi -luxury	Mengembalikan semua dokumen dalam indeks. Dokumen dengan istilah "wifi" atau dokumen yang tidak memiliki istilah "mewah" diberi peringkat lebih tinggi daripada dokumen lainnya. Kueri diperluas ke wifi OR -luxury OR *.
Sederhana	all	wifi -luxury	Hanya mengembalikan dokumen dalam indeks yang berisi istilah "wifi" dan tidak berisi istilah "mewah". Kueri diperluas ke wifi AND -luxury AND *.
Penuh	any	wifi -luxury	Mengembalikan hanya dokumen dalam indeks yang berisi istilah "wifi", lalu dokumen yang berisi istilah "mewah" dihapus dari hasil.
Penuh	all	wifi -luxury	Mengembalikan hanya dokumen dalam indeks yang berisi istilah "wifi", lalu dokumen yang berisi istilah "mewah" dihapus dari hasil.

Pencarian ber bidang

Anda dapat menentukan operasi pencarian beralaskan dengan sintaksis fieldName:searchExpression, tempat ekspresi pencarian dapat menjadi satu kata atau frasa, atau ekspresi yang lebih kompleks dalam tanda kurung, secara opsional dengan operator Boolean. Beberapa contoh meliputi:

• genre:jazz NOT history

• artists:("Miles Davis" "John Coltrane")

Pastikan untuk meletakkan beberapa string dalam tanda kutip jika Anda ingin kedua string dievaluasi sebagai entitas tunggal, dalam hal ini mencari dua artis berbeda di bidang artists.

Bidang yang ditentukan fieldName:searchExpression harus dalam bidang searchable. Lihat Membuat Indeks untuk detail tentang bagaimana atribut indeks digunakan dalam definisi bidang.

Catatan

Saat menggunakan ekspresi pencarian ber bidang, Anda tidak perlu menggunaka parameter searchFields karena setiap ekspresi pencarian per bidang memiliki nama bidang yang ditentukan secara eksplisit. Namun, Anda masih bisa menggunakan parameter searchFields jika Anda ingin menjalankan kueri yang mencakup beberapa bagian ke bidang tertentu, dan sisanya bisa berlaku untuk beberapa bidang. Misalnya, kueri search=genre:jazz NOT history&searchFields=description hanya akan mencocokkan jazz dengan bidang genre, sementara kueri akan mencocokkan NOT history dengan bidang description. Nama bidang yang disediakan di fieldName:searchExpression selalu diutamakan daripada parameter searchFields, itulah sebabnya dalam contoh ini, kami tidak perlu menyertakan genre di parameter searchFields.

Pencarian fuzzy

Pencarian fuzzy menemukan kecocokan dalam hal yang memiliki konstruksi serupa, yang memperluas istilah hingga maksimum 50 istilah agar memenuhi 2 kriteria jarak atau kurang. Untuk informasi selengkapnya, lihat Pencarian fuzzy.

Untuk melakukan pencarian fuzzy, gunakan simbol tilde ~ di akhir satu kata dengan parameter opsional, angka antara 0 dan 2 (default), yang menentukan jarak edit. Misalnya, blue~ atau blue~1 akan mengembalikan blue, blues, dan glue.

Pencarian fuzzy hanya dapat diterapkan pada istilah, bukan frasa yang diapit kutipan, tetapi Anda dapat menambahkan tilde ke setiap istilah satu per satu dalam nama atau frasa multi-bagian. Misalnya, Unviersty~ of~ Wshington~ akan cocok pada University of Washington.

Pencarian kedekatan

Pencarian terdekat digunakan untuk menemukan istilah yang saling berdekatan dalam sebuah dokumen. Sisipkan simbol tilde ~ di akhir frasa diikuti dengan jumlah kata yang membuat batas kedekatan. Misalnya, "hotel airport"~5 menemukan istilah hotel dan airport dalam lima kata satu sama lain dalam dokumen.

Peningkatan istilah

Peningkatan istilah mengacu pada peringkat dokumen yang lebih tinggi jika berisi istilah yang didorong, relatif terhadap dokumen yang tidak berisi istilah. Dokumen ini berbeda dari penilaian profil dalam profil penilaian yang meningkatkan bidang tertentu, bukan istilah tertentu.

Contoh berikut membantu mengilustrasikan perbedaan. Misalnya ada profil penilaian yang meningkatkan kecocokan di bidang tertentu, contohnya genre dalam contoh musicstoreindex. Peningkatan istilah dapat digunakan untuk lebih meningkatkan istilah pencarian tertentu yang lebih tinggi daripada istilah lain. Misalnya, rock^2 electronic meningkatkan dokumen yang berisi istilah pencarian di bidang genre yang lebih tinggi dari bidang lain yang dapat dicari dalam indeks. Selanjutnya, dokumen yang berisi istilah pencarian rock diberi peringkat lebih tinggi daripada istilah pencarian elektronik lainnya sebagai hasil dari nilai peningkatan istilah (2).

Untuk meningkatkan istilah, gunakan tanda sisipan, ^simbol , dengan faktor peningkatan (angka) di akhir istilah yang Anda cari. Anda juga dapat meningkatkan frasa. Semakin tinggi faktor peningkatan, semakin relevan istilah tersebut relatif terhadap istilah pencarian lainnya. Secara default, faktor peningkatan adalah 1. Meskipun faktor dorongan harus positif, itu bisa kurang dari 1 (misalnya, 0,20).

Pencarian ekspresi reguler

Pencarian regex menemukan kecocokan berdasarkan pola yang valid di bawah Apache Lucene, seperti yang didokumentasikan di kelas RegExp. Di Azure AI Search, ekspresi reguler diapit di antara garis miring /ke depan .

Misalnya, untuk menemukan dokumen yang berisi motel atau hotel, tentukan /[mh]otel/. Pencarian regex dicocokkan dengan satu kata.

Beberapa alat dan bahasa memberlakukan persyaratan karakter escape ekstra di luar aturan escape yang diberlakukan oleh Azure AI Search. Untuk JSON, string yang menyertakan garis miring diloloskan dengan garis miring mundur: microsoft.com/azure/ menjadi tempat search=/.* <string-placeholder>.*/ menyiapkan ekspresi reguler, dan microsoft.com\/azure\/ merupakan string dengan garis miring maju yang lolossearch=/.*microsoft.com\/azure\/.*/.

Dua simbol umum dalam kueri regex adalah . dan *. Cocok . dengan satu karakter dan cocok * dengan karakter sebelumnya nol atau lebih kali. Misalnya, /be./ cocok dengan istilah bee dan bet sementara /be*/ akan cocok bedengan , bee, dan beee tetapi tidak bet. Bersama-sama, .* memungkinkan Anda untuk mencocokkan serangkaian karakter /be.*/ sehingga akan cocok dengan istilah apa pun yang dimulai dengan be seperti better.

Jika Anda mendapatkan kesalahan sintaks dalam ekspresi reguler, tinjau aturan escape untuk karakter khusus. Anda mungkin juga mencoba klien lain untuk mengonfirmasi apakah masalahnya khusus untuk alat.

Pencarian kartubebas

Anda dapat menggunakan sintaksis yang dikenali secara umum untuk beberapa (*) atau satu pencarian kartubebas karakter (?). Sintaksis Lucene lengkap mendukung awalan, infiks, dan pencocokan akhiran.

Perhatikan pengurai kueri Lucene mendukung penggunaan simbol ini dengan satu istilah, bukan frasa.

Jenis imbuhan	Deskripsi dan contoh
awalan	Fragmen istilah datang sebelum * atau ?. Misalnya, ekspresi kueri pengembalian search=alpha*alphanumeric atau alphabetical. Pencocokan awalan didukung dalam sintaksis sederhana dan penuh.
Akhiran	Fragmen istilah muncul setelah * atau ?, dengan garis miring ke depan untuk memisahkan konstruksi. Misalnya, search=/.*numeric/ mengembalikan alphanumeric.
sisipan	Fragmen istilah menutup * atau ?. Misalnya, search=non*al mengembalikan non-numerical dan nonsensical.

Anda dapat menggabungkan operator dalam satu ekspresi. Misalnya, 980?2* cocok pada 98072-1222 dan 98052-1234, di mana ? cocok pada satu karakter (wajib), dan * cocok pada karakter dengan panjang selangit yang mengikutinya.

Pencocokan akhiran memerlukan pembatas garis miring / ekspresi reguler. Umumnya, Anda tidak dapat menggunakan * simbol atau ? sebagai karakter pertama istilah, tanpa /. Penting juga untuk dicatat bahwa * perilakunya berbeda ketika digunakan di luar kueri regex. Di luar pemisah garis miring / ke depan regex, * adalah karakter kartubebas dan cocok dengan serangkaian karakter .* seperti dalam regex. Sebagai contoh, search=/non.*al/ menghasilkan tataan hasil yang sama dengan search=non*al.

Catatan

Sebagai aturan, pencocokan pola lambat sehingga Anda mungkin ingin menjelajahi metode alternatif, seperti pembuatan token edge n-gram yang membuat token untuk urutan karakter dalam istilah. Dengan pembuatan token n-gram, indeks akan lebih besar, tetapi kueri mungkin menjalankan lebih cepat, tergantung pada konstruksi pola dan panjang string yang Anda indeks. Untuk informasi selengkapnya, lihat Pencarian dan pola istilah parsial dengan karakter khusus.

Efek penganalisis pada kueri kartubebas

Selama penguraian kueri, kueri yang diformulasikan sebagai awalan, akhiran, kartubebas, atau regex diteruskan dengan normal ke pohon kueri, yang melewati analisis leksikal. Kecocokan hanya akan ditemukan jika indeks berisi string dalam format yang ditentukan kueri Anda. Dalam kebanyakan kasus, Anda memerlukan penganalisis selama pengindeksan yang mempertahankan integritas string sehingga pencocokan istilah dan pola parsial berhasil. Untuk informasi selengkapnya, lihat Pencarian istilah parsial di kueri Pencarian Azure AI.

Pertimbangkan situasi di mana Anda mungkin ingin kueri terminal* pencarian mengembalikan hasil yang berisi istilah seperti terminate, termination, dan terminates.

Jika Anda menggunakan penganalisis en.lucene (English Lucene), penganalisis tersebut akan menerapkan stemming agresif dari setiap istilah. Misalnya, terminate, termination, terminates semua akan ditokenisasi ke token termi dalam indeks Anda. Di sisi lain, istilah dalam kueri yang menggunakan kartubebas atau pencarian fuzzy tidak dianalisis sama sekali, sehingga tidak akan ada hasil yang cocok dengan terminat* kueri.

Di sisi lain, penganalisis Microsoft (dalam hal ini, penganalisis en.microsoft) sedikit lebih canggih dan menggunakan lemmatisasi sebagai ganti stemming. Artinya, semua token yang dihasilkan harus berupa kata-kata dalam bahasa Inggris yang valid. Misalnya, terminate, terminates, dan termination sebagian besar akan tetap utuh dalam indeks, dan akan menjadi pilihan yang lebih disukai untuk skenario yang sangat bergantung pada wildcard dan pencarian fuzzy.

Menilai kueri kartubebas dan regex

Azure AI Search menggunakan penilaian berbasis frekuensi (BM25) untuk kueri teks. Namun, untuk kueri kartubebas dan regex tempat cakupan istilah dapat berpotensi luas, faktor frekuensi diabaikan untuk mencegah peringkat bias terhadap pertandingan dari istilah yang lebih langka. Semua kecocokan diperlakukan sama untuk pencarian kartubebas dan regex.

Karakter khusus

Dalam beberapa keadaan, Anda mungkin ingin mencari karakter khusus, seperti emoji '❤' atau tanda '€'. Dalam kasus seperti itu, pastikan penganalisis yang Anda gunakan tidak memfilter karakter tersebut. Penganalisis standar melewati banyak karakter khusus, tidak termasuk dari indeks Anda.

Penganalisis yang membuat token karakter khusus mencakup penganalisis spasi putih, yang mempertimbangkan urutan karakter apa pun yang dipisahkan oleh spasi kosong sebagai token (sehingga ❤ string akan dianggap sebagai token). Juga, penganalisis bahasa seperti penganalisis Microsoft English ("en.microsoft"), akan mengambil untai (karakter) "€" sebagai token. Anda dapat menguji penganalisis untuk melihat token apa yang dihasilkannya untuk kueri tertentu.

Saat menggunakan karakter Unicode, pastikan simbol diloloskan dengan benar di url kueri (misalnya ❤ akan menggunakan urutan %E2%9D%A4+escape ). Beberapa klien REST melakukan terjemahan ini secara otomatis.

Prioritas (pengelompokan)

Anda dapat menggunakan tanda kurung untuk membuat subkueri, termasuk operator dalam pernyataan kurung. Misalnya, motel+(wifi|luxury) mencari dokumen yang berisi motel istilah dan atau wifiluxury (atau keduanya).

Pengelompokan bidang serupa tetapi cakupan pengelompokan ke satu bidang. Misalnya, hotelAmenities:(gym+(wifi|pool)) mencari bidang hotelAmenities untuk gym dan wifi, atau gym dan pool.

Batas ukuran kueri

Azure AI Search memberlakukan batasan pada ukuran dan komposisi kueri karena kueri yang tidak terbatas dapat mendestabilisasi layanan pencarian Anda. Ada batasan ukuran dan komposisi kueri (jumlah klausul). Batasan juga ada untuk panjang pencarian awalan dan kompleksitas pencarian regex dan pencarian kartubebas. Jika aplikasi Anda menghasilkan kueri pencarian secara terprogram, sebaiknya merancangnya sedemikian sehingga tidak menghasilkan kueri dengan ukuran yang tidak terbatas.

Untuk informasi selengkapnya tentang batas kueri, lihat Batas permintaan API.

Lihat juga

• Contoh kueri untuk pencarian sederhana
• Contoh kueri untuk pencarian Lucene lengkap
• Dokumen Pencarian
• Sintaksis ekspresi OData untuk filter dan pengurutan
• Sintaks kueri sederhana di Azure AI Search