Azure 认知搜索的 OData 表达式语法参考OData expression syntax reference for Azure Cognitive Search

Azure 认知搜索在整个 API 中使用 OData 表达式作为参数。Azure Cognitive Search uses OData expressions as parameters throughout the API. 最常见的是,OData 表达式用于 $orderby$filter 参数。Most commonly, OData expressions are used for the $orderby and $filter parameters. 这些表达式可能很复杂,包含多个子句、函数和运算符。These expressions can be complex, containing multiple clauses, functions, and operators. 但是,甚至简单的 OData 表达式(如属性路径)都在 Azure 认知搜索 REST API 的许多部分中使用。However, even simple OData expressions like property paths are used in many parts of the Azure Cognitive Search REST API. 例如,路径表达式用于引用 API 中各处的复杂字段的子字段,例如在建议器评分函数$select 参数,甚至在 Lucene 查询中的字段搜索中列出子字段。For example, path expressions are used to refer to sub-fields of complex fields everywhere in the API, such as when listing sub-fields in a suggester, a scoring function, the $select parameter, or even fielded search in Lucene queries.

本文使用正式语法描述所有这些形式的 OData 表达式。This article describes all these forms of OData expressions using a formal grammar. 还有一个交互式图表,以帮助直观地探索语法。There is also an interactive diagram to help visually explore the grammar.

正式语法Formal grammar

我们可以使用 EBNF(扩展巴科斯-瑙尔范式)语法描述 Azure 认知搜索支持的 OData 语言的子集。We can describe the subset of the OData language supported by Azure Cognitive Search using an EBNF (Extended Backus-Naur Form) grammar. 规则以“自上而下”的方式列出,从最复杂的表达式开始,并将其分解为更原始的表达式。Rules are listed "top-down", starting with the most complex expressions, and breaking them down into more primitive expressions. 顶部是与 Azure 认知搜索 REST API 的特定参数相对应的语法规则:At the top are the grammar rules that correspond to specific parameters of the Azure Cognitive Search REST API:

  • $filter,由 filter_expression 规则定义。$filter, defined by the filter_expression rule.
  • $orderby,由 order_by_expression 规则定义。$orderby, defined by the order_by_expression rule.
  • $select,由 select_expression 规则定义。$select, defined by the select_expression rule.
  • 字段路径,由 field_path 规则定义。Field paths, defined by the field_path rule. 在整个 API 中使用字段路径。Field paths are used throughout the API. 它们可以引用索引的顶级字段,也可以引用具有一个或多个复杂字段祖先的子字段。They can refer to either top-level fields of an index, or sub-fields with one or more complex field ancestors.

EBNF 之后是一个可浏览的语法图,可用于交互式地探索语法及其规则之间的关系。After the EBNF is a browsable syntax diagram that allows you to interactively explore the grammar and the relationships between its rules.

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

语法图Syntax diagram

若要直观地探索 Azure 认知搜索支持的 OData 语言语法,请尝试交互式语法图:To visually explore the OData language grammar supported by Azure Cognitive Search, try the interactive syntax diagram:

另请参阅See also