Compartilhar via

Sintaxe de $filter do OData na Pesquisa de IA do Azure

  • Artigo

Na Pesquisa de IA do Azure, 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.

As constantes e a construção de caminho de campo são descritas na Visão geral da linguagem OData na Pesquisa de IA do Azure. Para obter mais informações sobre cenários de filtros, confira Filtros na Pesquisa de IA do Azure.

Sintaxe

Um filtro na linguagem OData é uma expressão booliana que, por sua vez, pode ser um dos vários tipos de expressão, conforme mostrado pelo seguinte EBNF (Formulário estendido Backus-Naur):

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 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 Pesquisa de IA do Azure para ver a EBNF completa.

Os tipos de expressões boolianas incluem:

  • Expressões de filtro de coleção usando any ou all. Elas aplicam critérios de filtro aos campos de coleção. Para obter mais informações, confira Operadores de coleção OData na Pesquisa de IA do Azure.
  • Expressões lógicas que combinam outras expressões boolianas usando os operadores and, or e not. Para obter mais informações, confira Operadores de coleção OData na Pesquisa de IA do Azure.
  • Expressões de comparação, que comparam campos ou variáveis de intervalo a valores constantes usando operadores eq, ne, gt, lt, ge e le. Para obter mais informações, confira Operadores de coleção OData na Pesquisa de IA do Azure. As expressões de comparação também são usadas para comparar distâncias entre coordenadas geoespaciais usando a função geo.distance. Para obter mais informações, confira Funções geoespaciais OData na Pesquisa de IA do Azure.
  • Literais boolianos true ou false. Essas constantes podem ser úteis às vezes ao gerar filtros programaticamente. Caso contrário, não tendem a ser usadas na prática.
  • Chamadas para funções boolianas, incluindo:
  • Caminhos de campo ou variáveis de intervalo do tipo Edm.Boolean. Por exemplo, se o índice tiver um campo booliano chamado IsEnabled e você desejar retornar todos os documentos em que esse campo é true, a expressão de filtro poderá ser apenas o nome IsEnabled.
  • Expressões boolianas 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, veja a próxima seção.

Precedência do operador nos filtros

Se você escrever uma expressão de filtro sem parênteses nas sub-expressões, a Pesquisa de IA do Azure a avalia de acordo com um conjunto de regras de precedência de operador. Essas regras são baseadas nos operadores que costumam combinar sub-expressões. A tabela a seguir lista grupos de operadores na ordem da precedência mais alta para a mais baixa:

Grupo Operadores
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 é superior na tabela acima será “associado de maneira mais rígida” a seus operandos do que outros operadores. Por exemplo, and tem maior precedência do que or, e os operadores de comparação têm precedência mais alta do que qualquer um deles, portanto, 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 operador not tem a maior precedência de todos – ainda mais do que os operadores de comparação. É por isso que, se você tentar gravar um filtro como este:

    not Rating gt 5

Você receberá a seguinte mensagem de erro:

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

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

    not (Rating gt 5)

Limitações de tamanho de filtro

Há limites para o tamanho e a complexidade de expressões de filtro que você pode enviar para a Pesquisa de IA do Azure. Os limites se baseiam aproximadamente no número de cláusulas na sua expressão de filtro. Uma boa diretriz é que, se você tiver centenas de cláusulas, você correrá o risco de exceder o limite. É recomendável criar o aplicativo de forma que ele não gere filtros de tamanho ilimitado.

Dica

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

Exemplos

Localizar todos os hotéis com, pelo menos, um quarto e taxa base menor que US$ 200, com classificação igual ou superior a 4:

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

Localizar todos os hotéis que foram renovados desde 2010 e que não sejam o “Sea View Motel”:

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

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

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

Encontrar todos os hotéis que tenham estacionamento incluído e onde todos os quartos sejam para não fumantes:

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

- OU -

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

Localizar todos os hotéis marcados como Luxo ou que incluem estacionamento e têm uma classificação de 5:

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

Encontrar todos os hotéis com a marca “WiFi” em pelo menos um quarto (onde cada quarto tenha marcas armazenadas em um campo Collection(Edm.String)):

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

Encontrar todos os hotéis que tenham quartos:

    $filter=Rooms/any()

Encontrar todos os hotéis que não tenham quartos:

    $filter=not Rooms/any()

Encontrar todos os hotéis em um raio de 10 km de determinado ponto de referência (em que Location é um campo do tipo Edm.GeographyPoint):

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

Encontrar todos os hotéis dentro de determinado visor descrito como um polígono (em que Location é um campo do tipo Edm.GeographyPoint). O polígono precisa estar fechado, o que significa que os conjuntos do primeiro e último pontos devem ser os mesmos. Além disso, os pontos devem estar listados em ordem no sentido 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))')

Encontrar todos os hotéis em que o campo “Descrição” for nulo. O campo será nulo se nunca tiver sido definido ou se tiver sido definido explicitamente como nulo:

    $filter=Description eq null

Encontrar todos os hotéis com o 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 outro delimitador entre aspas simples como o terceiro parâmetro de cadeia de caracteres:

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

Encontrar 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', '|')

Encontrar todos os hotéis em que todos os quartos tenham a marca “wifi” ou “tub”:

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

Localizar uma correspondência nas frases de uma coleção, como "heated towel racks" ou "hairdryer included" em marcas.

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

Localizar documentos com as palavras "orla marítima". Essa consulta de filtro é idêntica a uma solicitação de pesquisa com search=waterfront.

    $filter=search.ismatchscoring('waterfront')

Localizar 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. Não foi possível expressar essa solicitação sem a função search.ismatchscoring, pois ela combina a 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

Localizar documentos sem a palavra "luxo".

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

Localizar documentos com a frase "vista para o mar" ou classificação igual a 5. A consulta search.ismatchscoring será executada apenas em relação aos campos HotelName e Description. Os documentos que corresponderam apenas à segunda cláusula da disjunção também serão retornados: hotéis com Rating igual a 5. Esses documentos retornarão com uma pontuação igual a zero para deixar claro que eles não corresponderam a nenhuma parte classificada da expressão.

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

Encontrar hotéis em que os termos “hotel” e “aeroporto” não têm mais do que cinco palavras de diferença na descrição e onde todos os quartos são para não fumantes. Essa 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. Essa consulta usa a pesquisa de prefixo em combinação com search.ismatch.

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

Próximas etapas