Gambaran umum bahasa OData untuk $filter, $orderby, dan $select di Azure AI Search

  • Artikel

Artikel ini menyediakan gambaran umum tentang bahasa ekspresi OData yang digunakan dalam ekspresi $filter, $order oleh, dan $select di Azure AI Search. 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.

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:

Diagram sintaks OData untuk Azure AI Search

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 ada
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 yang didukung oleh Azure AI Search:

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:

Diagram sintaks OData untuk Azure AI Search

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, sebagian besar waktu Anda akan membutuhkan ekspresi yang lebih 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:

Diagram sintaks OData untuk Azure AI Search

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: