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

Artikel ini menyediakan gambaran umum bahasa ekspresi OData yang digunakan dalam $filter, , $order-bydan $select ekspresi untuk pencarian kata kunci di Pencarian Azure AI melalui bidang numerik dan string (nonvector).

Bahasa disajikan dari bawah ke atas, dimulai dengan elemen yang 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.
• Ekspresi $orderby diterapkan sebagai langkah pasca-pemrosesan untuk mengurutkan set hasil 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 .

Jalur medan

EBNF (Extended Backus-Naur Form) berikut mendefinisikan tata bahasa dari alur bidang.

field_path ::= identifier('/'identifier)*

identifier ::= [a-zA-Z_][a-zA-Z_0-9]*

Diagram sintaksis 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 subbidang variabel. Ini dianalogikan dengan notasi titik dalam banyak bahasa pemrograman.

Contoh jalur bidang diperlihatkan dalam tabel berikut ini:

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 secara langsung dalam sebuah 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 jalur bidang room/Type. Dengan begitu, room/Type mengacu pada jenis ruangan saat ini dalam dokumen saat ini. Ini adalah sebuah instans tunggal dari Type subbidang, sehingga dapat digunakan langsung dalam filter.

Menggunakan jalur bidang

Jalur bidang digunakan dalam banyak parameter pada REST API Pencarian Azure AI. Tabel berikut ini mencantumkan semua tempat di mana mereka dapat digunakan, ditambah batasan bagi penggunaannya:

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 Pencarian Azure AI. Konstanta pada jenis koleksi tidak didukung.

Tabel berikut ini memperlihatkan contoh konstanta untuk setiap jenis data nonvektor yang mendukung ekspresi OData:

Menghindari karakter khusus pada konstanta untai teks

Konstanta untai (karakter) di OData dibatasi oleh tanda kutip tunggal. Jika Anda perlu membuat kueri dengan konstanta string yang mungkin berisi tanda kutip tunggal, Anda bisa menghindari 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'.

Sintaks konstanta

EBNF (Extended Backus-Naur Form) berikut ini mendefinisikan sintaks untuk sebagian besar konstanta yang ditampilkan dalam tabel di atas. Tata bahasa untuk jenis geo-spasial dapat ditemukan dalam fungsi geo-spasial OData di Pencarian Azure AI.

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:

Membangun ekspresi dari jalur bidang dan konstanta

Jalur bidang dan konstanta adalah bagian paling mendasar dari ekspresi OData, namun keduanya sudah merupakan ekspresi yang lengkap. Bahkan, parameter $select di Pencarian Azure AI 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:

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 and, or, dan not, operator perbandingan seperti , eq, lt, dan seterusnya, serta operator pengumpulan seperti gt dan .

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

• Sintaks $filter OData di Pencarian Azure AI
• Sintaks $orderby OData di Pencarian Azure AI
• Sintaks $select OData di Pencarian Azure AI