Teilen über

Lucene-Abfragesyntax in Azure AI Search

  • Artikel

Beim Erstellen von Abfragen in Azure AI Search können Sie die vollständige Syntax des Lucene Query Parser für spezielle Abfrageformulare verwenden: Platzhaltersuche, Fuzzysuche, NEAR-Suche und Suche mit regulären Ausdrücken. Der Großteil der Lucene Query Parser-Syntax wird in Azure KI-Suche unverändert implementiert. Die einzige Ausnahme sind Bereichssuchen, die mit $filter-Ausdrücken erstellt werden.

Wenn Sie die vollständige Lucene-Syntax verwenden möchten, legen Sie queryType auf full fest und übergeben einen Abfrageausdruck, der für Platzhalterzeichen, die Fuzzysuche oder eines der anderen von der vollständigen Syntax unterstützten Abfrageformulare vorgesehen ist. In REST werden Abfrageausdrücke im search-Parameter eines Suchdokuments (REST API) bereitgestellt.

Beispiel (vollständige Syntax)

Das folgende Beispiel zeigt eine Suchanforderung, die mit der vollständigen Syntax erstellt wurde. In diesem speziellen Beispiel werden die In-Field-Suche und die Begriffsverstärkung veranschaulicht. Dabei werden Hotels gesucht, bei denen das Kategorienfeld den Begriff budget enthält. Allen Dokumenten, die den Ausdruck "recently renovated" enthalten, wird aufgrund des Werts für die Begriffsverstärkung (3) ein höherer Rang zugewiesen.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

Der searchMode-Parameter ist zwar nicht spezifisch für einen Abfragetyp, in diesem Beispiel aber relevant. Bei Abfragen mit Operatoren sollten Sie generell searchMode=all festlegen, um sicherzustellen, dass alle Kriterien abgeglichen werden.

Weitere Beispiele finden Sie unter Beispiele für die Lucene-Abfragesyntax. Ausführliche Informationen zur Abfrageanforderung und zu den Parametern (einschließlich „searchMode“) finden Sie unter Durchsuchen von Dokumenten (REST-API).

Grundlagen der Syntax

Die folgenden Syntaxgrundlagen gelten für alle Abfragen mit der Lucene-Syntax.

Operatorauswertung im Kontext

Die Platzierung bestimmt, ob ein Symbol als Operator oder einfach als ein weiteres Zeichen in einer Zeichenfolge interpretiert wird.

In der vollständigen Lucene-Syntax wird das Tildezeichen (~) beispielsweise sowohl für die Fuzzysuche als auch die NEAR-Suche verwendet. Wenn das ~ nach einem Ausdruck in Anführungszeichen steht, ruft es die NEAR-Suche auf. Steht ~ am Ende eines Begriffs, ruft es die Fuzzysuche auf.

Innerhalb eines Ausdrucks, wie z. B. business~analyst, wird das Zeichen nicht als Operator ausgewertet. Sofern es sich um eine Begriffs- oder Ausdrucksabfrage handelt, wird in diesem Fall bei der Volltextsuche mit lexikalischer Analyse das ~ entfernt, und der Begriff business~analyst wird in zwei Begriffe aufgeteilt: business ODER analyst.

Im obigen Beispiel geht es um das Tildezeichen (~), das gleiche Prinzip gilt jedoch für alle Operatoren.

Verwenden von Escapezeichen für Sonderzeichen

Um einen der Suchoperatoren als Teil des Suchtextes zu verwenden, maskieren Sie das Zeichen, indem Sie ihm einen einzelnen Backslash voranstellen (\). So würden Sie beispielsweise für eine Platzhaltersuche nach https://, in der :// ein Teil der Abfragezeichenfolge ist, search=https\:\/\/* angeben. Entsprechend könnte ein Telefonnummernmuster mit Escapezeichen so aussehen: \+1 \(800\) 642\-7676.

Zu den Sonderzeichen, die Escapezeichen erfordern, gehören die folgenden:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Hinweis

Obwohl Token durch die Verwendung von Escapezeichen zusammengehalten werden, können sie durch eine lexikalische Analyse während der Indizierung eventuell entfernt werden. Die Lucene-Standardanalyse teilt z. B. Wörter an Bindestrichen, Leerzeichen und anderen Zeichen auf. Wenn in der Abfragezeichenfolge Sonderzeichen erforderlich sind, benötigen Sie möglicherweise ein Analysetool, das sie im Index beibehält. Zu den Optionen gehören Microsoft Natural Language Analyzer (Analysetool für natürliche Sprache), bei dem Wörter mit Bindestrichen beibehalten werden, oder ein benutzerdefiniertes Analysetool für komplexere Muster. Weitere Informationen finden Sie unter Teilausdrücke, Muster und Sonderzeichen.

Codierung von unsicheren und reservierten Zeichen in URLs

Stellen Sie sicher, dass alle unsicheren und reservierten Zeichen in einer URL codiert werden. # ist beispielsweise ein Fragment- bzw. Ankerbezeichner in einer URL und deshalb ein unsicheres Zeichen. Bei der Verwendung in einer URL muss das Zeichen in %23 codiert werden. & und = sind Beispiele für reservierte Zeichen, da sie in Azure AI Search zum Trennen von Parametern und Angeben von Werten dienen. Weitere Informationen finden Sie unter RFC1738: Uniform Resource Locator (URL).

Unsichere Zeichen sind " ` < > # % { } | \ ^ ~ [ ]. Reservierte Zeichen sind ; / ? : @ = + &.

Boolesche Operatoren

Sie können boolesche Operatoren in eine Abfragezeichenfolge einbetten, um die Genauigkeit einer Übereinstimmung zu erhöhen. Die vollständige Syntax unterstützt neben Zeichenoperatoren auch Textoperatoren. Geben Sie boolesche Operatoren in Textform (AND, OR, NOT) immer in Großbuchstaben an.

Textoperator Zeichen Beispiel Verwendung
AND + wifi AND luxury Gibt Begriffe an, die eine Übereinstimmung enthalten muss. In dem Beispiel sucht das Abfragemodul nach Dokumenten, die sowohl wifi als auch luxury enthalten. Das Pluszeichen (+) kann auch direkt vor einer Benennung verwendet werden, um es erneut erforderlich zu machen. Beispielsweise legt +wifi +luxury fest, dass beide Begriffe im Feld eines einzelnen Dokuments vorkommen müssen.
OR (None) 1 wifi OR luxury Findet eine Übereinstimmung, wenn einer der beiden Begriffe gefunden wird. In dem Beispiel gibt das Abfragemodul eine Übereinstimmung für Dokumente zurück, die entweder wifi oder luxury oder beide Begriffe enthalten. Da OR der standardmäßige Konjunktionsoperator ist, könnten Sie ihn auch weglassen, d. h. wifi luxury entspricht wifi OR luxury.
NOT !, - wifi –luxury Gibt Übereinstimmungen für Dokumente zurück, die den Begriff ausschließen. Beispiel: wifi –luxury sucht nach Dokumenten, die den Begriff wifi, aber nicht den Begriff luxury enthalten.

1 Das Zeichen | wird für ODER-Vorgänge (OR) nicht unterstützt.

Boolescher NICHT-Operator

Wichtig

Der NICHT-Operator (NOT, ! oder -) in der vollständigen Syntax verhält sich anders als in einfacher Syntax.

  • In einfacher Syntax wird Abfragen mit Negation immer automatisch ein Platzhalter hinzugefügt. Die Abfrage -luxury wird z. B. automatisch erweitert auf -luxury *.
  • In der vollständigen Syntax können Abfragen mit Negation nicht mit einem Platzhalter kombiniert werden. Die Abfragen -luxury * sind beispielsweise nicht zulässig.
  • In der vollständigen Syntax sind Abfragen mit einer einzelnen Negation nicht zulässig. Die Abfrage -luxury ist beispielsweise nicht zulässig.
  • In der vollständigen Syntax verhalten sich Negationen so, als ob sie unabhängig vom Suchmodus immer auf die Abfrage mit UND hinzugefügt werden.
    • Die vollständige Syntaxabfrage wifi -luxury in der vollständigen Syntax ruft beispielsweise nur Dokumente ab, die den Ausdruck wifi enthalten, und wendet dann die Negation -luxury auf diese Dokumente an.
  • Wenn Sie Negationen verwenden möchten, um alle Dokumente im Index zu durchsuchen, wird eine einfache Syntax mit dem Suchmodus any empfohlen.
  • Wenn Sie Negationen verwenden möchten, um eine Teilmenge von Dokumenten im Index zu durchsuchen, werden vollständige Syntax oder die einfache Syntax mit dem gesamten Suchmodus empfohlen.
Abfragetyp Search Mode Beispielabfrage Verhalten
Einfach Beliebig wifi -luxury Gibt alle Dokumente im Index zurück. Dokumente mit dem Begriff „WLAN“ oder Dokumente, in denen der Begriff „Luxus“ fehlt, werden höher als andere Dokumente eingestuft. Die Abfrage wird auf wifi OR -luxury OR * erweitert.
Einfach all wifi -luxury Gibt nur Dokumente im Index zurück, die den Begriff „WIFI“ und nicht den Begriff „Luxus“ enthalten. Die Abfrage wird auf wifi AND -luxury AND * erweitert.
Vollzugriff Beliebig wifi -luxury Gibt nur Dokumente im Index zurück, die den Begriff „WIFI“ enthalten, und dann werden die Dokumente, die den Begriff „Luxus“ enthalten, aus den Ergebnissen entfernt.
Vollzugriff all wifi -luxury Gibt nur Dokumente im Index zurück, die den Begriff „WIFI“ enthalten, und dann werden die Dokumente, die den Begriff „Luxus“ enthalten, aus den Ergebnissen entfernt.

Feldbezogene Suche

Sie können einen feldbezogenen Suchvorgang mit der fieldName:searchExpression-Syntax definieren, wobei es sich bei dem Suchausdruck um ein einzelnes Wort, einen einfachen Ausdruck oder einen komplexeren Ausdruck in Klammern handeln kann, optional mit booleschen Operatoren. Einige Beispiele für Änderungen sind in der folgenden Liste aufgeführt:

  • genre:jazz NOT history

  • artists:("Miles Davis" "John Coltrane")

Achten Sie darauf, dass Sie mehrere Zeichenfolgen in Anführungszeichen setzen, wenn beide Zeichenfolgen als einzelne Entität ausgewertet werden sollen (in diesem Fall die Suche nach zwei verschiedenen Künstlern im Feld artists).

Das in fieldName:searchExpression angegebene Feld muss ein Feld vom Typ searchable sein. Einzelheiten zur Verwendung von Indexattributen in Felddefinitionen finden Sie unter Create Index (Erstellen eines Index).

Hinweis

Bei der Verwendung von feldbezogenen Suchausdrücken brauchen Sie den Parameter searchFields nicht zu verwenden, da in jedem feldbezogenen Suchausdruck explizit ein Feldname angegeben ist. Allerdings können Sie den Parameter searchFields trotzdem verwenden, wenn Sie eine Abfrage ausführen möchten, bei der einige Teile auf ein bestimmtes Feld beschränkt sind, der Rest sich jedoch auf mehrere Felder beziehen kann. Zum Beispiel würde jazz in der Abfrage search=genre:jazz NOT history&searchFields=description nur mit dem Feld genre, und NOT history mit dem Feld description abgeglichen werden. Der in fieldName:searchExpression angegebene Feldname hat immer Vorrang vor dem Parameter searchFields, weshalb genre in diesem Beispiel nicht in den Parameter searchFields aufgenommen werden muss.

Fuzzysuche

Bei einer Fuzzysuche werden Übereinstimmungen mit einer ähnlichen Konstruktion gefunden, wobei ein Begriff bis zu maximal 50 Begriffen erweitert wird, die die Abstandskriterien von zwei oder weniger erfüllen. Weitere Informationen finden Sie unter Fuzzysuche.

Verwenden Sie für eine Fuzzysuche das Tildezeichen ~ am Ende eines einzelnen Worts mit einem optionalen Parameter, einer Zahl zwischen 0 und 2 (Standardwert), der die Edit-Distanz angibt. Beispielsweise würden blue~ oder blue~1 blue, blues und gluezurückgeben.

Die Fuzzysuche kann nur auf Begriffe, nicht auf Ausdrücke in Anführungszeichen, angewendet werden. Sie können aber die Tilde an jeden Begriff in einem mehrteiligen Namen oder Ausdruck einzeln anfügen. Beispielsweise würde Unviersty~ of~ Wshington~ nur mit University of Washington übereinstimmen.

Näherungssuche

NEAR-Suchen werden verwendet, um Begriffe zu suchen, die in einem Dokument nahe beieinander liegen. Fügen Sie ein Tildezeichen ~ am Ende eines Ausdrucks ein, gefolgt von der Anzahl der Wörter, die den NEAR-Bereich bilden. Beispielsweise findet "hotel airport"~5 die Begriffe hotel und airport innerhalb von fünf Wörtern in einem Dokument.

Relevanz eines Begriffs erhöhen

Term Boosting bezieht sich auf das Höherbewerten eines Dokuments, das den verstärkten Begriff enthält, im Vergleich zu Dokumenten, die den Begriff nicht enthalten. Dies unterscheidet sich insofern von Bewertungsprofilen, als dass bei Bewertungsprofilen bestimmte Felder statt bestimmter Begriffe verstärkt werden.

Im folgenden Beispiel werden die Unterschiede veranschaulicht. Angenommen, Sie haben ein Bewertungsprofil, das Übereinstimmungen in einem bestimmten Feld verstärkt, beispielsweise genre im musicstoreindex-Beispiel. Mit der Begriffsverstärkung könnten Sie bestimmte Suchbegriffe noch höher bewerten als andere. Mit rock^2 electronic werden beispielsweise Dokumente, welche die Suchbegriffe im Feld „genre“ enthalten, höher eingestuft als andere durchsuchbare Felder im Index. Darüber hinaus wird Dokumenten, die den Suchbegriff rock enthalten, aufgrund des Werts für die Begriffsverstärkung (2) ein höherer Rang zugewiesen als Dokumenten mit dem anderen Suchbegriff elektronisch.

Verwenden Sie zum Verstärken eines Begriffs das Caretzeichen ^ mit einem Verstärkungsfaktor (einer Zahl) am Ende des Begriffs, nach dem Sie suchen. Sie können auch Ausdrücke verstärken. Je höher der Verstärkungsfaktor, desto relevanter wird der Begriff im Verhältnis zu anderen Suchbegriffen. Standardmäßig ist der Verstärkungsfaktor 1. Der Verstärkungsfaktor muss positiv sein, kann aber kleiner als 1 sein (z. B. 0.20).

Suche mit regulären Ausdrücken

Bei einer Suche mit regulären Ausdrücken werden Übereinstimmungen basierend auf unter Apache Lucene gültigen Mustern gefunden, wie in der RegExp-Klasse dokumentiert. In Azure AI Search wird ein regulärer Ausdruck in Schrägstrichen / eingeschlossen.

Um z. B. Dokumente zu suchen, die motel oder hotel enthalten, geben Sie an /[mh]otel/. Suchen mit regulären Ausdrücken werden mit einzelnen Wörtern abgeglichen.

Einige Tools und Sprachen enthalten zusätzliche Escapezeichenanforderungen, die über die von der Azure KI-Suche auferlegten Escaperegeln hinausgehen. Bei JSON werden Zeichenfolgen, die einen Schrägstrich enthalten, mit einem Escapezeichen in Form eines umgekehrten Schrägstrichs versehen: microsoft.com/azure/ wird zu search=/.*microsoft.com\/azure\/.*/, wobei search=/.* <string-placeholder>.*/ dem regulären Ausdruck und microsoft.com\/azure\/ der Zeichenfolge mit einem Escapezeichen in Form eines Schrägstrichs entspricht.

Zwei gängige Symbole in RegEx-Abfragen sind . und *. Ein . entspricht einem beliebigen Zeichen, und ein * entspricht dem vorherigen Zeichen, 0 (null) oder mehrmals. /be./ entspricht z. B. den Begriffen bee und bet während /be*/ mit be, bee und beee aber nicht mit bet übereinstimmen würden. Zusammen ermöglichen Ihnen .* den Abgleich einer beliebigen Abfolge von Zeichen, so dass /be.*/ jedem Begriff entspräche, der mit be beginnt, wie z. B. better.

Wenn Sie Syntaxfehler in Ihrem regulären Ausdruck erhalten, überprüfen Sie die Escaperegeln für Sonderzeichen. Sie können auch einen anderen Client ausprobieren, um zu überprüfen, ob das Problem toolspezifisch ist.

Platzhalter-Suche

Sie können die allgemein bekannte Syntax für die Platzhaltersuche nach mehreren (*) oder einzelnen (?) Zeichen verwenden. Die vollständige Lucene-Syntax unterstützt Präfix- und Infixvergleiche. Verwenden Sie die Syntax des regulären Ausdrucks zum Suffixabgleich.

Beachten Sie, dass der Lucene-Abfrageparser die Verwendung dieser Symbole bei einem einzelnen Begriff, nicht bei einem Ausdruck, unterstützt.

Affixtyp Beschreibung und Beispiele
prefix Begriffsfragmente stehen vor * oder ?. Beispiel: Ein Abfrageausdruck von search=alpha* gibt alphanumeric oder alphabetical zurück. Die Präfixübereinstimmung wird sowohl in der einfachen als auch vollständigen Syntax unterstützt.
Suffix Das Begriffsfragment folgt auf * oder ?, und das Konstrukt ist mit einem Schrägstrich begrenzt. search=/.*numeric/ gibt beispielsweise alphanumeric zurück.
infix Begriffsfragmente schließen * oder ? ein. Beispielsweise gibt search=non*al non-numerical und nonsensical zurück.

Sie können Operatoren in einem Ausdruck kombinieren. 980?2* gibt beispielsweise 98072-1222 und 98052-1234 zurück, während ? ein einzelnes (erforderliches) Zeichen und * darauf folgende Zeichenfolgen beliebiger Länge zurückgibt.

Für den Abgleich von Suffixen ist als Trennzeichen der Schrägstrich für reguläre Ausdrücke „/“ erforderlich. Im Allgemeinen können Sie ein *- oder ?-Symbol nicht als erstes Zeichen eines Begriffs ohne den / verwenden. Es ist auch wichtig zu beachten, dass sich das * anders verhält, wenn es außerhalb von RegEx-Abfragen verwendet wird. Außerhalb der RegEx-Schrägstrichtrennzeichen (/) für reguläre Ausdrücke ist * ein Platzhalterzeichen und entspricht allen Abfolgen von Zeichen, ähnlich wie .* in einem regulären Ausdruck. Beispielsweise erzeugt search=/non.*al/ dasselbe Ergebnis wie search=non*al.

Hinweis

Grundsätzlich ist der Musterabgleich langsam, sodass Sie möglicherweise alternative Methoden untersuchen sollten, z. B. Edge-N-Gramm-Tokenisierung, mit der Token für Zeichenfolgen in einem Begriff erstellt werden. Mit der N-Gramm-Tokenisierung wird der Index größer, Abfragen werden jedoch möglicherweise schneller ausgeführt, je nach der Form des Musters und der Länge der Zeichenfolgen, die Sie indizieren. Weitere Informationen finden Sie unter Suche nach Teilausdrücken und Mustern mit Sonderzeichen (Bindestriche, Platzhalter, reguläre Ausdrücke, Muster).

Auswirkung eines Analysetools auf Platzhalterabfragen

Während der Abfrageanalyse werden Abfragen, die als Präfix-, Suffix-, Platzhaltersuche oder reguläre Ausdrücke formuliert werden, unverändert an die Abfragestruktur übergeben, wobei die lexikalische Analyse umgangen wird. Es werden nur Übereinstimmungen gefunden, wenn der Index die Zeichenfolgen in dem in der Abfrage angegebenen Format enthält. In den meisten Fällen benötigen Sie beim Indizieren ein Analysetool, das die Integrität der Zeichenfolgen beibehält, damit der Abgleich von Teilausdrücken und Mustern gelingt. Weitere Informationen finden Sie im Thema zur Suche nach Teilausdrücken in Azure AI Search-Abfragen.

Berücksichtigen Sie eine Situation, in der die Suchabfrage terminal* Ergebnisse zurückgeben soll, die Ausdrücke wie terminate, terminationund terminates beinhalten.

Wenn Sie das Analysetool „de.lucene“ (deutsches Lucene) verwendeten, würde es eine aggressive Wortstammerkennung der einzelnen Begriffe anwenden. Beispielsweise werden terminate, termination, terminates alle tokenisiert bis zum Token termi in Ihrem Index. Andererseits werden Begriffe in Abfragen mit Platzhaltern oder Fuzzysuche überhaupt nicht analysiert. Deshalb gäbe es keine Ergebnisse für die terminat*-Abfrage.

Andererseits sind die Microsoft-Analysetools (in diesem Fall das Analysetool „de.microsoft“) etwas komplexer und verwenden Lemmatisierung statt Wortstammerkennung. Dies bedeutet, dass alle generierten Token gültige deutsche Wörter sein sollten. Beispielsweise bleiben terminate, terminates und termination meistens ganz im Index und wären eine bevorzugte Wahl bei Szenarien, die sehr viel auf Platzhalter und Fuzzysuche angewiesen sind.

Bewerten von Platzhalterabfragen und Abfragen mit regulären Ausdrücken

Azure AI Search verwendet für Textabfragen die häufigkeitsbasierte Bewertung (BM25). Für Platzhalterabfragen und Abfragen mit regulären Ausdrücken, bei denen die Anzahl von Begriffen groß sein kann, wird der Häufigkeitsfaktor jedoch ignoriert. Dadurch wird verhindert, dass Übereinstimmungen für seltenere Begriffe bei der Rangzuweisung bevorzugt behandelt werden. Alle Übereinstimmungen werden bei Platzhalterabfragen und Abfragen mit regulären Ausdrücken gleich behandelt.

Sonderzeichen

Unter bestimmten Umständen möchten Sie möglicherweise nach einem Sonderzeichen suchen, z. B. nach dem Emoji ❤ oder dem €-Zeichen. Stellen Sie in solchen Fällen sicher, dass das verwendete Analysetool diese Zeichen nicht herausfiltert. Das Standardanalysetool umgeht viele Sonderzeichen und schließt sie aus Ihrem Index aus.

Zu den Analysetools, die Sonderzeichen tokenisieren, gehört das Leerzeichen-Analysetool, das alle durch Leerzeichen getrennten Zeichensequenzen als Token berücksichtigt (sodass die Zeichenfolge ❤ als Token angesehen werden würde). Ein Sprachanalysetool wie das Microsoft-Analysetool für englische Sprache („en.microsoft“) würde auch die Zeichenfolge „€“ als Token ansehen. Sie können ein Analysetool testen, um herauszufinden, welche Token für eine bestimmte Abfrage generiert werden.

Wenn Sie Unicode-Zeichen verwenden, stellen Sie sicher, dass die Symbole in der Abfrage-URL ordnungsgemäß mit Escapezeichen versehen werden (z. B. muss für ❤ die Escapefolge %E2%9D%A4+ verwendet werden). Einige REST-Clients führen diese Übersetzung automatisch aus.

Rangfolge (Gruppierung)

Sie können mithilfe von Klammern Unterabfragen erstellen, die Operatoren innerhalb der Anweisung in Klammern enthalten. Beispielsweise sucht motel+(wifi|luxury) nach Dokumenten, die den motel-Ausdruck und entweder wifi oder luxury (oder beides) enthalten.

Die Feldgruppierung funktioniert ähnlich, beschränkt die Gruppierung jedoch auf ein einzelnes Feld. Beispielsweise durchsucht hotelAmenities:(gym+(wifi|pool)) das Feld hotelAmenities nach gym und wifioder gym und pool.

Abfragegrößenlimits

Azure AI Search erlegt der Abfragegröße und -zusammensetzung Grenzwerte auf, da unbegrenzte Abfragen Ihren Suchdienst destabilisieren können. Es gibt Grenzwerte für die Abfragegröße und -zusammensetzung (anzahl der Klauseln). Es gibt auch Grenzwerte für die Länge der Präfixsuche sowie für die Komplexität der RegEx-Suche und Platzhaltersuche. Wenn Ihre Anwendung programmgesteuert Suchabfragen generiert, sollten Sie durch den Entwurf sicherstellen, dass sie keine Abfragen von unbegrenzter Größe erzeugt.

Weitere Informationen zu Abfragegrenzwerten finden Sie unter API-Anforderungslimits.

Siehe auch