OData-Sprachübersicht für $filter, $orderby und $select in Azure AI Search

Dieser Artikel bietet einen Überblick über die OData-Ausdruckssprache, die in $filter, $order-by und $select verwendet wird, und Ausdrücke für die Stichwortsuche in Azure KI-Suche über numerische und Zeichenfolgefelder (Nicht-Vektoren).

Die Sprache wird „bottom-up“ vorgestellt, beginnend mit den einfachsten Elementen. Die OData-Ausdrücke, die Sie in einem Abfrageanforderungsbereich erstellen können, reichen von einfach bis hoch komplex, teilen aber alle gemeinsame Elemente. Zu den freigegebenen Elementen gehören:

• Feldpfade für Verweise auf bestimmte Felder des Index
• Konstanten als Literalwerte eines bestimmten Datentyps

Sobald Sie diese allgemeinen Konzepte verstanden haben, können Sie mit der Syntax der obersten Ebene für jeden Ausdruck fortfahren:

• $filter Ausdrücke werden während der Abfrageanalyse ausgewertet, die Suche auf bestimmte Felder beschränkt oder Übereinstimmungskriterien hinzugefügt, die bei Indexüberprüfungen verwendet werden.
• $orderby Ausdrücke werden als Nachbearbeitungsschritt über ein Resultset angewendet, um die zurückgegebenen Dokumente zu sortieren.
• $select Ausdrücke bestimmen, welche Dokumentfelder im Resultset enthalten sind.

Die Syntax dieser Ausdrücke unterscheidet sich von der einfachen oder vollständigen Abfragesyntax, die im Suchparameter verwendet wird, obwohl es einige Überlappungen in der Syntax für verweisende Felder gibt.

Beispiele in anderen Sprachen wie Python oder C# finden Sie in den Beispielen im RepositoryAzure-search-vector-samples.

Feldpfade

Die folgende EBNF (Erweiterte Backus-Naur-Form) definiert die Grammatik der Feldpfade.

field_path ::= identifier('/'identifier)*

identifier ::= [a-zA-Z_][a-zA-Z_0-9]*

Ein interaktives Syntaxdiagramm ist ebenfalls verfügbar:

Ein Feldpfad besteht aus einem oder mehreren Bezeichnern, die durch Schrägstriche voneinander getrennt sind. Jeder Bezeichner ist eine Folge von Zeichen, die mit einem ASCII-Buchstaben oder einem Unterstrich beginnen muss und nur ASCII-Buchstaben, Ziffern oder Unterstriche enthalten darf. Es können Groß- und Kleinbuchstaben verwendet werden.

Ein Bezeichner kann entweder auf den Namen eines Felds oder auf eine Bereichsvariable im Kontext eines Sammlungsausdruck (any oder all) in einem Filter verweisen. Eine Bereichsvariable ist wie eine Schleifenvariable, die das aktuelle Element der Sammlung darstellt. Bei komplexen Auflistungen stellt diese Variable ein Objekt dar, weshalb Sie Feldpfade verwenden können, um auf Unterfelder der Variablen zu verweisen. Dies ist vergleichbar mit der Punktnotation in vielen Programmiersprachen.

Die folgende Tabelle enthält Beispiele für Feldpfade:

Die Bedeutung eines Feldpfads variiert je nach Kontext. In Filtern verweist ein Feldpfad auf den Wert einer Einzelinstanz eines Felds im aktuellen Dokument. In anderen Kontexten, wie z. B. $orderby, $select oder bei der feldbezogenen Suche in der vollständigen Lucene-Syntax, verweist ein Feldpfad auf das Feld selbst. Dieser Unterschied hat Konsequenzen für die Verwendung von Feldpfaden in Filtern.

Betrachten Sie den Feldpfad Address/City. In einem Filter verweist dieser auf eine einzelne Stadt im aktuellen Dokument, z. B. „San Francisco“. Im Gegensatz dazu bezieht sich Rooms/Type auf das Unterfeld Type für viele Räume (z. B. „Standard“ für den ersten Raum, „deluxe“ für den zweiten Raum usw.). Da Rooms/Type nicht auf eine einzelne Instanz des Unterfelds Type verweist, kann es nicht direkt in einem Filter verwendet werden. Um stattdessen nach dem Zimmertyp zu filtern, verwenden Sie einen Lambdaausdruck mit einer Bereichsvariable, wie im Folgenden gezeigt:

Rooms/any(room: room/Type eq 'deluxe')

In diesem Beispiel ist die Bereichsvariable room im Feldpfad room/Type enthalten. Auf diese Weise verweist room/Type auf den Typ des aktuellen Zimmers im aktuellen Dokument. Dies ist eine einzelne Instanz des Type Unterfelds, sodass es direkt im Filter verwendet werden kann.

Verwenden von Feldpfaden

Feldpfade werden in zahlreichen Parametern der REST-APIs für Azure AI Search verwendet. Die folgende Tabelle enthält alle Stellen, an denen sie verwendet werden können, sowie einige Einschränkungen für ihre Nutzung:

Konstanten

Konstanten in OData sind Literalwerte eines bestimmten Entity Data Model-Typs (EDM). Eine Liste der in Azure AI Search unterstützten Typen finden Sie unter Unterstützte Datentypen. Konstanten von Sammlungstypen werden nicht unterstützt.

Die folgende Tabelle enthält Beispiele für Konstanten für jeden der Nicht-Vektor-Datentypen, die OData-Ausdrücke unterstützen:

Verwenden von Sonderzeichen in Zeichenfolgenkonstanten

Zeichenfolgenkonstanten in OData werden durch einfache Anführungszeichen getrennt. Wenn Sie eine Abfrage mit einer Zeichenfolgenkonstante erstellen müssen, die selbst Anführungszeichen enthalten kann, können Sie die eingebetteten Anführungszeichen verdoppeln, um sie mit Escapezeichen zu versehen.

Beispielsweise würde ein Ausdruck mit einem unformatierten Apostroph wie „Alice's car“ in OData als die Zeichenfolgenkonstante 'Alice''s car' dargestellt werden.

Konstantensyntax

Die folgende EBNF (erweiterte Backus-Naur-Form) definiert die Grammatik für die meisten Konstanten in der obigen Tabelle. Die Grammatik für geografisch-räumliche Datentypen finden Sie unter Geografisch-räumliche OData-Funktionen in Azure AI Search.

constant ::=
    string_literal
    | date_time_offset_literal
    | integer_literal
    | float_literal
    | boolean_literal
    | 'null'

string_literal ::= "'"([^'] | "''")*"'"

date_time_offset_literal ::= date_part'T'time_part time_zone

date_part ::= year'-'month'-'day

time_part ::= hour':'minute(':'second('.'fractional_seconds)?)?

zero_to_fifty_nine ::= [0-5]digit

digit ::= [0-9]

year ::= digit digit digit digit

month ::= '0'[1-9] | '1'[0-2]

day ::= '0'[1-9] | [1-2]digit | '3'[0-1]

hour ::= [0-1]digit | '2'[0-3]

minute ::= zero_to_fifty_nine

second ::= zero_to_fifty_nine

fractional_seconds ::= integer_literal

time_zone ::= 'Z' | sign hour':'minute

sign ::= '+' | '-'

/* In practice integer literals are limited in length to the precision of
the corresponding EDM data type. */
integer_literal ::= digit+

float_literal ::=
    sign? whole_part fractional_part? exponent?
    | 'NaN'
    | '-INF'
    | 'INF'

whole_part ::= integer_literal

fractional_part ::= '.'integer_literal

exponent ::= 'e' sign? integer_literal

boolean_literal ::= 'true' | 'false'

Ein interaktives Syntaxdiagramm ist ebenfalls verfügbar:

Erstellen von Ausdrücken aus Feldpfaden und Konstanten

Feldpfade und Konstanten sind der grundlegendste Teil jedes OData-Ausdrucks, sie sind aber selbst bereits vollständige Ausdrücke. Tatsächlich ist der $select-Parameter in Azure AI Search nur eine durch Trennzeichen getrennte Liste der Feldpfade, und $orderby ist nicht viel komplizierter als $select. Wenn Ihr Index ein Feld vom Typ Edm.Boolean enthält, können Sie sogar einen Filter schreiben, der lediglich der Pfad dieses Felds ist. Die Konstanten true und false sind ebenfalls gültige Filter.

Es kommt jedoch häufiger vor, dass sich komplexe Ausdrücke auf mehr als ein Feld und eine Konstante beziehen. Diese Ausdrücke werden je nach Parameter auf verschiedene Arten erstellt.

Die folgende EBNF (erweiterte Backus-Naur-Form) definiert die Grammatik der Parameter $filter, $orderby und $select. Diese basieren auf einfacheren Ausdrücken, die auf die Feldpfade und Konstanten verweisen:

filter_expression ::= boolean_expression

order_by_expression ::= order_by_clause(',' order_by_clause)*

select_expression ::= '*' | field_path(',' field_path)*

Ein interaktives Syntaxdiagramm ist ebenfalls verfügbar:

Nächste Schritte

Die Parameter $orderby und $select sind durch Trennzeichen getrennte Listen mit einfachen Ausdrücken. Der $filter-Parameter ist ein boolescher Ausdruck, der aus einfacheren Unterausdrücken besteht. Diese Unterausdrücke werden mithilfe logischer Operatoren wie and, or und not, Vergleichsoperatoren wie eq, lt, gt usw. und Sammlungsoperatoren wie any und all kombiniert.

In den folgenden Artikeln werden die Parameter $filter, $orderby und $select ausführlicher besprochen:

• OData-Syntax von „$filter“ in Azure AI Search
• OData-Syntax von „$orderby“ in Azure AI Search
• OData-Syntax von „$select“ in Azure AI Search