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.
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:
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 |
Suche | search , wenn queryType den Wert full hat |
Kann nur auf durchsuchbare Felder verweisen |
Suche | facet |
Kann nur auf facettierbare Felder verweisen |
Suche | highlight |
Kann nur auf durchsuchbare Felder verweisen |
Suche | 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 enthält Beispiele für Konstanten für jeden der Nicht-Vektor-Datentypen, die OData-Ausdrücke unterstützen:
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:
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.
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:
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: