OData-Funktion search.in in Azure KI Search
Ein gängiges Szenario für OData-Filterausdrücke ist die Überprüfung, ob ein einzelnes Feld in den Dokumenten jeweils einem von vielen möglichen Werten entspricht. So wird in einigen Anwendungen beispielsweise zur Implementierung der Einschränkung aus Sicherheitsgründen ein Feld, das eine oder mehrere Prinzipal-IDs enthält, mit einer Liste von Prinzipal-IDs verglichen, die den Benutzer darstellen, der die Abfrage ausführt. Eine solche Abfrage kann beispielsweise mithilfe der Operatoren eq und or erstellt werden:
group_ids/any(g: g eq '123' or g eq '456' or g eq '789')
Die Funktion search.in bietet hier eine kürzere Möglichkeit:
group_ids/any(g: search.in(g, '123, 456, 789'))
Wichtig
Diese Methode ist kürzer und besser lesbar. Darüber hinaus bietet die Verwendung der Funktion search.in auch Leistungsvorteile und ermöglicht die Vermeidung bestimmter Größeneinschränkungen von Filtern, wenn hunderte oder sogar tausende Werte in den Filter eingeschlossen werden. Aus diesem Grund empfehlen wir dringend, anstelle einer komplexeren Disjunktion von Gleichheitsausdrücken die Funktion search.in zu verwenden.
Hinweis
In der Version 4.01 des OData-Standards wurde kürzlich der in-Operator eingeführt, der sich ähnlich verhält wie die Funktion search.in in Azure KI Search. Dieser Operator wird von Azure KI Search allerdings nicht unterstützt, weshalb stattdessen die Funktion search.in verwendet werden muss.
Syntax
Die folgende EBNF (Erweiterte Backus-Naur-Form) definiert die Grammatik der Funktion search.in:
search_in_call ::=
'search.in(' variable ',' string_literal(',' string_literal)? ')'
Ein interaktives Syntaxdiagramm ist ebenfalls verfügbar:
Hinweis
Die vollständige EBNF finden Sie in der Referenz zur OData-Ausdruckssyntax für Azure KI Search.
Die Funktion search.in testet, ob ein bestimmtes Zeichenfolgenfeld oder eine Bereichsvariable einem der Werte in einer angegebenen Liste entspricht. Die Gleichheit zwischen der Variablen und den einzelnen Werten in der Liste wird wie beim eq-Operator unter Berücksichtigung der Groß-/Kleinschreibung ermittelt. Ein Ausdruck wie search.in(myfield, 'a, b, c') entspricht daher myfield eq 'a' or myfield eq 'b' or myfield eq 'c', allerdings bietet search.in eine deutlich bessere Leistung.
Es gibt zwei Überladungen der Funktion search.in:
search.in(variable, valueList)search.in(variable, valueList, delimiters)
Die Parameter werden in der folgenden Tabelle definiert:
| Parametername | Type | Beschreibung |
|---|---|---|
variable |
Edm.String |
Ein Verweis auf ein Zeichenfolgenfeld (oder eine Bereichsvariable für ein Zeichenfolgensammlungsfeld, falls search.in innerhalb eines Ausdrucks vom Typ any oder all verwendet wird). |
valueList |
Edm.String |
Eine Zeichenfolge mit einer durch Trennzeichen getrennten Liste von Werten für den Abgleich mit dem Parameter variable. Ohne Angabe des Parameters delimiters werden standardmäßig Leerzeichen und Kommas als Trennzeichen verwendet. |
delimiters |
Edm.String |
Eine Zeichenfolge, in der bei der Analyse des Parameters valueList jedes Zeichen als Trennzeichen behandelt wird. Der Standardwert dieses Parameters ist ' ,'. Das bedeutet, dass alle Werte, zwischen denen sich Leerzeichen und/oder Kommas befinden, getrennt werden. Falls Sie anstelle von Leerzeichen und Kommas andere Trennzeichen verwenden müssen, da Ihre Werte diese Zeichen enthalten, können Sie in diesem Parameter alternative Trennzeichen angeben (beispielsweise '|'). |
Leistung von search.in
Bei der Verwendung von search.in ist eine Antwortzeit von unter einer Sekunde zu erwarten, wenn der zweite Parameter eine Liste von Hunderten oder Tausenden von Werten enthält. Für die Anzahl von Elementen, die Sie an search.in übergeben können, gibt es keinen expliziten Grenzwert. Die maximal zulässige Anforderungsgröße gilt allerdings weiterhin. Die Wartezeit nimmt jedoch mit zunehmender Anzahl von Werten zu.
Beispiele
Suche nach allen Hotels, deren Name „Sea View motel“ oder „Budget hotel“ entspricht. Ausdrücke enthalten Leerzeichen, die Standardtrennzeichen sind. Sie können ein alternatives Trennzeichen in einfachen Anführungszeichen als dritten Zeichenfolgenparameter angeben:
search.in(HotelName, 'Sea View motel,Budget hotel', ',')
Suche nach allen Hotels, deren Name „Sea View motel“ oder „Budget hotel“ entspricht (getrennt durch „|“):
search.in(HotelName, 'Sea View motel|Budget hotel', '|')
Suche nach allen Hotels mit Zimmern, die über das Tag „wifi“ oder „tub“ verfügen:
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))
Suchen Sie eine Übereinstimmung mit Ausdrücken innerhalb einer Sammlung, z.B. „beheizte Handtuchhalter“ oder „Haartrockner inklusive“ in Tags.
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))
Suche nach allen Hotels ohne das Tag „motel“ oder „cabin“:
Tags/all(tag: not search.in(tag, 'motel, cabin'))