Einfache Abfragesyntax in Azure KI-Suche

Für Volltextsuchszenarien implementiert Azure KI-Suche zwei Lucene-basierte Abfragesprachen, die jeweils an einem Abfrageparser ausgerichtet sind. Der Einfache Abfrageparser ist die Standardeinstellung. Es behandelt häufige Anwendungsfälle und Versuche, eine Anforderung zu interpretieren, auch wenn sie nicht perfekt zusammengesetzt ist. Der andere Parser ist Lucene Query Parser und unterstützt komplexere Abfragekonstruktionen.

Dieser Artikel ist die Abfragesyntaxreferenz für den einfachen Abfrageparser.

Die Abfragesyntax für beide Parser bezieht sich auf Abfrageausdrücke, die im search Parameter eines Abfrageantrags übergeben werden. Sie darf nicht mit der OData-Syntax verwechselt werden, die ihre eigene Syntax und Regeln für filter und orderby Ausdrücke in derselben Anfrage hat.

Obwohl der einfache Parser auf der Apache Lucene Simple Query Parser-Klasse basiert, schließt die Implementierung in Azure KI-Suche fuzzy search aus. Wenn Sie Fuzzy-Suche benötigen, sollten Sie stattdessen die alternative vollständige Lucene-Abfragesyntax in Betracht ziehen.

Beispiel (einfache Syntax)

Dieses Beispiel zeigt eine einfache Abfrage, die sich durch "queryType": "simple" und eine gültige Syntax auszeichnet. Obwohl der Abfragetyp unten festgelegt ist, handelt es sich um die Standardeinstellung und er kann weggelassen werden, es sei denn, Sie kehren von einem alternativen Typ zurück. Im folgenden Beispiel handelt es sich um eine Suche über unabhängige Ausdrücke mit der Anforderung, dass alle übereinstimmenden Dokumente "pool" enthalten.

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2025-09-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

Der searchMode Parameter ist in diesem Beispiel relevant. Immer wenn boolesche Operatoren in der Abfrage enthalten sind, sollten Sie im Allgemeinen searchMode=all konfigurieren, dass alle Kriterien übereinstimmen. Andernfalls können Sie die Standardeinstellung searchMode=any verwenden, die den Rückruf vor Genauigkeit begünstigt.

Weitere Beispiele finden Sie in den Beispielen für einfache Abfragesyntax. Ausführliche Informationen zu abfrageanforderung und -parametern finden Sie unter Search Documents (REST API).For details about the query request and parameters, see Search Documents (REST API).

Stichwortsuche nach Begriffen und Ausdrücken

An den search Parameter übergebene Zeichenfolgen können Begriffe oder Ausdrücke in jeder unterstützten Sprache, boolesche Operatoren, Vorrangoperatoren, Wildcard- oder Präfixzeichen für "beginnt mit"-Abfragen, Escapezeichen und URL-Codierungszeichen enthalten. Der search Parameter ist optional. Nicht angegeben, Suchvorgänge (search=* oder search=" ") geben die obersten 50 Dokumente in beliebiger (nicht bewerteter) Reihenfolge zurück.

  • Bei einer Begriffssuche handelt es sich um eine Abfrage eines oder mehrerer Ausdrücke, bei denen eine der Ausdrücke als Übereinstimmung betrachtet wird.

  • Eine Begriffssuche ist ein exakter Ausdruck, der in Anführungszeichen " "eingeschlossen ist. Zum Beispiel, während Roach Motel (ohne Anführungszeichen) nach Dokumenten suchen würde, die Roach und/oder Motel in beliebiger Reihenfolge überall enthalten, werden "Roach Motel" (mit Anführungszeichen) nur Dokumente finden, die den gesamten Ausdruck in dieser Reihenfolge enthalten (die lexikalische Analyse gilt weiterhin).

Je nach Suchclient müssen Sie möglicherweise die Anführungszeichen in einer Phrasensuche maskieren oder ersetzen. In einer POST-Anforderung kann beispielsweise eine Begriffssuche "Roach Motel" im Anforderungskörper als "\"Roach Motel\"" angegeben werden. Wenn Sie das Azure SDKs verwenden, gibt der Suchclient die Anführungszeichen aus, wenn er den Suchtext serialisiert. Ihr Suchbegriff kann als "Roach Motel" gesendet werden.

Standardmäßig werden alle im search Parameter übergebenen Zeichenfolgen lexikalisch analysiert. Stellen Sie sicher, dass Sie das Tokenisierungsverhalten des verwendeten Analyzers kennen. Oft, wenn Abfrageergebnisse unerwartet sind, liegt der Grund darin, wie Begriffe zum Zeitpunkt der Abfrage tokenisiert werden. Sie können die Tokenisierung für bestimmte Zeichenfolgen testen , um die Ausgabe zu bestätigen.

Jede Texteingabe mit einem oder mehreren Begriffen gilt als gültiger Ausgangspunkt für die Abfrageausführung. Azure KI-Suche stimmt Dokumente überein, die einen oder alle der Begriffe enthalten, einschließlich jeglicher Variationen, die während der Analyse des Textes gefunden wurden.

So einfach dies klingt, gibt es einen Aspekt der Abfrageausführung in Azure KI-Suche, der könnte unerwartete Ergebnisse erzeugen und die Suchergebnisse erhöhen, anstatt sie zu verringern, da der Eingabezeichenfolge mehr Begriffe und Operatoren hinzugefügt werden. Ob diese Erweiterung tatsächlich auftritt, hängt von der Einbeziehung eines NOT-Operators ab, kombiniert mit einer searchMode Parametereinstellung, die bestimmt, wie NOT in Bezug auf AND oder OR Verhalten interpretiert wird. Weitere Informationen finden Sie im NOT Operator unter booleschen Operatoren.

Boolesche Operatoren

Sie können boolesche Operatoren in eine Abfragezeichenfolge einbetten, um die Genauigkeit einer Übereinstimmung zu verbessern. In der einfachen Syntax sind boolesche Operatoren zeichenbasiert. Textoperatoren, z. B. das Wort AND, werden nicht unterstützt.

Charakter Beispiel Verwendung
+ pool + ocean Ein AND Vorgang. Legt beispielsweise fest, pool + ocean dass ein Dokument beide Begriffe enthalten muss.
| pool | ocean Ein OR Vorgang findet eine Übereinstimmung, wenn entweder der eine oder der andere Begriff gefunden wird. Im Beispiel gibt das Abfragemodul eine Übereinstimmung für Dokumente zurück, die entweder pool oder ocean oder beide enthalten. Da OR der standardmäßige Konjunktionsoperator ist, können Sie ihn auch weglassen, sodass pool ocean dem Äquivalent von pool | ocean entspricht.
- pool – ocean Ein NOT Vorgang gibt Übereinstimmungen für Dokumente zurück, die den Begriff ausschließen.

Der searchMode-Parameter in einer Abfrage steuert, ob ein Ausdruck mit dem NOT-Operator in die Abfrage mit anderen Ausdrücken integriert oder kombiniert wird (vorausgesetzt, es gibt keine booleschen Operatoren für die anderen Ausdrücke). Gültige Werte enthalten any oder all.

searchMode=any erhöht den Rückruf von Abfragen, indem mehr Ergebnisse eingeschlossen werden, und standardmäßig - als "ODER NICHT" interpretiert wird. Beispielsweise entspricht pool - ocean Dokumenten, die entweder den Ausdruck pool enthalten oder solchen, die den Ausdruck ocean nicht enthalten.

searchMode=all erhöht die Genauigkeit von Abfragen durch die Einbeziehung von weniger Ergebnissen, und standardmäßig wird - als "UND NICHT" interpretiert. Mit der Abfrage searchMode=any werden zum Beispiel Dokumente gefunden, die den Begriff "Pool" enthalten und alle Dokumente, die nicht den Begriff "Ozean" enthalten. Dies ist wohl ein intuitiveres Verhalten für den - Operator. Daher sollten Sie die Verwendung von searchMode=all anstelle von searchMode=any in Betracht ziehen, wenn Sie Suchen eher auf Genauigkeit als auf Recall optimieren möchten und Ihre Benutzer den --Operator häufig in Suchvorgängen verwenden.

Berücksichtigen Sie bei der Entscheidung für eine searchMode Einstellung die Benutzerinteraktionsmuster für Abfragen in verschiedenen Anwendungen. Benutzer, die nach Informationen suchen, sind wahrscheinlicher, dass ein Operator in eine Abfrage einbezogen wird, im Gegensatz zu E-Commerce-Websites, die über integrierte Navigationsstrukturen verfügen.

Präfixabfragen

Fügen Sie für 'beginnt mit'-Abfragen einen Suffixoperator (*) als Platzhalter für den Rest eines Ausdrucks hinzu. Eine Präfixabfrage muss mit mindestens einem Nur-Text-Zeichen beginnen, bevor Sie den Suffixoperator hinzufügen können.

Charakter Beispiel Verwendung
* lingui* wird mit "linguistik" oder "linguini" übereinstimmen Das Sternchen (*) stellt ein oder mehrere Zeichen beliebiger Länge dar, wobei die Groß-/Kleinschreibung ignoriert wird.

Ähnlich wie bei Filtern sucht eine Präfixabfrage nach einer genauen Übereinstimmung. Daher gibt es keine Relevanzbewertung (alle Ergebnisse erhalten eine Suchbewertung von 1,0). Beachten Sie, dass Präfixabfragen langsam sein können, insbesondere, wenn der Index groß ist und das Präfix aus einer kleinen Anzahl von Zeichen besteht. Eine alternative Methodik, z. B. edge-n-Gram-Tokenisierung, kann schneller ausgeführt werden. Ausdrücke, die die Präfixsuche verwenden, dürfen maximal 1000 Zeichen lang sein.

Einfache Syntax unterstützt nur Präfixabgleich. Verwenden Sie für suffix- oder infix-Abgleich mit dem Ende oder der Mitte eines Begriffs die vollständige Lucene-Syntax für die Wildcardsuche.

Escapen von Suchoperatoren

In der einfachen Syntax enthalten Suchoperatoren die folgenden Zeichen: + | " ( ) ' \

Wenn eines dieser Zeichen Teil eines Tokens im Index ist, maskieren Sie es, indem Sie einen einzelnen umgekehrten Schrägstrich (\) in der Abfrage voranstellen. Angenommen, Sie haben einen benutzerdefinierten Analyzer für die tokenisierung ganzer Begriffe verwendet, und Ihr Index enthält die Zeichenfolge "Luxury+Hotel". Um eine genaue Übereinstimmung für dieses Token zu erhalten, fügen Sie ein Escapezeichen ein: search=luxury\+hotel.

Um die Dinge für die typischeren Fälle einfach zu machen, gibt es zwei Ausnahmen für diese Regel, bei der die Flucht nicht erforderlich ist:

  • Der NOT-Operator - muss nur maskiert werden, wenn er das erste Zeichen nach einem Leerzeichen ist. Wenn das - in der Mitte (z. B. in 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD) erscheint, können Sie das Escaping überspringen.

  • Der Suffixoperator * muss nur maskiert werden, wenn er das letzte Zeichen vor einem Leerzeichen ist. Wenn die * Anzeige in der Mitte (z. B. in 4*4=16) erfolgt, ist keine Flucht erforderlich.

Hinweis

Standardmäßig entfernt und teilt der Standard-Analysator Wörter an Bindestrichen, Leerraum, Et-Zeichen und anderen Zeichen während der lexikalischen Analyse. Wenn Sie sonderzeichen in der Abfragezeichenfolge beibehalten müssen, benötigen Sie möglicherweise einen Analyzer, der sie im Index behält. Einige Optionen umfassen den Microsoft-Sprachanalysator, der Bindestrichwörter beibehält, oder einen benutzerdefinierten Analysator für komplexere Muster. Weitere Informationen finden Sie unter Teilbegriffe, Muster und Sonderzeichen.

Codieren unsicherer und reservierter Zeichen in URLs

Stellen Sie sicher, dass alle unsicheren und reservierten Zeichen in einer URL codiert sind. Beispielsweise ist "#" ein unsicheres Zeichen, da es sich um einen Fragment-/Ankerbezeichner in einer URL handelt. Das Zeichen muss codiert %23 werden, wenn es in einer URL verwendet wird. '& ' und '=' sind Beispiele für reservierte Zeichen, während sie Parameter trennen und Werte in Azure KI-Suche angeben. Weitere Informationen finden Sie unter RFC1738: Uniform Resource Locators (URL).

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

Sonderzeichen

Sonderzeichen können von Währungssymbolen wie "$" oder "€" bis zu Emojis reichen. Viele Analyzer, einschließlich der Standard-Standardanalyse, schließen Sonderzeichen während der Indizierung aus, was bedeutet, dass sie nicht in Ihrem Index dargestellt werden.

Wenn Sie eine Sonderzeichendarstellung benötigen, können Sie einen Analyzer zuweisen, der sie behält:

  • Der Whitespace Analyzer betrachtet jede Zeichensequenz, die durch Leerzeichen getrennt ist, als Token (sodass das Emoji "❤" als Token betrachtet wird).

  • Ein Sprachanalysator, z. B. der Microsoft-Englisch-Analysator (en.microsoft), würde die Zeichenfolge "$" oder "€" als Token verwenden.

Zur Bestätigung können Sie einen Analyzer testen , um zu sehen, welche Token für eine bestimmte Zeichenfolge generiert werden. Wie Sie erwarten, erhalten Sie möglicherweise keine vollständige Tokenisierung von einem einzigen Analyzer. Eine Problemumgehung besteht darin, mehrere Felder zu erstellen, die denselben Inhalt enthalten, jedoch mit unterschiedlichen Analyser-Zuweisungen (z. B. description_en, description_fr und so weiter für Sprach-Analyser).

Stellen Sie bei Verwendung von Unicode-Zeichen sicher, dass Symbole in der Abfrage-URL ordnungsgemäß escapet sind (z. B. für "❤" würde die Escapesequenz %E2%9D%A4+verwendet). Einige Webclients führen diese Übersetzung automatisch aus.

Rangfolge (Gruppierung)

Sie können Klammern verwenden, um Unterabfragen zu erstellen, einschließlich der Verwendung von Operatoren innerhalb des Klammerausdrucks. Sucht z. B. nach Dokumenten, motel+(wifi|luxury) die den Begriff "Motel" und entweder "WIFI" oder "Luxus" (oder beides) enthalten.

Grenzwerte für die Abfragegröße

Wenn Ihre Anwendung Suchabfragen programmgesteuert generiert, empfehlen wir, sie so zu entwerfen, dass keine Abfragen mit ungebundener Größe generiert werden.

  • Für GET darf die Länge der URL 8 KB nicht überschreiten.

  • Für POST (und alle anderen Anforderungen), bei denen der Textkörper der Anforderung search und andere Parameter wie filter und orderby enthält, beträgt die maximale Größe 16 MB. Zu den zusätzlichen Grenzwerten gehören:

    • Die maximale Länge der Suchklausel beträgt 100.000 Zeichen.
    • Die maximale Anzahl von Klauseln in search (ausdrücke getrennt durch AND oder OR) ist 1024.
    • Die maximale Suchbegriffgröße beträgt 1000 Zeichen für die Präfixsuche.
    • Es gibt auch eine Beschränkung von ca. 32 KB für die Größe eines einzelnen Ausdrucks in einer Abfrage.

Weitere Informationen zu Abfragegrenzwerten finden Sie unter API-Anforderungsgrenzwerte.

Nächste Schritte

Wenn Sie Abfragen programmgesteuert erstellen, überprüfen Sie Full-Textsuche in Azure KI-Suche, um die Phasen der Abfrageverarbeitung und die Auswirkungen der Textanalyse zu verstehen.

Sie können auch die folgenden Artikel lesen, um mehr über die Abfrageerstellung zu erfahren:

  • Last updated on