Fonction search.in OData dans la recherche Azure AI
Un scénario courant dans Expressions de filtre OData consiste à vérifier si un champ unique dans chaque document est égal à l’une des nombreuses valeurs possibles. Par exemple, voici comment certaines applications implémentent le filtrage de sécurité : en comparant un champ contenant un ou plusieurs ID de principal avec une liste d’ID de principal représentant l’utilisateur qui émet la requête. Une façon d’écrire une requête telle que celle-ci consiste à utiliser les opérateurs eq et or :
group_ids/any(g: g eq '123' or g eq '456' or g eq '789')
Toutefois, il existe une manière plus courte de l’écrire, à l’aide de la fonction search.in :
group_ids/any(g: search.in(g, '123, 456, 789'))
Important
En plus d’être plus courte et plus facile à lire, l’utilisation de search.in offre également des avantages en termes de performances et permet d’éviter certaines limites de taille de filtres lorsqu’il existe des centaines voire des milliers de valeurs à inclure dans le filtre. Pour cette raison, nous recommandons fortement d’utiliser search.in au lieu d’une disjonction plus complexe d’expressions d’égalité.
Remarque
La version 4.01 du protocole OData standard a récemment introduit l’inopérateur, qui a un comportement similaire à la fonction search.in dans la recherche Azure AI. Toutefois, la recherche Azure AI ne prend pas en charge cet opérateur, vous devez donc utiliser la fonction search.in à la place.
Syntaxe
L’extension EBNF suivante (Extended Backus-Naur Form) définit la grammaire de la fonction search.in :
search_in_call ::=
'search.in(' variable ',' string_literal(',' string_literal)? ')'
Un diagramme de syntaxe interactif est également disponible :
Remarque
Consultez Informations de référence sur la syntaxe d’expression OData pour la recherche Azure AI afin d’avoir la forme EBNF complète.
La fonction search.in teste si un champ de type chaîne donné ou une variable de portée est égal à une des valeurs d’une liste donnée. L’égalité entre la variable et chaque valeur de la liste est déterminée de manière à respecter la casse, de la même façon que pour l’opérateur eq. Ainsi, une expression comme search.in(myfield, 'a, b, c') équivaut à myfield eq 'a' or myfield eq 'b' or myfield eq 'c', sauf que search.in aboutira à de bien meilleures performances.
Il existe deux surcharges de la fonction search.in :
search.in(variable, valueList)search.in(variable, valueList, delimiters)
Les paramètres sont définis dans le tableau suivant :
| Nom du paramètre | Type | Description |
|---|---|---|
variable |
Edm.String |
Une référence du champ de type chaîne (ou une variable de portée sur un champ de collection de chaînes dans le cas où search.in est utilisé à l’intérieur d’une expression any ou all). |
valueList |
Edm.String |
Une chaîne contenant une liste délimitée de valeurs à mettre en correspondance le paramètre variable. Si le paramètre delimiters n’est pas spécifié, les séparateurs par défaut sont l’espace et la virgule. |
delimiters |
Edm.String |
Une chaîne dans laquelle chaque caractère est traité comme un séparateur lors de l’analyse du paramètre valueList. La valeur par défaut de ce paramètre est ' ,', ce qui signifie que toutes les valeurs avec des espaces et/ou des virgules entre elles seront séparées. Si vous devez utiliser des séparateurs autres que des espaces et des virgules dans le cas où vos valeurs incluent ces caractères, vous pouvez spécifier d’autres séparateurs, tels que '|' dans ce paramètre. |
Performances de search.in
Si vous utilisez search.in, vous pouvez vous attendre à des temps de réponse inférieurs à la seconde quand le deuxième paramètre contient une liste de plusieurs centaines ou plusieurs milliers de valeurs. Il n’existe pas de limite explicite quant au nombre d’éléments que vous pouvez passer à search.in, même si vous êtes néanmoins limité par la taille maximale de la demande. Cependant, la latence augmente en même temps que le nombre de valeurs.
Exemples
Recherchez tous les hôtels avec un nom égal à « Sea View motel » ou « Budget hotel ». Les expressions contiennent des espaces, qui sont des séparateurs par défaut. Vous pouvez spécifier un autre séparateur entre guillemets simples comme troisième paramètre de chaîne :
search.in(HotelName, 'Sea View motel,Budget hotel', ',')
Recherchez tous les hôtels avec un nom égal à « Sea View motel » ou « Budget hotel » séparés par « | » :
search.in(HotelName, 'Sea View motel|Budget hotel', '|')
Recherchez tous les hôtels avec des chambres comportant les balises « wifi » ou « baignoire » :
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))
Recherchez une correspondance entre des expressions tirées d’une collection, telles que « heated towel racks » ou « hairdryer included » dans les balises.
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))
Recherchez tous les hôtels sans les balises « motel » ou « cabin » :
Tags/all(tag: not search.in(tag, 'motel, cabin'))