Gambaran umum bahasa OData untuk $filter, $orderby, dan $select di Azure AI Search
Artikel ini menyediakan gambaran umum bahasa ekspresi OData yang digunakan dalam $filter, , $order-bydan $select ekspresi untuk pencarian kata kunci di Azure AI Search melalui bidang numerik dan string (nonvector).
Bahasa disajikan "bottom-up" dimulai dengan elemen paling dasar. Ekspresi OData yang dapat Anda buat dalam permintaan kueri berkisar dari sederhana hingga sangat kompleks, tetapi semuanya berbagi elemen umum. Elemen bersama meliputi:
- Jalur bidang, yang merujuk ke bidang tertentu dari indeks Anda.
- Konstanta, yang merupakan nilai literal dari jenis data tertentu.
Setelah memahami konsep umum ini, Anda dapat melanjutkan dengan sintaks tingkat atas untuk setiap ekspresi:
- $filter ekspresi dievaluasi selama penguraian kueri, membatasi pencarian ke bidang tertentu atau menambahkan kriteria kecocokan yang digunakan selama pemindaian indeks.
- $orderby ekspresi diterapkan sebagai langkah pasca-pemrosesan di atas tataan hasil untuk mengurutkan dokumen yang dikembalikan.
- ekspresi $select menentukan bidang dokumen mana yang disertakan dalam tataan hasil.
Sintaks ekspresi ini berbeda dari sintaks kueri sederhana atau lengkap yang digunakan dalam parameter pencarian , meskipun ada beberapa tumpang tindih dalam sintaks untuk merujuk bidang.
Untuk contoh dalam bahasa lain seperti Python atau C#, lihat contoh di repositori azure-search-vector-samples .
Catatan
Terminologi dalam Azure AI Search berbeda dari standar OData dalam beberapa cara. Apa yang kita sebut bidang di Azure AI Search disebut properti di OData, dan demikian pula untuk jalur bidang versus jalur properti. Indeks yang berisi dokumen dalam Azure AI Search disebut lebih umum di OData sebagai kumpulan entitas yang berisi entitas. Terminologi Azure AI Search digunakan di seluruh referensi ini.
Jalur bidang
EBNF (Extended Backus-Naur Form) berikut mendefinisikan tata bahasa dari jalur bidang.
field_path ::= identifier('/'identifier)*
identifier ::= [a-zA-Z_][a-zA-Z_0-9]*
Diagram sintaksis interaktif juga tersedia:
Catatan
Lihat Referensi sintaks ekspresi OData untuk Pencarian Azure AI untuk EBNF lengkap.
Jalur bidang terdiri dari satu atau beberapa pengidentifikasi yang dipisahkan oleh garis miring. Setiap pengidentifikasi adalah urutan karakter yang harus dimulai dengan huruf atau garis bawah ASCII, dan hanya berisi huruf, digit, atau garis bawah ASCII. Huruf-hurufnya bisa berupa huruf besar atau kecil.
Pengidentifikasi dapat merujuk ke nama bidang, atau ke variabel rentang dalam konteks ekspresi koleksi ( anyatauall ) dalam filter. Variabel rentang seperti variabel perulangan yang mewakili elemen koleksi saat ini. Untuk koleksi kompleks, variabel tersebut mewakili objek, itulah sebabnya Anda dapat menggunakan jalur bidang untuk merujuk ke subbidang variabel. Ini dianalogikan dengan notasi titik dalam banyak bahasa pemrograman.
Contoh jalur bidang diperlihatkan dalam tabel berikut ini:
| Jalur bidang | Deskripsi |
|---|---|
HotelName |
Merujuk ke bidang tingkat atas indeks |
Address/City |
Mengacu pada City subbidang bidang kompleks dalam indeks; Address adalah jenis Edm.ComplexType dalam contoh ini |
Rooms/Type |
Mengacu pada Type subbidang bidang koleksi kompleks dalam indeks; Rooms adalah jenis Collection(Edm.ComplexType) dalam contoh ini |
Stores/Address/Country |
Mengacu pada Country subbidang Address subbidang bidang koleksi kompleks dalam indeks; Stores berjenis Collection(Edm.ComplexType) dan Address berjenis Edm.ComplexType dalam contoh ini |
room/Type |
Mengacu pada Type subbidang room variabel rentang, misalnya dalam ekspresi filter Rooms/any(room: room/Type eq 'deluxe') |
store/Address/Country |
Mengacu pada Country subbidang Address subbidang store variabel rentang, misalnya dalam ekspresi filter Stores/any(store: store/Address/Country eq 'Canada') |
Arti dari jalur bidang berbeda tergantung pada konteksnya. Dalam filter, jalur bidang mengacu pada nilai instans tunggal dari bidang dalam dokumen saat ini. Dalam konteks lain, seperti $orderby, $select, atau dalam pencarian bidang dalam sintaks Lucene lengkap, jalur bidang mengacu pada bidang itu sendiri. Perbedaan ini memiliki beberapa konsekuensi tergantung cara Anda menggunakan jalur bidang dalam filter.
Pertimbangkan jalur bidang Address/City. Dalam filter, ini mengacu pada satu kota untuk dokumen saat ini, seperti "San Francisco". Sebaliknya, Rooms/Type mengacu pada subbidang Type untuk banyak kamar (seperti "standar" untuk kamar pertama, "deluxe" untuk kamar kedua, dan sebagainya). Karena Rooms/Type tidak merujuk ke satu instans subbidang Type, itu tidak dapat digunakan langsung dalam filter. Sebagai gantinya, untuk memfilter pada jenis kamar, Anda akan menggunakan ekspresi lambda dengan variabel rentang, seperti ini:
Rooms/any(room: room/Type eq 'deluxe')
Dalam contoh ini, variabel rentang room muncul di room/Type jalur bidang. Dengan begitu, room/Type mengacu pada jenis ruangan saat ini dalam dokumen saat ini. Ini adalah satu instans Type subbidang, sehingga dapat digunakan langsung di filter.
Menggunakan jalur bidang
Jalur bidang digunakan dalam banyak parameter REST API Azure AI Search. Tabel berikut ini mencantumkan semua tempat di mana mereka dapat digunakan, ditambah batasan bagi penggunaannya:
| API | Nama Parameter | Batasan |
|---|---|---|
| Buat atau Perbarui Indeks | suggesters/sourceFields |
Tidak |
| Buat atau Perbarui Indeks | scoringProfiles/text/weights |
Hanya bisa merujuk ke bidang yang dapat dicari |
| Buat atau Perbarui Indeks | scoringProfiles/functions/fieldName |
Hanya bisa merujuk ke bidang yang dapat difilter |
| Mencari | search ketika queryType merupakan full |
Hanya bisa merujuk ke bidang yang dapat dicari |
| Mencari | facet |
Hanya bisa merujuk ke bidang facetable |
| Mencari | highlight |
Hanya bisa merujuk ke bidang yang dapat dicari |
| Mencari | searchFields |
Hanya bisa merujuk ke bidang yang dapat dicari |
| Menyarankan dan Lengkapi otomatis | searchFields |
Hanya bisa merujuk ke bidang yang merupakan bagian dari saran |
| Cari, Sarankan, dan Lengkapi Otomatis | $filter |
Hanya bisa merujuk ke bidang yang dapat difilter |
| Cari dan Sarankan | $orderby |
Hanya bisa merujuk ke bidang yang dapat diurutkan |
| Cari, Sarankan, dan Temukan | $select |
Hanya bisa merujuk ke bidang yang dapat diambil |
Konstanta
Konstanta dalam OData adalah nilai literal dari jenis Model Data Entitas (EDM) tertentu. Lihat Jenis data yang didukung untuk daftar jenis yang didukung di Azure AI Search. Konstanta jenis koleksi tidak didukung.
Tabel berikut ini memperlihatkan contoh konstanta untuk setiap jenis data nonvektor yang mendukung ekspresi OData:
| Jenis Data | Contoh konstanta |
|---|---|
Edm.Boolean |
true, false |
Edm.DateTimeOffset |
2019-05-06T12:30:05.451Z |
Edm.Double |
3.14159, , -1.2e7NaN, , INF,-INF |
Edm.GeographyPoint |
geography'POINT(-122.131577 47.678581)' |
Edm.GeographyPolygon |
geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))' |
Edm.Int32 |
123, -456 |
Edm.Int64 |
283032927235 |
Edm.String |
'hello' |
Lolos dari karakter khusus dalam konstanta untai (karakter)
Konstanta untai (karakter) di OData dibatasi oleh tanda kutip tunggal. Jika Anda perlu membuat kueri dengan konstanta untai (karakter) yang mungkin berisi tanda kutip, Anda bisa lolos dari tanda kutip yang disematkan dengan menggandakannya.
Misalnya, frasa dengan apostrof yang tidak diformat seperti "mobil Alice" akan diwakili dalam OData sebagai konstanta untai (karakter) 'Alice''s car'.
Penting
Saat membuat filter secara terprogram, penting untuk diingat untuk menghindari konstanta untai (karakter) yang berasal dari input pengguna. Ini untuk mengurangi kemungkinan serangan injeksi, terutama ketika menggunakan filter untuk menerapkan pemangkasan keamanan.
Sintaks konstanta
EBNF (Extended Backus-Naur ) berikutini mendefinisikan tata bahasa untuk sebagian besar konstanta yang diperlihatkan dalam tabel di atas. Tata bahasa untuk jenis geo-spasial dapat ditemukan dalam fungsi geo-spasial OData di Azure AI Search.
constant ::=
string_literal
| date_time_offset_literal
| integer_literal
| float_literal
| boolean_literal
| 'null'
string_literal ::= "'"([^'] | "''")*"'"
date_time_offset_literal ::= date_part'T'time_part time_zone
date_part ::= year'-'month'-'day
time_part ::= hour':'minute(':'second('.'fractional_seconds)?)?
zero_to_fifty_nine ::= [0-5]digit
digit ::= [0-9]
year ::= digit digit digit digit
month ::= '0'[1-9] | '1'[0-2]
day ::= '0'[1-9] | [1-2]digit | '3'[0-1]
hour ::= [0-1]digit | '2'[0-3]
minute ::= zero_to_fifty_nine
second ::= zero_to_fifty_nine
fractional_seconds ::= integer_literal
time_zone ::= 'Z' | sign hour':'minute
sign ::= '+' | '-'
/* In practice integer literals are limited in length to the precision of
the corresponding EDM data type. */
integer_literal ::= digit+
float_literal ::=
sign? whole_part fractional_part? exponent?
| 'NaN'
| '-INF'
| 'INF'
whole_part ::= integer_literal
fractional_part ::= '.'integer_literal
exponent ::= 'e' sign? integer_literal
boolean_literal ::= 'true' | 'false'
Diagram sintaksis interaktif juga tersedia:
Catatan
Lihat Referensi sintaks ekspresi OData untuk Pencarian Azure AI untuk EBNF lengkap.
Membangun ekspresi dari jalur bidang dan konstanta
Jalur bidang dan konstanta adalah bagian paling mendasar dari ekspresi OData, tetapi hal tersebut merupakan ekspresi penuh itu sendiri. Bahkan, parameter $select di Azure AI Search tidak lain adalah daftar jalur bidang yang dipisahkan koma, dan $orderby tidak jauh lebih rumit daripada $select. Jika Anda kebetulan memiliki bidang jenis Edm.Boolean dalam indeks Anda, Anda bahkan dapat menulis filter yang tidak lain adalah jalur dari bidang tersebut. Konstanta true dan false juga filter yang valid.
Namun, lebih umum untuk memiliki ekspresi kompleks yang merujuk ke lebih dari satu bidang dan konstanta. Ekspresi ini dibangun dengan cara yang berbeda tergantung pada parameternya.
EBNF(Extended Backus-Naur Form) berikut mendefinisikan tata bahasa untuk parameter $filter, $orderby, $select. Ini dibangun dari ekspresi yang lebih sederhana yang merujuk ke jalur bidang dan konstanta:
filter_expression ::= boolean_expression
order_by_expression ::= order_by_clause(',' order_by_clause)*
select_expression ::= '*' | field_path(',' field_path)*
Diagram sintaksis interaktif juga tersedia:
Catatan
Lihat Referensi sintaks ekspresi OData untuk Pencarian Azure AI untuk EBNF lengkap.
Langkah berikutnya
Parameter $orderby dan $select keduanya merupakan daftar ekspresi yang lebih sederhana yang dipisahkan koma. Parameter $filter adalah ekspresi Boolean yang terdiri dari subekspresi yang lebih sederhana. Subekspresi ini dikombinasikan menggunakan operator logis seperti operator , , ordan not, perbandingan sepertieq , , lt, gtdan sebagainya, dan operator pengumpulan seperti any dan all.and
Parameter $filter, $orderby, dan $select, dan dieksplorasi secara lebih rinci dalam artikel berikut: