Sintaks kueri sederhana dalam Pencarian Azure AI

Catatan

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Untuk skenario pencarian teks lengkap, Pencarian Azure AI mengimplementasikan dua bahasa kueri berbasis Lucene, masing-masing selaras dengan pengurai kueri. Parser Kueri Sederhana adalah default. Ini mencakup kasus penggunaan umum dan berusaha menginterpretasikan permintaan bahkan jika tidak disusun dengan sempurna. Pengurai lainnya adalah Lucene Query Parser dan mendukung konstruksi kueri yang lebih canggih.

Artikel ini adalah referensi sintaks kueri untuk pengurai kueri sederhana.

Sintaks kueri untuk kedua pengurai berlaku untuk ekspresi kueri yang diteruskan dalam search parameter permintaan kueri, yang tidak boleh dikacaukan dengan sintaks OData, yang memiliki sintaks dan aturan tersendiri untuk ekspresi filter dan orderby dalam permintaan yang sama.

Meskipun pengurai sederhana didasarkan pada kelas Apache Lucene Simple Query Parser, implementasinya dalam Pencarian Azure AI mengecualikan pencarian fuzzy. Jika Anda memerlukan pencarian fuzzy, pertimbangkan sintaks kueri Lucene lengkap alternatif sebagai gantinya.

Contoh (sintaks sederhana)

Contoh ini memperlihatkan kueri sederhana, dibedakan oleh "queryType": "simple" dan sintaks yang valid. Meskipun jenis kueri diatur di bawah ini, ini adalah default dan dapat dihilangkan kecuali Anda kembali dari jenis alternatif. Contoh berikut adalah pencarian melalui istilah independen, dengan persyaratan bahwa semua dokumen yang cocok menyertakan "pool".

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2026-04-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

Parameter searchMode relevan dalam contoh ini. Setiap kali operator boolean berada di kueri, Anda umumnya harus mengatur searchMode=all untuk memastikan bahwa semua kriteria cocok. Jika tidak, Anda dapat menggunakan default searchMode=any yang lebih mengutamakan penarikan kembali daripada presisi.

Untuk contoh selengkapnya, lihat Contoh sintaks kueri sederhana. Untuk detail tentang permintaan dan parameter kueri, lihat Dokumen Pencarian (REST API).

Pencarian kata kunci pada istilah dan frasa

String yang diteruskan ke search parameter dapat mencakup istilah atau frasa dalam bahasa apa pun yang didukung, operator boolean, operator prioritas, karakter wildcard atau awalan untuk kueri "dimulai dengan", karakter escape, dan karakter pengodean URL. Parameter search bersifat opsional. Tanpa spesifikasi, pencarian (search=* atau search=" ") mengembalikan 50 dokumen teratas dalam urutan acak (tidak terdaftar).

  • Pencarian istilah adalah kueri dari satu atau beberapa istilah, di mana salah satu istilah dianggap cocok.

  • Pencarian frasa adalah frasa persis yang diapit dalam " "tanda kutip. Misalnya, sementara Roach Motel (tanpa tanda kutip) akan mencari dokumen yang berisi Roach dan/atau Motel di mana saja dalam urutan apa pun, "Roach Motel" (dengan tanda kutip) hanya akan cocok dengan dokumen yang berisi seluruh frasa tersebut bersama-sama dan dalam urutan tersebut (analisis leksikal masih berlaku).

Bergantung pada klien pencarian Anda, Anda mungkin perlu melepaskan tanda kutip dalam pencarian frasa. Misalnya, dalam permintaan POST, pencarian frasa di "Roach Motel" dalam isi permintaan mungkin ditentukan sebagai "\"Roach Motel\"". Jika Anda menggunakan Azure SDK, klien pencarian akan lolos dari tanda kutip saat menserialisasikan teks pencarian. Frasa pencarian Anda dapat dikirim menjadi "Roach Motel".

Secara default, semua string yang diteruskan dalam search parameter mengalami analisis leksikal. Pastikan Anda memahami perilaku tokenisasi penganalisis yang Anda gunakan. Seringkali, ketika hasil kueri tidak terduga, alasannya dapat ditelusuri tentang bagaimana istilah ditokenisasi pada waktu kueri. Anda dapat menguji tokenisasi pada string tertentu untuk mengonfirmasi output.

Input teks apa pun dengan satu atau beberapa istilah dianggap sebagai titik awal yang valid untuk eksekusi kueri. Pencarian Azure AI akan mencocokkan dokumen yang berisi salah satu atau semua istilah, termasuk variasi apa pun yang ditemukan selama analisis teks.

Seperti terdengar sederhana, ada satu aspek dari eksekusi kueri dalam Pencarian Azure AI yang mungkin menghasilkan hasil yang tidak terduga, meningkat daripada mengurangi hasil pencarian ketika lebih banyak istilah dan operator ditambahkan ke string input. Apakah perluasan ini benar-benar terjadi tergantung pada penyertaan operator NOT, dikombinasikan dengan searchMode pengaturan parameter yang menentukan bagaimana NOT diinterpretasikan dalam konteks perilaku AND atau OR. Untuk informasi selengkapnya, lihat operator di NOT bawah operator Boolean.

Operator Boolean

Anda dapat menyematkan operator Boolean dalam string kueri untuk meningkatkan presisi kecocokan. Dalam sintaks sederhana, operator boolean berbasis karakter. Operator teks, seperti kata AND, tidak didukung.

Karakter Contoh Penggunaan
+ pool + ocean Sebuah AND operasi. Misalnya, pool + ocean menetapkan bahwa dokumen harus berisi kedua istilah.
| pool | ocean Operasi OR menemukan kecocokan ketika salah satu istilah ditemukan. Dalam contoh, mesin kueri akan mengembalikan kecocokan pada dokumen yang berisi atau poolocean atau keduanya. Karena OR adalah operator konjunsi default, Anda juga dapat menghilangkannya, sehingga pool ocean adalah setara dengan pool | ocean.
- pool – ocean Operasi NOT mengembalikan kecocokan pada dokumen yang mengecualikan istilah.

Parameter searchMode pada permintaan kueri mengontrol apakah istilah dengan operator NOT diproses atau digabungkan dengan istilah lain dalam kueri (dengan asumsi tidak ada operator boolean pada istilah lain). Nilai yang valid meliputi any atau all.

searchMode=any meningkatkan pengenalan kueri dengan menyertakan lebih banyak hasil, dan secara default - akan ditafsirkan sebagai "ATAU TIDAK". Misalnya, pool - ocean akan cocok dengan dokumen yang berisi istilah pool atau yang tidak berisi istilah ocean.

searchMode=all meningkatkan presisi kueri dengan menyertakan lebih sedikit hasil, dan secara default - akan ditafsirkan sebagai "DAN TIDAK". Misalnya, dengan searchMode=any, kueri pool - ocean akan cocok dengan dokumen yang berisi istilah "kolam" dan semua dokumen yang tidak berisi istilah "samudra". Ini bisa dibilang perilaku yang lebih intuitif bagi - operator. Oleh karena itu, Anda harus mempertimbangkan untuk menggunakan searchMode=all alih-alih searchMode=any jika Anda ingin mengoptimalkan pencarian untuk presisi alih-alih pengenalan, dan pengguna Anda sering menggunakan - operator dalam pencarian.

Saat menentukan pengaturan searchMode, pertimbangkan pola interaksi pengguna untuk kueri di berbagai aplikasi. Pengguna yang mencari informasi lebih cenderung menyertakan operator dalam kueri, dibandingkan dengan situs e-niaga yang memiliki lebih banyak struktur navigasi bawaan.

Kueri awalan

Untuk kueri "dimulai dengan", tambahkan operator akhiran (*) sebagai tempat penampung untuk sisa istilah. Kueri awalan harus dimulai dengan setidaknya satu karakter teks biasa sebelum Anda dapat menambahkan operator akhiran.

Karakter Contoh Penggunaan
* lingui* akan cocok pada "linguistic" atau "linguini" Tanda bintang (*) mewakili satu atau beberapa karakter dengan panjang sembarang, mengabaikan huruf besar/kecil.

Mirip dengan filter, kueri awalan mencari kecocokan yang tepat. Dengan demikian, tidak ada penilaian relevansi (semua hasil menerima skor pencarian 1,0). Ketahuilah bahwa kueri awalan bisa lambat, terutama jika indeks besar dan awalan terdiri dari sejumlah kecil karakter. Metodologi alternatif, seperti tokenisasi n-gram tepi, mungkin berkinerja lebih cepat. Istilah yang menggunakan pencarian awalan tidak boleh lebih dari 1000 karakter.

Sintaks sederhana hanya mendukung pencocokan awalan. Untuk pencocokan akhiran atau infiks terhadap akhir atau bagian tengah istilah, gunakan sintaks Lucene penuh untuk pencarian wildcard.

Melarikan diri operator pencarian

Dalam sintaks sederhana, operator pencarian menyertakan karakter ini: + | " ( ) ' \

Jika salah satu karakter ini adalah bagian dari token dalam indeks, keluarkan dengan mengawalinya dengan garis miring terbalik tunggal (\) dalam kueri. Misalnya, Anda menggunakan penganalisis kustom untuk seluruh tokenisasi istilah, dan indeks Anda berisi string "Luxury+Hotel". Untuk mendapatkan kecocokan yang tepat pada token ini, masukkan karakter escape: search=luxury\+hotel.

Untuk mempermudah kasus yang lebih umum, ada dua pengecualian untuk aturan ini di mana penghindaran tidak diperlukan.

  • Operator NOT - hanya perlu diloloskan jika itu adalah karakter pertama setelah spasi kosong. Jika - muncul di tengah (misalnya, di 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), Anda dapat melewatkan penandaan.

  • Operator akhiran * hanya perlu diloloskan jika itu adalah karakter terakhir sebelum spasi kosong. * Jika muncul di tengah (misalnya, dalam 4*4=16), tidak diperlukan pelepasan.

Catatan

Secara default, penganalisis standar akan menghapus dan memecah kata-kata pada tanda hubung, spasi putih, ampersands, dan karakter lainnya selama analisis leksikal. Jika Anda memerlukan karakter khusus untuk tetap berada dalam string kueri, Anda mungkin memerlukan penganalisis yang mempertahankannya dalam indeks. Beberapa pilihan termasuk penganalisis bahasa alami Microsoft, yang mempertahankan kata-kata berimbuhan, atau penganalisis kustom untuk pola yang lebih kompleks. Untuk informasi selengkapnya, lihat Istilah parsial, pola, dan karakter khusus.

Pengodean karakter yang tidak aman dan dipesan dalam URL

Pastikan semua karakter yang tidak aman dan yang dipesan dienkodekan dalam sebuah URL. Misalnya, '#' adalah karakter yang tidak aman karena merupakan pengidentifikasi fragmen/jangkar dalam URL. Karakter harus dikodekan menjadi %23 jika digunakan dalam URL. '&' dan '=' adalah contoh karakter cadangan untuk memisahkan parameter dan menentukan nilai dalam Pencarian Azure AI. Untuk informasi selengkapnya, lihat RFC1738: Uniform Resource Locators (URL).

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

Karakter khusus

Karakter khusus dapat berkisar dari simbol mata uang seperti '$' atau '€', hingga emoji. Banyak penganalisis, termasuk penganalisis standar default, akan mengecualikan karakter khusus selama pengindeksan, yang berarti mereka tidak akan diwakili dalam indeks Anda.

Jika Anda memerlukan representasi karakter khusus, Anda dapat menetapkan penganalisis yang mempertahankannya:

  • Penganalisis spasi putih mempertimbangkan urutan karakter apa pun yang dipisahkan oleh spasi kosong sebagai token (sehingga emoji '❤' akan dianggap sebagai token).

  • Penganalisis language, seperti penganalisis bahasa Inggris Microsoft (en.microsoft), akan mengambil string '$' atau '€' sebagai token.

Untuk konfirmasi, Anda dapat menguji penganalisis untuk melihat token apa yang dihasilkan untuk string tertentu. Seperti yang Anda harapkan, Anda mungkin tidak mendapatkan tokenisasi penuh dari satu penganalisis. Solusinya adalah membuat beberapa bidang yang berisi konten yang sama, tetapi dengan penetapan penganalisis yang berbeda (misalnya, , description_en, description_frdan sebagainya untuk penganalisis bahasa).

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

Prioritas (pengelompokan)

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

Batas ukuran kueri

Jika aplikasi Anda menghasilkan kueri pencarian secara terprogram, sebaiknya merancangnya sedemikian sehingga tidak menghasilkan kueri dengan ukuran yang tidak terbatas.

  • Untuk GET, panjang URL tidak boleh melebihi 8 KB.

  • Untuk POST (dan permintaan lainnya), di mana isi permintaan menyertakan search dan parameter lain seperti filter dan orderby, ukuran maksimum adalah 16 MB. Batas tambahan meliputi:

    • Panjang maksimum klausa pencarian adalah 100.000 karakter.
    • Jumlah maksimum klausa dalam search (ekspresi yang menggunakan pemisah AND atau OR) adalah 1024.
    • Ukuran istilah pencarian maksimum adalah 1000 karakter untuk pencarian awalan.
    • Ada juga batas sekitar 32 KB pada ukuran setiap istilah individu dalam kueri.

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

Langkah berikutnya

Jika Anda akan membuat kueri secara terprogram, tinjau pencarian teks Full di Pencarian Azure AI untuk memahami tahapan pemrosesan kueri dan implikasi analisis teks.

Anda juga bisa meninjau artikel berikut untuk mempelajari selengkapnya tentang konstruksi kueri:

  • Last updated on