Visão geral da linguagem OData para $filter, $orderby e $select na IA do Azure Search

Este artigo fornece uma visão geral da linguagem de expressão OData usada em expressões $filter, $order-bye $select para pesquisa de palavras-chave na Pesquisa de IA do Azure em campos numéricos e de cadeia de caracteres (não vetor).

A linguagem é apresentada "de baixo para cima", começando com os elementos mais básicos. As expressões OData que você pode construir em uma solicitação de consulta variam de simples a altamente complexas, mas todas elas compartilham elementos comuns. Os elementos compartilhados incluem:

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

Depois de entender esses conceitos comuns, você poderá continuar com a sintaxe de nível superior para cada expressão:

• As expressões $filter são avaliadas durante a análise da consulta, restringindo a pesquisa a campos específicos ou adicionando critérios de correspondência usados durante as verificações de índice.
• As expressões $orderby são aplicadas como etapa de pós-processamento em um conjunto de resultados para classificar os documentos retornados.
• As expressões $select determinam quais campos de documento são incluídos no conjunto de resultados.

A sintaxe dessas expressões é distinta da sintaxe de consulta simples ou completa usada no parâmetro de pesquisa, embora haja sobreposição na sintaxe para fazer referência a campos.

Para obter exemplos em outras linguagens, como Python ou C#, consulte os exemplos no repositório azure-search-vector-samples.

Caminhos de campo

O EBNF (formulário estendido Backus-Naur) a seguir define a gramática dos caminhos de campo.

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

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

Um diagrama de sintaxe interativa também está disponível:

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

Um identificador pode se referir ao nome de um campo ou a uma variável de intervalo no contexto de uma expressão de coleção (any ou all) em um filtro. Uma variável de intervalo é como uma variável de loop que representa o elemento atual da coleção. Para coleções complexas, essa variável representa um objeto. Por isso, você pode usar caminhos de campo para fazer referência a subcampos da variável. Isso é análogo à notação de ponto em muitas linguagens de programação.

A tabela abaixo contém exemplos de caminhos de campo:

O significado de um caminho de campo difere dependendo do contexto. Em filtros, um caminho de campo refere-se ao valor de uma instância de um campo no documento atual. Em outros contextos, como $orderby, $select ou na pesquisa de campo na sintaxe Lucerne completa, um caminho de campo refere-se ao próprio campo. Essa diferença tem algumas consequências para a forma como você usa caminhos de campo em filtros.

Considere o caminho do campo Address/City. Em um filtro, isso se refere a uma cidade para o documento atual, como "San Francisco". Por outro lado, Rooms/Type se refere ao subcampo Type para vários quartos (como "padrão" no primeiro quarto, "deluxe" no segundo e assim por diante). Como o Rooms/Type não se refere a uma instância do subcampo Type, ele não pode ser usado diretamente em um filtro. Em vez disso, para filtrar o tipo de quarto, você usaria uma expressão lambda com uma variável de intervalo, desta forma:

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

Neste exemplo, a variável de intervalo room aparece no caminho do campo room/Type. Dessa forma, room/Type refere-se ao tipo do quarto atual no documento atual. Essa é uma instância do subcampo Type, portanto, ela pode ser usada diretamente no filtro.

Usar caminhos de campo

Os caminhos de campo são usados em muitos parâmetros das APIs REST da IA do Azure Search. A seguinte tabela mostra todos os locais em que eles podem ser usados, além de eventuais restrições de uso:

Constantes

As constantes no OData são valores literais de um determinado tipo de EDM (Modelo de Dados de Entidade). Confira Tipos de dados com suporte para ver a lista de tipos com suporte na IA do Azure Search. As constantes de tipos de coleção não são compatíveis.

A tabela a seguir mostra exemplos de constantes para cada um dos tipos de dados não vetores que dão suporte a expressões OData:

Caracteres especiais de escape em constantes de cadeia de caracteres

As constantes de cadeia de caracteres no OData são delimitadas por aspas simples. Se você precisar criar uma consulta com uma constante de cadeia de caracteres que contém aspas simples, dobre as aspas integradas para escapá-las.

Por exemplo, uma frase com um apóstrofo não formatado como "Alice's car" seria representada no OData como a constante de cadeia de caracteres 'Alice''s car'.

Sintaxe de constantes

O EBNF (Formulário de Backup Naus Estendido) a seguir define a gramática da maioria das constantes mostradas na tabela acima. A gramática dos tipos geoespaciais pode ser encontrada nas Funções geoespaciais do OData na IA do Azure 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'

Um diagrama de sintaxe interativa também está disponível:

Criar expressões usando caminhos de campo e constantes

Caminhos de campo e constantes são a parte mais básica de uma expressão do OData, mas elas já são próprias expressões completas. Na verdade, o parâmetro $select da IA do Azure Search nada mais é do que uma lista separada por vírgulas de caminhos de campo, e $orderBy não menos complicado do que $select. Se houver um campo do tipo Edm.Boolean no índice, você poderá até mesmo escrever um filtro que seja apenas o caminho do campo. As constantes true e false são filtros válidos da mesma forma.

No entanto, é mais comum ter expressões complexas que se referem a mais de um campo e uma constante. Essas expressões são criadas de maneiras diferentes, dependendo do parâmetro.

O EBNF a seguir (Formulário Backus-Naur Estendido) define a gramática dos parâmetros $filter, $orderBye $Sslect. Eles são criados usando expressões mais simples que se referem a caminhos e constantes de campo:

filter_expression ::= boolean_expression

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

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

Um diagrama de sintaxe interativa também está disponível:

Próximas etapas

Os parâmetros $orderBy e $select são listas separadas por vírgulas de expressões mais simples. O parâmetro $filter é uma expressão booliana composta por subexpressãos mais simples. Essas subexpressãos são combinadas usando operadores lógicos, como and, or e not, operadores de comparação, como eq, lt, gt e assim por diante, bem como operadores de coleção, como any e all.

Os parâmetros $filter, $orderBye $select são analisados com mais detalhes nos seguintes artigos:

• Sintaxe de $filter do OData na IA do Azure Search
• Sintaxe de $orderby do OData na IA do Azure Search
• Sintaxe de $select do OData na IA do Azure Search