Sintaks kueri Lucene di Pencarian Azure AI

Saat membuat kueri di Pencarian Azure AI, Anda dapat memilih sintaks lengkap Pengurai Kueri Lucene untuk bentuk kueri khusus: wildcard, pencarian fuzzy, pencarian kedekatan, ekspresi reguler. Sebagian besar sintaks Lucene Query Parser diimplementasikan secara utuh dalam Pencarian Azure AI, kecuali untuk pencarian rentang nilai, yang dibangun menggunakan $filter ekspresi.

Untuk menggunakan sintaks Lucene penuh, atur queryType ke full dan masukkan ekspresi kueri yang berpola untuk kartu-bebas, pencarian fuzzy, atau salah satu bentuk 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 berbasis bidang dan peningkatan relevansi frasa. Ini mencari hotel di mana bidang kategori berisi istilah budget. Dokumen yang berisi frasa "recently renovated" menerima bobot peningkatan ekstra dan mungkin memberi peringkat lebih tinggi sebagai hasil dari nilai peningkatan frasa (3).

POST /indexes/hotels-sample/docs/search?api-version=2026-04-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 memecah istilah business~analyst menjadi dua: business ATAU analyst.

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

Pelolosan karakter khusus

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

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

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 = adalah contoh karakter cadangan yang digunakan untuk menandai batas parameter dan menentukan nilai dalam Pencarian Azure AI. 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 cantumkan operator boolean teks (AND, OR, NOT) dengan huruf besar.

¹ Karakter | tidak didukung untuk operasi OR.

OPERATOR BUKAN Boolean

• 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 kartu bebas. 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 seakan-akan selalu digabungkan secara logis ke dalam 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 melakukan pencarian dengan negasi untuk mencari subset dokumen dalam indeks, sintaks penuh atau sintaks sederhana dengan mode pencarian 'semua' disarankan.

Pencarian berdasar 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 di fieldName:searchExpression harus merupakan bidang searchable. Lihat Membuat Indeks untuk detail tentang bagaimana atribut indeks digunakan dalam definisi bidang.

Pencarian fuzzy

Pencarian fuzzy menemukan kecocokan dalam istilah yang memiliki konstruksi serupa, dapat memperluas hingga maksimum 50 istilah yang memenuhi kriteria jarak dua 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 tanda kutip, tetapi Anda dapat menambahkan tilde ke masing-masing istilah dalam nama atau frasa yang terdiri dari beberapa bagian. Misalnya, Unviersty~ of~ Wshington~ akan cocok pada University of Washington.

Pencarian lokasi terdekat

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.

Penguatan istilah

Pikirkan pencarian sebagai dua langkah. Pertama, Pencarian Azure AI menemukan dokumen yang cocok. Kemudian, memberi peringkat pada kecocokan tersebut. Peningkatan bobot istilah hanya memengaruhi langkah kedua: hal ini dapat menaikkan posisi dokumen yang cocok dengan salah satu bagian dari kueri Anda ke posisi yang lebih tinggi dalam hasil pencarian.

Peningkatan istilah berbeda dari profil penilaian. Boost memberi prioritas lebih tinggi pada kata, frasa, atau kelompok dalam kueri saat ini. Profil penilaian mendukung bidang atau konten indeks lainnya sesuai dengan aturan yang ditentukan dalam indeks.

Tingkatkan cakupan

Tulis simbol caret (^) dan bilangan positif tepat setelah bagian kueri yang ingin Anda prioritaskan. Misalnya, tax^2 dapat menempatkan dokumen yang berisi tax lebih tinggi dibandingkan dokumen yang hanya cocok dengan istilah yang bobotnya tidak ditingkatkan. Nilai peningkatan default adalah 1. Anda juga dapat menggunakan nilai antara 0 dan 1, seperti 0.2, untuk memberi bobot yang lebih rendah pada kecocokan.

Tanda baca memberi tahu Anda kata mana yang mempengaruhi setiap instruksi:

• Nama bidang ditambah titik dua, yang disebut awalan bidang, muncul sebelum kata, frasa yang dikutip, atau grup yang dikutip. Misalnya, content: memberi tahu Pencarian Azure AI untuk mencari di bidang content.
• Peningkatan, seperti ^2, muncul setelah kata, frasa yang dikutip, atau grup yang dikurung. Ini memberi tahu Pencarian Azure AI apa yang harus disukai saat memberi peringkat pada pertandingan.

Tabel berikut menggunakan default searchMode=any, di mana spasi antar kata berfungsi seperti OR.

Dengan searchMode=all, kueri deferred tax^2 memerlukan kedua kata untuk dicocokkan. Peningkatan masih hanya berlaku untuk tax. Untuk mencocokkan salah satu kata, tulis deferred OR tax^2.

Letakkan tanda sisipan setelah tanda kutip penutup atau tanda kurung saat Anda ingin meningkatkan seluruh frasa atau grup. Tanda kurung tidak membuat frasa. Gunakan tanda kutip saat kata-kata harus bersebelahan dan dalam urutan tertentu.

Tingkatkan dan cakupan bidang

Nama bidang yang diikuti titik dua membatasi lokasi Pencarian Azure AI mencari. Peningkatan mengubah cara Pencarian Azure AI memberi peringkat kecocokan. Anda bisa menggunakan keduanya dalam kueri yang sama.

Misalnya, jika searchFields diatur ke title, kueri pertama mencari deferred di content dan tax di title. Tanda kutip dan tanda kurung dalam kueri lain tetap menempatkan kedua kata dalam content.

Efek analiser pada kueri yang ditingkatkan

Untuk kata, frasa, dan grup kata biasa, peningkatan tidak melewati analisis teks. Sebelum pencocokan, Pencarian Azure AI tetap memproses teks kueri dengan analisis tiap bidang. Akibatnya, teks yang sama yang diberi boost dapat menghasilkan kecocokan yang berbeda pada field yang menggunakan penganalisis yang berbeda.

Frasa atau kelompok dengan prefiks kolom menggunakan analisator kolom tersebut. Teks tanpa prefiks bidang menggunakan penganalisis untuk setiap bidang yang ditelusuri. Misalnya, penganalisis yang mengubah teks menjadi huruf kecil dapat mencocokkan "DEFERRED TAX"^2 dengan istilah yang diindeks dalam huruf kecil.

Bentuk kueri lainnya, seperti wildcard, ekspresi reguler, dan kueri fuzzy, menggunakan aturan analisis yang berbeda. Menambahkan peningkatan tidak mengubah aturan-aturan tersebut. Untuk informasi selengkapnya, lihat Tahap 2: Analisis leksikal.

Pencarian ekspresi reguler

Pencarian regex menemukan kecocokan berdasarkan pola yang valid di bawah Apache Lucene, seperti yang didokumentasikan di kelas RegExp.

Di Pencarian Azure AI, ekspresi reguler adalah:

• Diapit di antara garis miring ke depan /
• Huruf kecil saja

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

Beberapa alat dan bahasa memberlakukan persyaratan karakter escape ekstra di luar aturan escape yang diberlakukan oleh Pencarian Azure AI. Untuk JSON, string yang menyertakan garis miring ke depan diloloskan dengan garis miring ke belakang: microsoft.com/azure/ menjadi search=/.*microsoft.com\/azure\/.*/ di mana search=/.* <string-placeholder>.*/ menyiapkan ekspresi reguler, dan microsoft.com\/azure\/ adalah string dengan garis miring ke depan yang diloloskan.

Dua simbol umum dalam kueri regex adalah . dan *. Simbol . mencocokkan satu karakter dan simbol * mencocokkan karakter sebelumnya nol atau lebih kali. Misalnya, /be./ cocok dengan istilah bee dan bet, sementara /be*/ akan cocok dengan be, bee, dan beee, tetapi tidak dengan 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 aplikasi klien lain untuk mengonfirmasi apakah masalahnya khusus untuk aplikasi tersebut.

Pencarian karakter pengganti

Anda dapat menggunakan sintaksis yang dikenali secara umum untuk pencarian dengan beberapa (*) atau satu (?) karakter pengganti. Sintaks lengkap Lucene mendukung pencocokan awalan dan infiks. Gunakan ekspresi reguler untuk pencocokan akhiran.

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

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 yang bervariasi yang mengikutinya.

Pencocokan akhiran memerlukan pembatas ekspresi reguler berupa garis miring /. 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 maju / pada regex, * adalah karakter pengganti dan cocok dengan serangkaian karakter seperti .* dalam regex. Sebagai contoh, search=/non.*al/ menghasilkan tataan hasil yang sama dengan search=non*al.

Efek penganalisis pada kueri kartubebas

Selama penguraian kueri, kueri yang diformulasikan sebagai awalan, akhiran, wildcard, atau ekspresi reguler diteruskan apa adanya ke pohon kueri, tanpa melalui 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 dalam 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 (Lucene Bahasa Inggris), penganalisis tersebut akan menerapkan stemming yang agresif pada 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 karakter pengganti dan ekspresi reguler (regex)

Pencarian Azure AI menggunakan penilaian berbasis frekuensi (BM25) untuk kueri teks. Namun, untuk kueri wildcard dan regex di mana cakupan istilah berpotensi luas, faktor frekuensi diabaikan untuk mencegah peringkat menjadi bias terhadap kecocokan dari istilah yang lebih langka. Semua kecocokan diperlakukan sama untuk pencarian wildcard dan regex.

Karakter khusus

Dalam beberapa keadaan, Anda mungkin ingin mencari karakter khusus, seperti emoji '❤' atau tanda '€'. Dalam kasus seperti itu, pastikan analisis yang Anda gunakan tidak memfilter karakter tersebut. Analisis standar mengabaikan 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 di-escape dengan benar di URL kueri (misalnya ❤ akan menggunakan urutan escape %E2%9D%A4+). Beberapa klien REST melakukan terjemahan ini secara otomatis.

Prioritas (pengelompokan)

Gunakan tanda kurung untuk mengontrol bagian kueri mana yang dievaluasi bersama-sama. Misalnya, motel AND (wifi OR luxury) memerlukan motel dan setidaknya salah satu istilah di dalam tanda kurung: wifi atau luxury.

Tempatkan prefiks bidang sebelum kelompok dalam tanda kurung untuk menelusuri seluruh kelompok tersebut dalam satu bidang. Misalnya, hotelAmenities:(wifi OR pool) mencari wifi atau pool hanya di kolom hotelAmenities.

Tanda kurung mengontrol cara AND dan OR bekerja sama. Mereka tidak memerlukan kata-kata untuk muncul di samping satu sama lain atau dalam urutan tertentu. Gunakan tanda kutip untuk perilaku tersebut. Untuk meningkatkan grup, letakkan tanda sisipan setelah kurung tutup, seperti dalam hotelAmenities:(wifi OR pool)^2. Untuk informasi selengkapnya, lihat Meningkatkan cakupan.

Batas ukuran kueri

Pencarian Azure AI 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 Pencarian Azure AI