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

Azure Cognitive Search mendukung subset sintaks ekspresi OData untuk ekspresi $filter, $orderby, $select. Ekspresi filter dievaluasi selama penguraian kueri, membatasi pencarian ke bidang tertentu atau menambahkan kriteria kecocokan yang digunakan selama pemindaian indeks. Urutkan berdasarkan Ekspresi diterapkan sebagai langkah pascapemrosesan atas tataan hasil untuk mengurutkan dokumen yang dikembalikan. Pilih ekspresi menentukan bidang dokumen mana yang disertakan dalam tataan hasil. Sintaks ekspresi ini berbeda dari sintaks kueri sederhana atau penuh yang digunakan dalam parameter pencarian, meskipun ada beberapa tumpang tindih dalam sintaks untuk mereferensikan bidang.

Artikel ini menyediakan gambaran umum bahasa pemrogram ekspresi OData yang digunakan dalam filter, urutan menurut, dan memilih ekspresi. Bahasa pemrogram ini disajikan "bottom-up", dimulai dengan elemen paling dasar dan membangun tingkatannya. Sintaks tingkat atas untuk setiap parameter dijelaskan dalam artikel terpisah:

Ekspresi OData berkisar dari sederhana hingga sangat kompleks, tetapi semuanya berbagi elemen umum. Bagian paling mendasar dari ekspresi OData di Azure Cognitive Search adalah:

  • Jalur bidang, yang merujuk ke bidang tertentu dari indeks Anda.
  • Konstanta, yang merupakan nilai literal dari jenis data tertentu.

Catatan

Terminologi dalam Azure Cognitive Search yang berbeda dari standar OData dalam beberapa hal. Apa yang kami sebut bidang di Azure Cognitive Search disebut properti di OData, dan juga sama untuk jalur bidang versus jalur properti. Indeks yang berisi dokumen dalam Azure Cognitive Search disebut secara lebih umum di OData sebagai set entitas yang berisi beberapa entitas. Terminologi Azure Cognitive 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 sintaks interaktif juga tersedia:

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 sub-bidang 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 Merujuk ke City sub-bidang dari bidang yang kompleks dalam indeks; Address yang merupakan jenisEdm.ComplexType pada contoh ini
Rooms/Type Merujuk ke Type sub-bidang dari bidang koleksi kompleks dalam indeks; Rooms yang merupakan jenisCollection(Edm.ComplexType) pada contoh ini
Stores/Address/Country Merujuk ke Country sub-bidang dari Address sub-bidang dari bidang koleksi kompleks dalam indeks; Stores yang merupakan jenis Collection(Edm.ComplexType) dan Address yang merupakan jenis Edm.ComplexType dalam contoh ini
room/Type Mengacu pada Type sub-bidang dari roomvariabel rentang, misalnya dalam ekspresi filter Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country Merujuk ke Country sub-bidang dari Address sub-bidang dari 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 Type sub-bidang untuk banyak kamar (seperti "standar" untuk kamar pertama, "deluxe" untuk kamar kedua, dan sebagainya). Karena Rooms/Type tidak merujuk ke instans tunggal dari sub-bidang 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 instans tunggal dari Type sub-bidang, sehingga dapat digunakan langsung di filter.

Menggunakan jalur bidang

Jalur bidang digunakan dalam banyak parameter API REST Azure Cognitive 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
Cari search ketika queryType merupakan full Hanya bisa merujuk ke bidang yang dapat dicari
Cari facet Hanya bisa merujuk ke bidang facetable
Cari highlight Hanya bisa merujuk ke bidang yang dapat dicari
Cari 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 Cognitive Search. Konstanta jenis koleksi tidak didukung.

Tabel berikut ini memperlihatkan contoh konstanta untuk setiap jenis data yang didukung oleh Azure Cognitive Search:

Jenis data Contoh konstanta
Edm.Boolean true, false
Edm.DateTimeOffset 2019-05-06T12:30:05.451Z
Edm.Double 3.14159, -1.2e7, NaN, 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 Cognitive 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 sintaks interaktif juga tersedia:

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 Cognitive 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 sintaks interaktif juga tersedia:

Parameter $orderby dan $select keduanya merupakan daftar ekspresi yang lebih sederhana yang dipisahkan koma. Parameter $filter adalah ekspresi Boolean yang terdiri dari sub-ekspresi yang lebih sederhana. Sub-ekspresi ini digabungkan menggunakan operator logika seperti and, or, dan not, operator perbandingan seperti eq, lt, gt dan sebagainya, dan operator koleksi seperti any dan all.

Parameter $filter, $orderby, dan $select, dan dieksplorasi secara lebih rinci dalam artikel berikut:

Lihat juga