Função search.in do OData no Azure AI Search

  • Artigo

Um cenário comum em expressões de filtro do OData é verificar se um campo em cada documento é igual a um dos muitos valores possíveis. Por exemplo, é assim que alguns aplicativos implementam a restrição de segurança: comparando um campo que contém uma ou mais IDs de entidade a uma lista de IDs de entidade que representam o usuário que fez a consulta. Uma forma de escrever uma consulta como essa é usar os operadores eq e or:

    group_ids/any(g: g eq '123' or g eq '456' or g eq '789')

No entanto, há uma forma mais curta de escrever isso usando a função search.in:

    group_ids/any(g: search.in(g, '123, 456, 789'))

Importante

Além de ser mais curto e fácil de ler, search.in também melhora o desempenho e evita certas limitações no tamanho de filtros quando há centenas ou milhares de valores para incluir no filtro. Por isso, recomendamos usar search.in em vez de um conjunto complexo e confuso de expressões de igualdade.

Observação

Recentemente, a versão 4.01 do padrão do OData lançou o operador in, que tem comportamento semelhante ao da função search.in do Azure AI Search. No entanto, o Azure AI Search não dá suporte para esse operador, portanto, você deve usar a função search.in.

Sintaxe

O seguinte EBNF (formulário estendido Backus-Naur) define a gramática da função search.in:

search_in_call ::=
    'search.in(' variable ',' string_literal(',' string_literal)? ')'

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.

A função search.in testa se um determinado campo de cadeia de caracteres ou variável de intervalo é igual a um de uma determinada lista de valores. A igualdade entre a variável e cada valor na lista é determinada de maneira a diferenciar maiúsculas de minúsculas, da mesma forma que para o operador eq. Portanto, uma expressão como search.in(myfield, 'a, b, c') é equivalente a myfield eq 'a' or myfield eq 'b' or myfield eq 'c', exceto que search.in produzirá um desempenho muito melhor.

Há duas sobrecargas da função search.in:

  • search.in(variable, valueList)
  • search.in(variable, valueList, delimiters)

A tabela abaixo contém os parâmetros:

Nome do parâmetro Tipo Descrição
variable Edm.String Uma referência de campo de cadeia de caracteres (ou uma variável de intervalo em um campo de coleção de cadeia de caracteres no caso em que search.in é usado dentro de uma expressão any ou all).
valueList Edm.String Uma cadeia de caracteres que contém uma lista delimitada de valores para corresponder ao parâmetro variable. Se o parâmetro delimiters não for especificado, os delimitadores padrão serão espaço e vírgula.
delimiters Edm.String Uma cadeia de caracteres em que cada caractere é tratado como um separador ao analisar o parâmetro valueList. O valor padrão do parâmetro é ' ,' que significa que todos os valores com espaços e/ou vírgulas entre eles serão separados. Se você precisar usar separadores diferentes de espaços e vírgulas porque os valores incluem esses caracteres, especifique outros delimitadores como '|' no parâmetro.

Desempenho de search.in

Se você usar search.in, espere um tempo de resposta abaixo de um segundo quando o segundo parâmetro contiver uma lista de centenas ou milhares de valores. Não há limite explícito ao número de itens que você pode passar para search.in, embora o tamanho máximo de solicitação ainda se aplique. No entanto, a latência aumenta à medida em que cresce o número de valores.

Exemplos

Localizar todos os hotéis com o nome igual a "Sea View motel" ou "Budget hotel". As frases contêm espaços, que é um delimitador padrão. Você pode especificar outro delimitador entre aspas simples como o terceiro parâmetro de cadeia de caracteres:

    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 “|”):

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

Localizar todos os hotéis com quartos que têm a marca "wifi" ou "tub":

    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.

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

Localizar todos os hotéis sem as marcas “motel” ou “cabin”:

    Tags/all(tag: not search.in(tag, 'motel, cabin'))

Próximas etapas