Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Visão geral da linguagem OData para
Nota
Foundry IQ (Pesquisa de IA do Azure) fornece APIs de indexação direta e de consulta, juntamente com APIs de fonte de conhecimento e de base de conhecimento de nível mais elevado para recuperação gerida. Utilize o portal do Azure, APIs REST ou SDKs do Azure para configurar estas capacidades, ou ligue agentes a bases de conhecimento no portal Microsoft Foundry.
Este artigo apresenta uma visão geral da linguagem de expressões OData utilizada em expressões $filter, $order-by e $select para pesquisa por palavras-chave no Foundry IQ (Pesquisa de IA do Azure) sobre campos numéricos e de cadeia de carateres (não vetoriais).
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 partilhados incluem:
- Caminhos de campos, que se referem a campos específicos do seu índice.
- Constantes, que são valores literais de um determinado tipo de dados.
Depois de entender esses conceitos comuns, você pode continuar com a sintaxe de nível superior para cada expressão:
- $filter expressões são avaliadas durante a análise sintática da consulta, restringindo a pesquisa a campos específicos ou adicionando critérios de correspondência usados durante os varrimentos do índice.
- $orderby as expressões são aplicadas como etapa de pós-processamento sobre um conjunto de resultados para ordenar os documentos que são devolvidos.
- $select As expressões determinam quais os campos do documento que 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 alguma sobreposição na sintaxe para referenciar campos.
Para obter exemplos em outras linguagens, como Python ou C#, consulte os exemplos no repositório azure-search-vector-samples .
Nota
A terminologia no Foundry IQ difere do padrão OData em alguns aspetos. O que chamamos de campo em Foundry IQ é chamado de propriedade em OData, e de forma semelhante para caminho de campo versus caminho de propriedade. Um índice que contém documentos no Foundry IQ é designado, de forma mais geral, em OData, como um conjunto de entidades que contém entidades. A terminologia Foundry IQ é utilizada ao longo desta referência.
Caminhos de campo
O seguinte EBNF (Extended Backus-Naur Form) 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 interativo também está disponível:
Nota
Consulte a referência da sintaxe de expressões OData para Foundry IQ para o EBNF completo.
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 ou sublinhado ASCII 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 intervalo no contexto de uma expressão de coleção (any ou all) em um filtro. Uma variável range é como uma variável de loop que representa o elemento atual da coleção. Para coleções complexas, essa variável representa um objeto, e é por isso que você pode usar caminhos de campo para se referir a subcampos da variável. Isto é análogo à notação de pontos em muitas linguagens de programação.
Exemplos de caminhos de campo são mostrados na tabela a seguir:
| Caminho do campo | Descrição |
|---|---|
HotelName |
Refere-se a um campo de nível superior do índice |
Address/City |
Refere-se ao City subcampo de um campo complexo no índice; Address é do tipo Edm.ComplexType neste exemplo |
Rooms/Type |
Refere-se ao Type subcampo de um campo de coleção complexo no índice; Rooms é do tipo Collection(Edm.ComplexType) neste exemplo |
Stores/Address/Country |
Refere-se ao Country subcampo do Address subcampo de um campo de coleção complexo no índice; Stores é do tipo Collection(Edm.ComplexType) e Address é do tipo Edm.ComplexType neste exemplo |
room/Type |
Refere-se ao Type subcampo da room variável de intervalo, por exemplo, na expressão de filtro Rooms/any(room: room/Type eq 'deluxe') |
store/Address/Country |
Refere-se ao Country subcampo do Address subcampo da store variável de intervalo, por exemplo, na expressão de filtro Stores/any(store: store/Address/Country eq 'Canada') |
O significado de um caminho de campo difere dependendo do contexto. Em 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 campos utilizando a sintaxe completa do Lucene, um caminho de campo refere-se ao campo em questão. Essa diferença tem algumas consequências sobre como você usa caminhos de campo em filtros.
Considere o caminho do campo Address/City. Em um filtro, isso se refere a uma única cidade para o documento atual, como "São Francisco". Em contraste, Rooms/Type refere-se ao Type subcampo para muitos quartos (como "standard" para o primeiro quarto, "deluxe" para o segundo quarto, e assim por diante). Como Rooms/Type não se refere a uma única instância do subcampo Type, ele não pode ser usado diretamente em um filtro. Em vez disso, para filtrar por tipo de quarto, você usaria uma expressão lambda com uma variável de intervalo, como esta:
Rooms/any(room: room/Type eq 'deluxe')
Neste exemplo, a variável de intervalo room aparece no campo room/Type. Dessa forma, room/Type refere-se ao tipo de sala atual no documento atual. Esta é uma única instância do Type subcampo, por isso pode ser usada diretamente no filtro.
Usando caminhos de campo
Os caminhos de campo são usados em muitos parâmetros das APIs REST do Foundry IQ. A tabela a seguir lista todos os locais onde eles podem ser usados, além de quaisquer restrições sobre seu uso:
| API | Nome do parâmetro | Restrições |
|---|---|---|
| Criar ou Atualizar Índice | suggesters/sourceFields |
Nenhuma |
| Criar ou Actualizar índice | scoringProfiles/text/weights |
Só pode referir-se a campos pesquisáveis |
| Criar ou Actualizar o Índice | scoringProfiles/functions/fieldName |
Só pode referir-se a campos filtráveis |
| Procurar |
search quando queryType é full |
Só pode referir-se a campos pesquisáveis |
| Procurar | facet |
Só pode referir-se a campos facetable |
| Procurar | highlight |
Só pode referir-se a campos pesquisáveis |
| Procurar | searchFields |
Só pode referir-se a campos pesquisáveis |
| Suggest e Autocomplete | searchFields |
Só pode referir-se a campos que fazem parte de um sugestionador |
| Pesquisar, sugerir e completar automaticamente | $filter |
Só pode referir-se a campos filtráveis |
| Pesquisa e Sugestão | $orderby |
Só pode referir-se a campos classificáveis |
| Pesquisar, Sugerir e Consulta | $select |
Só pode referir-se a campos recuperáveis |
Constantes
As constantes em OData são valores literais de um determinado tipo de Modelo de Dados de Entidade (EDM). Consulte Tipos de dados suportados para uma lista dos tipos suportados no Foundry IQ. Não há suporte para constantes de tipos de coleção.
A tabela a seguir mostra exemplos de constantes para cada um dos tipos de dados não vetoriais que oferecem suporte a expressões OData:
| Tipo de dados | Constantes de exemplo |
|---|---|
Edm.Boolean |
true, false |
Edm.DateTimeOffset |
2019-05-06T12:30:05.451Z |
Edm.Double |
3.14159, -1.2e7, NaN, INF, -INF |
Edm.GeographyPoint |
geography'POINT(-122.131577 47.678581)' |
Edm.GeographyPolygon |
geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))' |
Edm.Int32 |
123, -456 |
Edm.Int64 |
283032927235 |
Edm.String |
'hello' |
Escapando de caracteres especiais em constantes de cadeia de caracteres
As constantes de cadeia de caracteres no OData são delimitadas por aspas simples. Se você precisar construir uma consulta com uma constante de cadeia de caracteres que possa conter aspas simples, poderá escapar das aspas incorporadas duplicando-as.
Por exemplo, uma frase com um apóstrofo não formatado como "carro d'Alice" seria representada em OData como a constante de cadeia de caracteres 'Alice''s car'.
Importante
Ao construir filtros programaticamente, é importante lembrar de escapar das constantes de cadeia de caracteres que vêm da entrada do usuário. Isso é para mitigar a possibilidade de ataques de injeção, especialmente ao usar filtros para implementar recorte de segurança.
Sintaxe das constantes
O seguinte EBNF (Extended Backus-Naur Form) define a gramática para a maioria das constantes mostradas na tabela acima. A gramática para tipos geoespaciais pode ser encontrada em funções geoespaciais OData em Foundry IQ.
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 interativo também está disponível:
Nota
Consulte a referência sintáctica da expressão OData para o Foundry IQ para o EBNF completo.
Criando expressões a partir de caminhos de campo e constantes
Caminhos de campo e constantes são a parte mais básica de uma expressão OData, mas eles já são expressões completas. Na verdade, o parâmetro $select no Foundry IQ 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 acontecer de você ter um campo do tipo Edm.Boolean em seu índice, você pode até escrever um filtro que nada mais é do que o caminho desse campo. As constantes true e false são igualmente filtros válidos.
No entanto, é mais comum ter expressões complexas que se referem a mais de um campo e constante. Essas expressões são construídas de maneiras diferentes, dependendo do parâmetro.
O seguinte EBNF (Extended Backus-Naur Form) define a gramática para os parâmetros $filter, $orderby e $select . Estes são construídos 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)*
Um diagrama de sintaxe interativo também está disponível:
Nota
Consulte a referência sintáctica da expressão OData para o Foundry IQ para o EBNF completo.
Próximos passos
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 booleana que é composta de subexpressões mais simples. Essas subexpressões são combinadas usando operadores lógicos como and, ore not, operadores de comparação como eq, lt, gt, e assim por diante, e operadores de coleta como any e all.
Os parâmetros $filter, $orderby e $select são explorados mais detalhadamente nos seguintes artigos: