Função OData search.in no Azure AI Search
Um cenário comum em expressões de filtro OData é verificar se um único campo em cada documento é igual a um dos muitos valores possíveis. Por exemplo, é assim que alguns aplicativos implementam a filtragem de segurança -- verificando um campo que contém uma ou mais IDs principais em relação a uma lista de IDs principais que representam o usuário que emite a consulta. Uma maneira de escrever uma consulta como esta é usar os eq operadores e or :
group_ids/any(g: g eq '123' or g eq '456' or g eq '789')
No entanto, há uma maneira mais curta de escrever isso, usando a search.in função:
group_ids/any(g: search.in(g, '123, 456, 789'))
Importante
Além de ser mais curto e fácil de ler, o uso search.in também proporciona benefícios de desempenho e evita certas limitações de tamanho dos filtros quando há centenas ou até milhares de valores para incluir no filtro. Por esta razão, recomendamos vivamente o uso search.in de expressões de igualdade, em vez de uma disjunção mais complexa.
Nota
A versão 4.01 do padrão OData introduziu recentemente o in operador, que tem comportamento semelhante à search.in função no Azure AI Search. No entanto, o Azure AI Search não oferece suporte a esse operador, portanto, você deve usar a search.in função.
Sintaxe
O seguinte EBNF (Extended Backus-Naur Form) define a gramática da search.in função:
search_in_call ::=
'search.in(' variable ',' string_literal(',' string_literal)? ')'
Um diagrama de sintaxe interativo também está disponível:
Nota
Consulte Referência de sintaxe de expressão OData para Azure AI Search para obter o EBNF completo.
A search.in função 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 forma sensível a maiúsculas e minúsculas, da mesma forma que para o eq operador. Portanto, uma expressão como search.in(myfield, 'a, b, c') é equivalente a myfield eq 'a' or myfield eq 'b' or myfield eq 'c', só que search.in vai render um desempenho muito melhor.
Existem duas sobrecargas da search.in função:
search.in(variable, valueList)search.in(variable, valueList, delimiters)
Os parâmetros são definidos na tabela a seguir:
| Nome do parâmetro | Tipo | Description |
|---|---|---|
variable |
Edm.String |
Uma referência de campo de cadeia de caracteres (ou uma variável de intervalo sobre um campo de coleção de cadeia de caracteres no caso em que search.in é usado dentro de uma any expressão ou all ). |
valueList |
Edm.String |
Uma cadeia de caracteres que contém uma lista delimitada de valores para corresponder ao variable parâmetro. Se o delimiters parâmetro não for especificado, os delimitadores padrão serão espaço e vírgula. |
delimiters |
Edm.String |
Uma cadeia de caracteres onde cada caractere é tratado como um separador ao analisar o valueList parâmetro. O valor padrão deste parâmetro é ' ,' o que significa que quaisquer 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 seus valores incluem esses caracteres, poderá especificar delimitadores alternativos, como '|' neste parâmetro. |
Desempenho de search.in
Se você usar search.ino , poderá esperar um tempo de resposta inferior a um segundo quando o segundo parâmetro contiver uma lista de centenas ou milhares de valores. Não há limite explícito para o número de itens para search.inos quais você pode passar, embora você ainda esteja limitado pelo tamanho máximo da solicitação. No entanto, a latência crescerá à medida que o número de valores crescer.
Exemplos
Encontre todos os hotéis com nome igual a 'Sea View motel' ou 'Budget hotel'. As frases contêm espaços, que é um delimitador padrão. Você pode especificar um delimitador alternativo entre aspas simples como o terceiro parâmetro de cadeia de caracteres:
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 '|'):
search.in(HotelName, 'Sea View motel|Budget hotel', '|')
Encontre todos os hotéis com quartos com a tag 'wifi' ou 'banheira':
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.
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))
Encontre todos os hotéis sem a tag 'motel' ou 'cabine':
Tags/all(tag: not search.in(tag, 'motel, cabin'))