Поделиться через

Справочник по синтаксису выражений OData для поиска ИИ Azure

  • Статья

Поиск ИИ Azure использует выражения OData в качестве параметров по всему API. Чаще всего выражения OData применяются для параметров $orderby и $filter. Эти выражения могут быть сложными и включать несколько предложений, функций и операторов. Однако даже простые выражения OData, такие как пути свойств, используются во многих частях REST API поиска ИИ Azure. Например, выражения пути используются для ссылки на подфилды сложных полей в API, например при перечислении подфилдов в средстве предложения, функции оценки, $select параметра или даже поля поиска в запросах Lucene.

В этой статье описываются все эти формы выражений OData, в которых используется формальная грамматика. Кроме того, вам доступна интерактивная схема, позволяющая визуально изучить грамматику.

Формальная грамматика

Мы можем описать подмножество языка OData, поддерживаемого поиском ИИ Azure, с помощью грамматики EBNF (расширенная форма Backus-Naur). Перечень правил формируется "сверху вниз",начиная с наиболее сложных выражений, которые затем разбиваются на более простые выражения. Вверху приведены правила грамматики, соответствующие определенным параметрам REST API службы "Поиск ИИ Azure":

  • $filter, определяется правилом filter_expression.
  • $orderby, определяется правилом order_by_expression.
  • $select, определяется правилом select_expression.
  • Пути к полям, определяемые правилом field_path. Пути к полям используются в разных разделах API. Они могут ссылаться на поля верхнего уровня индекса или подполя с одним или несколькими сложными предками полей .

На основе EBNF создана схема синтаксиса с возможностью просмотра, которая позволяет интерактивно исследовать грамматику и связи между ее правилами.

/* 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'"

Схема синтаксиса

Чтобы визуально изучить грамматику языка OData, поддерживаемую поиском ИИ Azure, попробуйте использовать интерактивную схему синтаксиса:

Схема синтаксиса OData для поиска ИИ Azure

См. также