Lucene-Abfragesyntax in Azure KI-Suche

Beim Erstellen von Abfragen in Azure KI-Suche 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 des 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. Dieses konkrete Beispiel zeigt feldbezogene Suche und Phrasen-Boosting. Dabei werden Hotels gesucht, bei denen das Kategorienfeld den Begriff budget enthält. Dokumente, die den Ausdruck "recently renovated" enthalten, erhalten ein zusätzliches Boost-Gewicht und werden aufgrund des Phrase-Boost-Werts (3) möglicherweise höher eingestuft.

POST /indexes/hotels-sample/docs/search?api-version=2026-04-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:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

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 KI-Suche 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.

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

Boolescher NICHT-Operator

• 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.

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).

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~1blue, 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

Stellen Sie sich die Suche als zwei Schritte vor. Zuerst findet Azure KI-Suche übereinstimmende Dokumente. Anschließend werden diese Übereinstimmungen bewertet. Das Boosting von Suchbegriffen betrifft nur den zweiten Schritt: Es kann Dokumente, die mit einem Teil Ihrer Abfrage übereinstimmen, in den Ergebnissen weiter nach oben verschieben.

Term-Boosting unterscheidet sich von einem Scoringprofil. Eine Gewichtungserhöhung bevorzugt ein Wort, einen Ausdruck oder eine Gruppe in der aktuellen Abfrage. Ein Bewertungsprofil bevorzugt Felder oder andere Indexinhalte gemäß den im Index definierten Regeln.

Verstärkungsbereich

Schreiben Sie ein Caretzeichen (^) und eine positive Zahl unmittelbar nach dem Teil der Abfrage, den Sie bevorzugen möchten. Beispielsweise kann tax^2 Dokumente, die tax enthalten, höher einstufen als Dokumente, die nur mit einem nicht verstärkten Begriff übereinstimmen. Der Standardwert für die Heraufwertung ist 1. Sie können auch einen Wert zwischen 0 und 1 verwenden, z. B. 0.2, um eine Übereinstimmung geringer zu gewichten.

Die Interpunktion teilt Ihnen mit, welche Wörter die einzelnen Anweisungen betreffen:

• Ein Feldname plus ein Doppelpunkt, der als Feldpräfix bezeichnet wird, wird vor einem Wort, einem an zitierten Ausdruck oder einer Klammergruppe angezeigt. Zum Beispiel weist content: Azure KI-Suche an, im Feld content zu suchen.
• Ein Hochgestellt-Zeichen wie ^2 erscheint nach einem Wort, einem in Anführungszeichen gesetzten Ausdruck oder einer in Klammern gesetzten Gruppe. Sie teilt Azure KI-Suche mit, was bei der Einstufung der Treffer bevorzugt werden soll.

In der folgenden Tabelle wird der Standardwert searchMode=any verwendet, wobei ein Leerzeichen zwischen Wörtern als OR fungiert.

Mit searchMode=all erfordert die Abfrage deferred tax^2, dass beide Wörter übereinstimmen. Die Verstärkung gilt weiterhin nur für tax. Wenn Sie stattdessen mit beiden Wörtern übereinstimmen möchten, schreiben Sie deferred OR tax^2.

Platzieren Sie das Caret nach dem schließenden Anführungszeichen oder der Klammer, wenn Sie den gesamten Ausdruck oder die gesamte Gruppe erhöhen möchten. Klammern erstellen keinen Ausdruck. Verwenden Sie Anführungszeichen, wenn die Wörter nebeneinander und in einer bestimmten Reihenfolge stehen müssen.

Verstärkung und Feldumfang

Ein Feldname, gefolgt von einem Doppelpunkt, beschränkt den Bereich, in dem Azure KI-Suche sucht. Eine Gewichtung ändert, wie Azure KI-Suche einen Treffer einstuft. Sie können beide in derselben Abfrage verwenden.

Wenn beispielsweise searchFields auf title festgelegt ist, sucht die erste Abfrage nach deferred in content und nach tax in title. Die Anführungszeichen und Klammern in den anderen Suchanfragen sorgen dafür, dass beide Wörter in content bleiben.

Auswirkung eines Analyzers auf erhöhte Abfragen

Bei gewöhnlichen Wörtern, Ausdrücken und Wortgruppen überspringt das Boosting die Textanalyse nicht. Vor dem Abgleichen verarbeitet Azure KI-Suche den Abfragetext dennoch mit dem Analyzer des jeweiligen Felds. Daher kann derselbe verstärkte Text in Feldern, die unterschiedliche Analyzer verwenden, unterschiedlich übereinstimmen.

Ein Ausdruck oder eine Gruppe mit einem Feldpräfix verwendet den Analyzer dieses Felds. Text ohne Feldpräfix verwendet den Analysator für jedes zu durchsuchende Feld. Beispielsweise kann ein Analysator, der Text in Kleinbuchstaben umwandelt, "DEFERRED TAX"^2 mit indizierten Begriffen in Kleinbuchstaben abgleichen.

Andere Abfrageformulare, z. B. Wildcard-, reguläre Ausdrücke und Fuzzy-Abfragen, verwenden unterschiedliche Analyseregeln. Durch das Hinzufügen einer Verstärkung werden diese Regeln nicht geändert. Weitere Informationen finden Sie in Phase 2: Lexikalische Analyse.

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 KI-Suche ist ein regulärer Ausdruck:

• Zwischen Schrägstrichen eingeschlossen /
• Nur Kleinschreibung

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 Infix-Matching. Verwenden Sie die regulärer Ausdruck-Syntax für Suffixvergleich.

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

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.

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 KI-Suche-Abfragen.

Stellen Sie sich eine Situation vor, in der die Suchabfrage terminal* Ergebnisse zurückgeben soll, die Ausdrücke wie terminate, termination und 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 KI-Suche 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.

Vorrang (Gruppierung)

Verwenden Sie Klammern, um zu steuern, welche Teile einer Abfrage zusammen ausgewertet werden. Zum Beispiel erfordert motel AND (wifi OR luxury)motel und mindestens einen der Begriffe in Klammern: wifi oder luxury.

Platzieren Sie ein Feldpräfix vor einer Klammergruppe, um diese gesamte Gruppe in einem Feld zu durchsuchen. Zum Beispiel sucht hotelAmenities:(wifi OR pool) nur im Feld wifi nach pool oder hotelAmenities.

Klammern steuern, wie AND und OR zusammenarbeiten. Sie erfordern nicht, dass Wörter nebeneinander oder in einer bestimmten Reihenfolge angezeigt werden. Verwenden Sie Anführungszeichen für dieses Verhalten. Um eine Gruppe zu erhöhen, platzieren Sie das Caret nach der schließenden Klammer, wie in hotelAmenities:(wifi OR pool)^2. Weitere Informationen finden Sie unter Boost-Umfang.

Abfragegrößenlimits

Azure KI-Suche 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

• Abfragebeispiele für die einfache Suche
• Abfragebeispiele für die vollständige Lucene-Suche
• Durchsuchen von Dokumenten
• OData-Ausdruckssyntax für Filter und Sortierung
• Einfache Abfragesyntax in Azure KI-Suche