Sintaxe $filter OData na Pesquisa de IA do Azure

  • Artigo

No Azure AI Search, o parâmetro $filter especifica critérios de inclusão ou exclusão para retornar correspondências nos resultados da pesquisa. Este artigo descreve a sintaxe OData de $filter e fornece exemplos.

A construção e as constantes do caminho de campo são descritas na visão geral da linguagem OData no Azure AI Search. Para obter mais informações sobre cenários de filtro, consulte Filtros no Azure AI Search.

Sintaxe

Um filtro na linguagem OData é uma expressão booleana, que por sua vez pode ser um dos vários tipos de expressão, como mostrado pelo seguinte EBNF (Extended Backus-Naur Form):

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

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

Diagrama de sintaxe OData para Azure AI Search

Nota

Consulte Referência de sintaxe de expressão OData para Azure AI Search para obter o EBNF completo.

Os tipos de expressões booleanas incluem:

  • Expressões de filtro de coleção usando any ou all. Estes aplicam critérios de filtro aos campos de recolha. Para obter mais informações, consulte Operadores de coleção OData no Azure AI Search.
  • Expressões lógicas que combinam outras expressões booleanas usando os operadores and, , ore not. Para obter mais informações, consulte Operadores lógicos OData no Azure AI Search.
  • Expressões de comparação, que comparam campos ou variáveis de intervalo com valores constantes usando os operadores eq, , , , , ltgenegte .le Para obter mais informações, consulte Operadores de comparação OData no Azure AI Search. Expressões de comparação também são usadas para comparar distâncias entre coordenadas geoespaciais usando a geo.distance função. Para obter mais informações, consulte Funções geoespaciais OData no Azure AI Search.
  • Os literais true booleanos e false. Essas constantes podem ser úteis às vezes ao gerar filtros programaticamente, mas de outra forma não tendem a ser usadas na prática.
  • Chamadas para funções booleanas, incluindo:
  • Caminhos de campo ou variáveis de intervalo do tipo Edm.Boolean. Por exemplo, se o seu índice tem um campo booleano chamado IsEnabled e você deseja retornar todos os documentos onde esse campo está true, sua expressão de filtro pode ser apenas o nome IsEnabled.
  • Expressões booleanas entre parênteses. O uso de parênteses pode ajudar a determinar explicitamente a ordem das operações em um filtro. Para obter mais informações sobre a precedência padrão dos operadores OData, consulte a próxima seção.

Precedência do operador nos filtros

Se você escrever uma expressão de filtro sem parênteses em torno de suas subexpressões, o Azure AI Search a avaliará de acordo com um conjunto de regras de precedência do operador. Essas regras são baseadas em quais operadores são usados para combinar subexpressões. A tabela a seguir lista os grupos de operadores em ordem da maior para a menor precedência:

Agrupar Operador(es)
Operadores lógicos not
Operadores de comparação eq, ne, gt, lt, ge, le
Operadores lógicos and
Operadores lógicos or

Um operador que é mais alto na tabela acima irá "ligar mais fortemente" aos seus operandos do que outros operadores. Por exemplo, é de maior precedência do que , e os operadores de comparação são de maior precedência do que orqualquer um deles, portanto, and as duas expressões a seguir são equivalentes:

    Rating gt 0 and Rating lt 3 or Rating gt 7 and Rating lt 10
    ((Rating gt 0) and (Rating lt 3)) or ((Rating gt 7) and (Rating lt 10))

O not operador tem a maior precedência de todos - ainda maior do que os operadores de comparação. É por isso que se você tentar escrever um filtro como este:

    not Rating gt 5

Você receberá esta mensagem de erro:

    Invalid expression: A unary operator with an incompatible type was detected. Found operand type 'Edm.Int32' for operator kind 'Not'.

Este erro acontece porque o operador está associado apenas ao Rating campo, que é do tipo Edm.Int32, e não a toda a expressão de comparação. A correção é colocar o operando de not entre parênteses:

    not (Rating gt 5)

Limitações de tamanho do filtro

Há limites para o tamanho e a complexidade das expressões de filtro que você pode enviar para o Azure AI Search. Os limites são baseados aproximadamente no número de cláusulas em sua expressão de filtro. Uma boa orientação é que, se você tiver centenas de cláusulas, corre o risco de exceder o limite. Recomendamos projetar seu aplicativo de tal forma que ele não gere filtros de tamanho ilimitado.

Gorjeta

Usar a função em vez de longas disjunções de comparações de igualdade pode ajudar a search.in evitar o limite da cláusula de filtro, uma vez que uma chamada de função conta como uma única cláusula.

Exemplos

Encontre todos os hotéis com pelo menos um quarto com uma tarifa base inferior a $200 com classificação igual ou superior a 4:

    $filter=Rooms/any(room: room/BaseRate lt 200.0) and Rating ge 4

Encontre todos os hotéis além de "Sea View Motel" que foram renovados desde 2010:

    $filter=HotelName ne 'Sea View Motel' and LastRenovationDate ge 2010-01-01T00:00:00Z

Encontre todos os hotéis que foram renovados em 2010 ou posterior. O literal datetime inclui informações de fuso horário para a Hora Padrão do Pacífico:

    $filter=LastRenovationDate ge 2010-01-01T00:00:00-08:00

Encontre todos os hotéis que têm estacionamento incluído e onde todos os quartos são para não fumadores:

    $filter=ParkingIncluded and Rooms/all(room: not room/SmokingAllowed)

- OU -

    $filter=ParkingIncluded eq true and Rooms/all(room: room/SmokingAllowed eq false)

Encontre todos os hotéis que são de luxo ou incluem estacionamento e têm uma classificação de 5:

    $filter=(Category eq 'Luxury' or ParkingIncluded eq true) and Rating eq 5

Encontre todos os hotéis com a tag "wifi" em pelo menos um quarto (onde cada quarto tem tags armazenadas em um Collection(Edm.String) campo):

    $filter=Rooms/any(room: room/Tags/any(tag: tag eq 'wifi'))

Encontre todos os hotéis com qualquer quarto:

    $filter=Rooms/any()

Encontre todos os hotéis que não têm quartos:

    $filter=not Rooms/any()

Encontre todos os hotéis a menos de 10 km de um determinado ponto de referência (onde Location está um campo do tipo Edm.GeographyPoint):

    $filter=geo.distance(Location, geography'POINT(-122.131577 47.678581)') le 10

Encontre todos os hotéis dentro de um determinado visor descrito como um polígono (onde Location é um campo do tipo Edm.GeographyPoint). O polígono deve ser fechado, o que significa que o primeiro e o último conjuntos de pontos devem ser os mesmos. Além disso, os pontos devem ser listados em ordem anti-horário.

    $filter=geo.intersects(Location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')

Encontre todos os hotéis onde o campo "Descrição" é nulo. O campo será nulo se nunca tiver sido definido ou se tiver sido explicitamente definido como nulo:

    $filter=Description eq null

Encontre todos os hotéis com nome igual a 'Sea View motel' ou 'Budget hotel'). Essas frases contêm espaços e o espaço é um delimitador padrão. Você pode especificar um delimitador alternativo entre aspas simples como o terceiro parâmetro de cadeia de caracteres:

    $filter=search.in(HotelName, 'Sea View motel,Budget hotel', ',')

Encontre todos os hotéis com nome igual a 'Sea View motel' ou 'Budget hotel' separados por '|'):

    $filter=search.in(HotelName, 'Sea View motel|Budget hotel', '|')

Encontre todos os hotéis onde todos os quartos têm a tag 'wifi' ou 'banheira':

    $filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))

Encontre uma correspondência em frases de uma coleção, como "toalheiros aquecidos" ou "secador de cabelo incluído" nas etiquetas.

    $filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))

Encontre documentos com a palavra "beira-mar". Esta consulta de filtro é idêntica a uma solicitação de pesquisa com search=waterfront.

    $filter=search.ismatchscoring('waterfront')

Encontre documentos com a palavra "hostel" e classificação maior ou igual a 4, ou documentos com a palavra "motel" e classificação igual a 5. Essa solicitação não poderia ser expressa sem a função, search.ismatchscoring pois combina pesquisa de texto completo com operações de filtro usando or.

    $filter=search.ismatchscoring('hostel') and rating ge 4 or search.ismatchscoring('motel') and rating eq 5

Encontre documentos sem a palavra "luxo".

    $filter=not search.ismatch('luxury')

Encontre documentos com a frase "vista para o mar" ou classificação igual a 5. A search.ismatchscoring consulta será executada apenas em campos HotelName e Description. Documentos que correspondam apenas à segunda cláusula da disjunção também serão devolvidos - hotéis com Rating igual a 5. Esses documentos serão devolvidos com pontuação igual a zero para deixar claro que não corresponderam a nenhuma das partes pontuadas da expressão.

    $filter=search.ismatchscoring('"ocean view"', 'Description,HotelName') or Rating eq 5

Encontre hotéis onde os termos "hotel" e "aeroporto" não estão separados por mais de cinco palavras na descrição e onde todos os quartos são para não fumadores. Esta consulta usa a linguagem de consulta Lucene completa.

    $filter=search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and not Rooms/any(room: room/SmokingAllowed)

Encontre documentos que tenham uma palavra que comece com as letras "lux" no campo Descrição. Esta consulta usa a pesquisa de prefixo em combinação com search.ismatcho .

    $filter=search.ismatch('lux*', 'Description')

Próximos passos