Referensi sintaks ekspresi OData untuk Pencarian Azure AI

Pencarian Azure AI menggunakan ekspresi OData sebagai parameter di seluruh API. Umumnya, ekspresi OData digunakan untuk parameter $orderby dan $filter. Ekspresi ini bisa menjadi rumit, berisi beberapa klausul, fungsi, dan operator. Namun, bahkan ekspresi OData sederhana seperti jalur properti digunakan di banyak bagian Rest API Pencarian Azure AI. Misalnya, ekspresi jalur digunakan untuk merujuk ke subbidang kompleks di mana-mana di API, seperti saat mencantumkan subbidang di pemberi saran, fungsi penghitungan skor, $select parameter, atau bahkan pencarian bidang dalam kueri Lucene.

Artikel ini menjelaskan semua bentuk ekspresi OData menggunakan tata bahasa formal. Terdapat juga diagram interaktif untuk membantu mempelajari tata bahasa secara visual.

Tata bahasa formal

Kita dapat menjelaskan subset bahasa OData yang didukung oleh Pencarian Azure AI menggunakan tata bahasa EBNF (Extended Backus-Naur Form). Aturan disusun dari "atas ke bawah", dimulai dari ekspresi yang paling kompleks, lalu dipecah ke ekspresi yang lebih primitif. Di bagian atas adalah aturan tata bahasa yang sesuai dengan parameter tertentu dari AZURE AI Search REST API:

• $filter, ditentukan oleh aturan filter_expression.
• $orderby, ditentukan oleh aturan order_by_expression.
• $select, ditentukan oleh aturan select_expression.
• Jalur kolom, ditentukan oleh aturan field_path. Jalur kolom digunakan di seluruh API. Mereka dapat merujuk ke bidang tingkat atas indeks, atau subbidang dengan satu atau beberapa leluhur bidang yang kompleks.

Setelah EBNF adalah diagram sintaksis yang dapat dijelajahi yang memungkinkan Anda secara interaktif menjelajahi tata bahasa dan hubungan antara aturannya.

/* Top-level rules */

filter_expression ::= boolean_expression

order_by_expression ::= order_by_clause(',' order_by_clause)*

select_expression ::= '*' | field_path(',' field_path)*

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


/* Shared base rules */

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


/* Rules for $orderby */

order_by_clause ::= (field_path | sortable_function) ('asc' | 'desc')?

sortable_function ::= geo_distance_call | 'search.score()'


/* Rules for $filter */

boolean_expression ::=
    collection_filter_expression
    | logical_expression
    | comparison_expression
    | boolean_literal
    | boolean_function_call
    | '(' boolean_expression ')'
    | variable

/* This can be a range variable in the case of a lambda, or a field path. */
variable ::= identifier | field_path

collection_filter_expression ::=
    field_path'/all(' lambda_expression ')'
    | field_path'/any(' lambda_expression ')'
    | field_path'/any()'

lambda_expression ::= identifier ':' boolean_expression

logical_expression ::=
    boolean_expression ('and' | 'or') boolean_expression
    | 'not' boolean_expression

comparison_expression ::= 
    variable_or_function comparison_operator constant | 
    constant comparison_operator variable_or_function

variable_or_function ::= variable | function_call

comparison_operator ::= 'gt' | 'lt' | 'ge' | 'le' | 'eq' | 'ne'


/* Rules for constants and literals */

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 ::= sign? 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'


/* Rules for functions */

function_call ::=
    geo_distance_call |
    boolean_function_call

geo_distance_call ::=
    'geo.distance(' variable ',' geo_point ')'
    | 'geo.distance(' geo_point ',' variable ')'

geo_point ::= "geography'POINT(" lon_lat ")'"

lon_lat ::= float_literal ' ' float_literal

boolean_function_call ::=
    geo_intersects_call |
    search_in_call |
    search_is_match_call

geo_intersects_call ::=
    'geo.intersects(' variable ',' geo_polygon ')'

/* You need at least four points to form a polygon, where the first and
last points are the same. */
geo_polygon ::=
    "geography'POLYGON((" lon_lat ',' lon_lat ',' lon_lat ',' lon_lat_list "))'"

lon_lat_list ::= lon_lat(',' lon_lat)*

search_in_call ::=
    'search.in(' variable ',' string_literal(',' string_literal)? ')'

/* Note that it is illegal to call search.ismatch or search.ismatchscoring
from inside a lambda expression. */
search_is_match_call ::=
    'search.ismatch'('scoring')?'(' search_is_match_parameters ')'

search_is_match_parameters ::=
    string_literal(',' string_literal(',' query_type ',' search_mode)?)?

query_type ::= "'full'" | "'simple'"

search_mode ::= "'any'" | "'all'"

Diagram sintaksis

Untuk menjelajahi tata bahasa OData yang didukung oleh Pencarian Azure AI secara visual, coba diagram sintaks interaktif:

Lihat juga

• Filter di Pencarian Azure AI
• Pencarian Dokumen (Pencarian Azure AI REST API)
• Sintaks kueri Lucene
• Sintaks kueri sederhana di Pencarian Azure AI