Fungsi OData search.in di Azure AI Search
Skenario umum dalam ekspresi filter OData adalah memeriksa apakah satu bidang di setiap dokumen sama dengan salah satu dari banyak kemungkinan nilai. Misalnya, ini adalah cara beberapa aplikasi menerapkan pemangkasan keamanan -- dengan mencentang bidang yang berisi satu atau beberapa ID utama terhadap daftar ID utama yang mewakili pengguna yang mengeluarkan kueri. Salah satu cara untuk menulis kueri seperti ini adalah menggunakan operator eq dan or:
group_ids/any(g: g eq '123' or g eq '456' or g eq '789')
Namun, ada cara yang lebih singkat untuk menulis ini, menggunakan fungsi search.in:
group_ids/any(g: search.in(g, '123, 456, 789'))
Penting
Selain lebih pendek dan lebih mudah dibaca, menggunakan search.in juga memberikan manfaat performa dan menghindari batasan ukuran filter tertentu jika ada ratusan atau bahkan ribuan nilai untuk disertakan dalam filter. Karena alasan ini, kami sangat menyarankan untuk menggunakan search.in alih-alih disjungsi persamaan yang lebih kompleks.
Catatan
Versi 4.01 dari standar OData baru-baru ini memperkenalkan in operator, yang memiliki perilaku serupa dengan search.in fungsi di Azure AI Search. Namun, Azure AI Search tidak mendukung operator ini, jadi Anda harus menggunakan fungsi sebagai gantinya search.in .
Sintaks
EBNF (Extended Backus-Naur Form) berikut mendefinisikan tata bahasa dari fungsi search.in:
search_in_call ::=
'search.in(' variable ',' string_literal(',' string_literal)? ')'
Diagram sintaksis interaktif juga tersedia:
Catatan
Lihat Referensi sintaks ekspresi OData untuk Pencarian Azure AI untuk EBNF lengkap.
Fungsi search.in menguji apakah bidang untai atau variabel rentang yang diberikan sama dengan salah satu daftar nilai yang diberikan. Kesetaraan antara variabel dan setiap nilai dalam daftar ditentukan dengan cara sensitif huruf besar/kecil, dengan cara yang sama seperti untuk operator eq. Oleh karena itu ekspresi seperti search.in(myfield, 'a, b, c') setara dengan myfield eq 'a' or myfield eq 'b' or myfield eq 'c', kecuali bahwa search.in akan menghasilkan performa yang jauh lebih baik.
Ada dua kelebihan dari fungsi search.in:
search.in(variable, valueList)search.in(variable, valueList, delimiters)
Parameter didefinisikan dalam tabel berikut:
| Nama Parameter | Tipe | Deskripsi |
|---|---|---|
variable |
Edm.String |
Referensi bidang string (atau variabel rentang di atas bidang kumpulan string jika search.in digunakan di dalam ekspresi any atau all). |
valueList |
Edm.String |
Untai berisi daftar nilai yang dipisahkan untuk dicocokkan dengan parameter variable. Jika parameter delimiters tidak ditentukan, pembatas default adalah spasi dan koma. |
delimiters |
Edm.String |
Untai di mana setiap karakter diperlakukan sebagai pemisah saat mengurai parameter valueList. Nilai default parameter ini adalah ' ,' yang berarti bahwa setiap nilai dengan spasi dan/atau koma di antaranya akan dipisahkan. Jika Anda perlu menggunakan pemisah selain spasi dan koma karena nilai Anda menyertakan karakter tersebut, Anda dapat menentukan pembatas alternatif seperti '|' dalam parameter ini. |
Performa search.in
Jika Anda menggunakan search.in, Anda dapat mengharapkan waktu respons sub-detik saat parameter kedua berisi daftar ratusan atau ribuan nilai. Tidak ada batasan eksplisit mengenai jumlah item yang dapat diberikan ke search.in, meskipun Anda masih dibatasi oleh ukuran permintaan maksimum. Namun, latensi akan bertambah seiring dengan bertambahnya jumlah nilai.
Contoh
Temukan semua hotel dengan nama yang sama dengan 'Sea View motel' atau 'Budget hotel'. Frase berisi spasi, yang merupakan pembatas default. Anda dapat menentukan pembatas alternatif dalam tanda kutip tunggal sebagai parameter string ketiga:
search.in(HotelName, 'Sea View motel,Budget hotel', ',')
Temukan semua hotel dengan nama yang sama dengan 'Sea View motel' atau 'Budget hotel yang dipisahkan dengan '|'):
search.in(HotelName, 'Sea View motel|Budget hotel', '|')
Temukan semua hotel dengan kamar yang memiliki tag 'wifi' atau 'tub':
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))
Temukan kecocokan pada frasa dalam koleksi, seperti 'heated towel racks' atau 'hairdryer included' dalam tag.
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))
Temukan semua hotel tanpa tag 'motel' atau 'cabin':
Tags/all(tag: not search.in(tag, 'motel, cabin'))