Visão geral da linguagem OData $filter $orderby para, e $select em Azure Cognitive Search

A Azure Cognitive Search suporta um subconjunto da sintaxe de expressão OData para $filter, $orderby e expressões $select. As expressões de filtro são avaliadas durante a análise de consulta, limitando a procura a campos específicos ou adicionando critérios de correspondência utilizados durante as análises de índices. As expressões ordenadas são aplicadas como um passo pós-processamento sobre um conjunto de resultados para classificar os documentos que são devolvidos. As expressões selecionadas determinam quais os campos de documentos incluídos no conjunto de resultados. A sintaxe destas expressões é distinta da sintaxe de consulta simples ou completa que é usada no parâmetro de pesquisa, embora haja alguma sobreposição na sintaxe para campos de referência.

Este artigo fornece uma visão geral da linguagem de expressão OData utilizada em filtros, encomendas e expressões selecionadas. A linguagem é apresentada "de baixo para cima", começando pelos elementos mais básicos e baseando-se neles. A sintaxe de nível superior para cada parâmetro é descrita num artigo separado:

• sintaxe $filter
• sintaxe $orderby
• sintaxe $select

As expressões OData variam de simples a altamente complexas, mas todas partilham elementos comuns. As partes mais básicas de uma expressão OData na Pesquisa Cognitiva Azure são:

• Caminhos de campo , que se referem a campos específicos do seu índice.
• Constantes, que são valores literais de um determinado tipo de dados.

Caminhos de campo

O seguinte EBNF(Formulário Backus-Naur Alargado)define a gramática dos caminhos de campo.

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

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

Está também disponível um diagrama de sintaxe interativo:

Um caminho de campo é composto por um ou mais identificadores separados por cortes. Cada identificador é uma sequência de caracteres que deve começar com uma letra ASCII ou sublinhar, e conter apenas letras, dígitos ou sublinhados ASCII. As letras podem ser maiúsculas ou minúsculas.

Um identificador pode referir-se ao nome de um campo, ou a uma variável de alcance no contexto de uma expressão de recolha any all (ou) num filtro. Uma variável de gama é como uma variável de loop que representa o elemento atual da coleção. Para coleções complexas, esta variável representa um objeto, razão pela qual pode usar caminhos de campo para se referir a sub-campos da variável. Isto é análogo à notação de pontos em muitas línguas de programação.

Exemplos de percursos de campo são mostrados na tabela seguinte:

O significado de um caminho de campo difere dependendo do contexto. Nos filtros, um caminho de campo refere-se ao valor de uma única instância de um campo no documento atual. Em outros contextos, como $orderby, $select, ou em busca de campo na sintaxe lucene completa,um caminho de campo refere-se ao próprio campo. Esta diferença tem algumas consequências na forma como utiliza caminhos de campo em filtros.

Considere o caminho do Address/City campo. Num filtro, isto refere-se a uma única cidade para o documento atual, como "São Francisco". Em contraste, Rooms/Type Type refere-se ao sub-campo para muitos quartos (como "standard" para o primeiro quarto, "deluxe" para a segunda sala, e assim por diante). Uma Rooms/Type vez que não se refere a um único caso do sub-campo, não pode ser Type usado diretamente num filtro. Em vez disso, para filtrar no tipo de quarto, você usaria uma expressão lambda com uma variável de gama, como esta:

Rooms/any(room: room/Type eq 'deluxe')

Neste exemplo, a variável de alcance room aparece no caminho de room/Type campo. Desta forma, room/Type refere-se ao tipo de sala atual no documento atual. Este é um único exemplo do Type sub-campo, para que possa ser usado diretamente no filtro.

Usando caminhos de campo

Os caminhos de campo são utilizados em muitos parâmetros das APIs de Repouso cognitivo Azure. A tabela que se segue lista todos os locais onde podem ser utilizados, além de quaisquer restrições à sua utilização:

Constantes

As constantes no OData são valores literais de um determinado modelo de dados da entidade (EDM). Consulte os tipos de dados suportados para uma lista de tipos suportados na Pesquisa Cognitiva Azure. As constantes dos tipos de recolha não são suportadas.

A tabela a seguir mostra exemplos de constantes para cada um dos tipos de dados suportados pela Azure Cognitive Search:

Escapando de personagens especiais em constantes de cordas

As constantes de cordas no OData são delimitadas por citações únicas. Se precisar de construir uma consulta com uma constante de corda que possa conter citações individuais, pode escapar às citações incorporadas duplicando-as.

Por exemplo, uma frase com um apóstrofo nãoformado como "O carro de Alice" seria representada no OData como a constante de cordas 'Alice''s car' .

Sintaxe de constantes

O seguinte EBNF (Formulário Backus-Naur Alargado)define a gramática para a maioria das constantes mostradas na tabela acima. A gramática para tipos geo-espaciais pode ser encontrada em funções geo-espaciais OData em 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'

Está também disponível um diagrama de sintaxe interativo:

Construindo expressões de caminhos de campo e constantes

Os caminhos de campo e as constantes são a parte mais básica de uma expressão OData, mas já são expressões completas. Na verdade, o parâmetro $select na Pesquisa Cognitiva de Azure não passa de uma lista separada por vírgulas de caminhos de campo, e $orderby não é muito mais complicado do que $select. Se por acaso tiver um campo de tipo Edm.Boolean no seu índice, pode até escrever um filtro que não passa do caminho desse campo. As constantes true e false são igualmente filtros válidos.

No entanto, a maior parte do tempo você precisará de expressões mais complexas que se referem a mais de um campo e constante. Estas expressões são construídas de diferentes formas dependendo do parâmetro.

O seguinte EBNF (Formulário Backus-Naur Alargado)define a gramática para os parâmetros $filter, $orderby e $select. Estas são construídas a partir de expressões mais simples que se referem a caminhos de campo e constantes:

filter_expression ::= boolean_expression

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

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

Está também disponível um diagrama de sintaxe interativo:

Os parâmetros $orderby e $select são ambas listas separadas por vírgulas de expressões mais simples. O parâmetro $filter é uma expressão booleana que é composta por subexpressões mais simples. Estas subexpressões são combinadas com operadores lógicos and or como, e, not operadores de comparação eq lt como, e assim por gt diante,e operadores de recolha como any e all .

Os $filter, $orderby e $select parâmetros são explorados mais detalhadamente nos seguintes artigos:

• OData $filter sintaxe na Pesquisa Cognitiva de Azure
• OData $orderby sintaxe na Pesquisa Cognitiva de Azure
• OData $select sintaxe na pesquisa cognitiva de Azure

Ver também

• Navegação facetada em Pesquisa Cognitiva Azure
• Filtros em Pesquisa Cognitiva Azure
• Documentos de pesquisa (Azure Cognitive Search REST API)
• Sintaxe de consulta Lucene
• Sintaxe de consulta simples na Pesquisa Cognitiva Azure