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

  • Artikel

Dieser Artikel enthält eine Übersicht über die OData-Ausdruckssprache, die in den $filter, $order-by- und $select-Ausdrücken in Azure AI Search verwendet wird. 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.

Hinweis

Die Terminologie in Azure AI Search unterscheidet sich vom OData-Standard in verschiedener Hinsicht. Was in Azure AI Search als Feld bezeichnet wird, ist in OData eine Eigenschaft. Dasselbe gilt auch für Feldpfad bzw. Eigenschaftspfad. Ein Index mit Dokumenten in Azure AI Search wird in OData allgemeiner als eine Entitätenmenge mit Entitäten bezeichnet. In dieser Referenz wird die Azure AI Search-Terminologie verwendet.

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:

OData-Syntaxdiagramm für Azure AI Search

Hinweis

Die vollständige EBNF finden Sie in der Referenz zur OData-Ausdruckssyntax für Azure AI Search.

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:

Feldpfad BESCHREIBUNG
HotelName Verweist auf ein Feld der obersten Ebene des Indexes
Address/City Bezieht sich auf das Unterfeld City eines komplexen Felds im Index; Address ist in diesem Beispiel vom Typ Edm.ComplexType
Rooms/Type Bezieht sich auf das Unterfeld Type eines komplexen Auflistungsfelds im Index; Rooms ist in diesem Beispiel vom Typ Collection(Edm.ComplexType)
Stores/Address/Country Bezieht sich auf das Unterfeld Country des Unterfelds Address eines komplexen Auflistungsfelds im Index; Stores ist vom Typ Collection(Edm.ComplexType) und Address ist vom Typ Edm.ComplexType in diesem Beispiel
room/Type Bezieht sich auf das Unterfeld Type der room Bereichsvariablen, z. B. im Filterausdruck Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country Bezieht sich auf das Unterfeld Country des Unterfelds Address der Variablen store Bereich, z. B. im Filterausdruck Stores/any(store: store/Address/Country eq 'Canada')

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:

API Parametername Beschränkungen
Erstellen oder Aktualisieren des Index suggesters/sourceFields Keine
Erstellen oder Aktualisieren des Index scoringProfiles/text/weights Kann nur auf durchsuchbare Felder verweisen
Erstellen oder Aktualisieren des Index scoringProfiles/functions/fieldName Kann nur auf filterbare Felder verweisen
Suchen, search, wenn queryType den Wert full hat Kann nur auf durchsuchbare Felder verweisen
Suchen, facet Kann nur auf facettierbare Felder verweisen
Suchen, highlight Kann nur auf durchsuchbare Felder verweisen
Suchen, searchFields Kann nur auf durchsuchbare Felder verweisen
Vorschlagen und AutoVervollständigen searchFields Kann nur auf Felder verweisen, die Teil einer Vorschlagsfunktion sind
Suchen, Vorschlagen und AutoVervollständigen $filter Kann nur auf filterbare Felder verweisen
Suchen und Vorschlagen $orderby Kann nur auf sortierbare Felder verweisen
Suchen, Vorschlagen und Nachschlagen $select Kann nur auf abrufbare Felder verweisen

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 zeigt Beispiele für Konstanten für jeden der von Azure AI Search unterstützten Datentypen:

Datentyp Beispielkonstanten
Edm.Boolean true, false
Edm.DateTimeOffset 2019-05-06T12:30:05.451Z
Edm.Double 3.14159, -1.2e7, NaN, INF, -INF
Edm.GeographyPoint geography'POINT(-122.131577 47.678581)'
Edm.GeographyPolygon geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'
Edm.Int32 123, -456
Edm.Int64 283032927235
Edm.String 'hello'

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.

Wichtig

Wenn Sie Filter programmgesteuert erstellen, sollten Sie daran denken, Zeichenfolgenkonstanten aus Benutzereingaben mit Escapezeichen zu versehen. Dadurch wird – insbesondere bei Verwendung von Filtern zum Implementieren von Sicherheitskürzungen – die Möglichkeit von Injektionsangriffen umgangen.

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:

OData-Syntaxdiagramm für Azure AI Search

Hinweis

Die vollständige EBNF finden Sie in der Referenz zur OData-Ausdruckssyntax für Azure AI Search.

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.

Allerdings benötigen Sie in den meisten Fällen komplexere Ausdrücke, die auf mehr als ein Feld und eine Konstante verweisen. 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:

OData-Syntaxdiagramm für Azure AI Search

Hinweis

Die vollständige EBNF finden Sie in der Referenz zur OData-Ausdruckssyntax für Azure AI Search.

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: