Operadores de comparação OData no Azure IA Search – eq, ne, gt, lt, ge e le

  • Artigo

A operação mais básica em uma expressão de filtro OData no Azure IA Search é comparar um campo com um determinado valor. Dois tipos de comparação são possíveis – comparação de igualdade e comparação de intervalo. Use os seguintes operadores para comparar um campo com um valor constante:

Operadores de igualdade:

  • eq: teste se um campo é igual a um valor constante
  • ne: teste se um campo é diferente de um valor constante

Operadores de intervalo:

  • gt: teste se um campo é maior que um valor constante
  • lt: teste se um campo é menor que um valor constante
  • ge: teste se um campo é superior ou igual a um valor constante
  • le: teste se um campo é inferior ou igual a um valor constante

Você pode usar os operadores de intervalo em combinação com os operadores lógicos para testar se um campo está dentro de um determinado intervalo de valores. Consulte os exemplos mais adiante neste artigo.

Observação

Se preferir, você pode colocar o valor constante no lado esquerdo do operador e o nome do campo no lado direito. Para operadores de intervalo, o significado da comparação é invertido. Por exemplo, se o valor constante estiver à esquerda, o gt testará se o valor constante é maior que o campo. Você também pode usar os operadores de comparação para comparar o resultado de uma função, como geo.distance, com um valor. Para funções booleanas como search.ismatch, comparar o resultado com true ou false é opcional.

Sintaxe

A EBNF (forma estendida de Backus-Naur) a seguir define a gramática de uma expressão OData que usa operadores de comparação.

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'

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

Diagrama de sintaxe OData para Azure AI Search

Observação

Confira Referência de sintaxe de expressão OData para Azure AI Search para ver a EBNF completa.

Há duas formas de expressões de comparação. A única diferença entre eles é se a constante aparece no lado esquerdo ou direito do operador. A expressão no outro lado do operador deve ser uma variável ou uma chamada de função. Uma variável pode ser um nome de campo ou uma variável de intervalo no caso de uma expressão lambda.

Tipos de dados para comparações

Os tipos de dados em ambos os lados de um operador de comparação devem ser compatíveis. Por exemplo, se o lado esquerdo é um campo do tipo Edm.DateTimeOffset, o lado direito deve ser uma constante de data e hora. Os tipos de dados numéricos são mais flexíveis. Você pode comparar variáveis e funções de qualquer tipo numérico com constantes de qualquer outro tipo numérico, com algumas limitações, conforme descrito na tabela a seguir.

Variável ou tipo de função Tipo de valor constante Limitações
Edm.Double Edm.Double A comparação está sujeita a regras especiais para NaN
Edm.Double Edm.Int64 Constante é convertida em Edm.Double, resultando em uma perda de precisão para valores de magnitude grande
Edm.Double Edm.Int32 N/D
Edm.Int64 Edm.Double Comparações com NaN, -INF ou INF não são permitidas
Edm.Int64 Edm.Int64 N/D
Edm.Int64 Edm.Int32 A constante é convertida em Edm.Int64 antes da comparação
Edm.Int32 Edm.Double Comparações com NaN, -INF ou INF não são permitidas
Edm.Int32 Edm.Int64 N/D
Edm.Int32 Edm.Int32 N/D

Para comparações que não são permitidas, como comparar um campo do tipo Edm.Int64 com NaN, a API REST do Azure IA Search retornará um erro "HTTP 400: Solicitação Ruim".

Importante

Embora as comparações de tipo numérico sejam flexíveis, é altamente recomendável escrever comparações em filtros para que o valor constante seja do mesmo tipo de dados que a variável ou função à qual ele está sendo comparado. Isso é especialmente importante ao misturar valores de ponto flutuante e inteiro, em que conversões implícitas que perdem precisão são possíveis.

Casos especiais de null e NaN

Ao usar operadores de comparação, é importante lembrar que todos os campos que não são de coleção no Azure IA Search podem ser null. A tabela a seguir mostra todos os resultados possíveis para uma expressão de comparação em que um dos lados pode ser null:

Operador Resultado quando apenas o campo ou variável é null Resultado quando apenas a constante é null Resultado quando o campo ou variável e a constante são null
gt false HTTP 400: de solicitação ruim HTTP 400: de solicitação ruim
lt false HTTP 400: de solicitação ruim HTTP 400: de solicitação ruim
ge false HTTP 400: de solicitação ruim HTTP 400: de solicitação ruim
le false HTTP 400: de solicitação ruim HTTP 400: de solicitação ruim
eq false false true
ne true true false

Em resumo, null é igual apenas a si mesmo e não é menor ou maior que qualquer outro valor.

Se o índice tiver campos do tipo Edm.Double e você carregar valores NaN nesses campos, você precisará levar em conta isso ao gravar filtros. O Azure IA Search implementa o padrão IEEE 754 para manipular valores NaN, e comparações com esses valores produzem resultados não óbvios, conforme mostrado na tabela a seguir.

Operador Resultado quando pelo menos um operando for NaN
gt false
lt false
ge false
le false
eq false
ne true

Em resumo, NaN não é igual a qualquer valor, incluindo a si mesmo.

Comparando dados geoespaciais

Não é possível comparar diretamente um campo do tipo Edm.GeographyPoint com um valor constante, mas você pode usar a função geo.distance. Essa função retorna um valor do tipo Edm.Double, de modo que você pode compará-lo com uma constante numérica para filtrar com base na distância das coordenadas geoespaciais constantes. Confira os exemplos abaixo.

Comparar dados de cadeia de caracteres

As cadeias de caracteres podem ser comparadas em filtros para correspondências exatas usando os operadores eq e ne. Essas comparações diferenciam maiúsculas de minúsculas.

Exemplos

Corresponder documentos em que o campo Rating está entre 3 e 5, inclusive:

Rating ge 3 and Rating le 5

Corresponder documentos em que o campo Location é inferior a 2 quilômetros da latitude e longitude determinada:

geo.distance(Location, geography'POINT(-122.031577 47.578581)') lt 2.0

Corresponder documentos em que o campo LastRenovationDate é maior ou igual a 1 de janeiro de 2015, meia-noite UTC:

LastRenovationDate ge 2015-01-01T00:00:00.000Z

Corresponder documentos em que o campo Details/Sku não é null:

Details/Sku ne null

Corresponder documentos para hotéis em que pelo menos uma sala tem o tipo "sala de luxo", em que a cadeia de caracteres do campo Rooms/Type corresponde exatamente ao filtro:

Rooms/any(room: room/Type eq 'Deluxe Room')

Próximas etapas