Função search.in do OData no Azure AI Search
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:
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'))