Einfache Abfragesyntax in Azure AI Search

  • Artikel

Für Szenarien mit Volltextsuche implementiert Azure KI-Suche zwei Lucene-basierte Abfragesprachen, die jeweils auf einen Abfrageparser ausgerichtet sind. Der einfache Abfrageparser ist der standardmäßige Abfrageparser. Er behandelt gängige Anwendungsfälle und versucht, eine Anforderung zu interpretieren, auch wenn sie nicht perfekt zusammengesetzt ist. Der andere Parser ist der Lucene-Abfrageparser. Er unterstützt komplexere Abfragekonstruktionen.

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

Die Abfragesyntax für die beiden Parser gilt für Abfrageausdrücke, die im Parameter search einer Abfrageanforderung übergeben werden. Sie ist nicht zu verwechseln mit der OData-Syntax, die ihre eigene Syntax und eigene Regeln für die Ausdrücke filter und orderby in derselben Anforderung hat.

Obwohl die Simple Parser auf der Apache Lucene Simple Query Parser-Klasse basiert, schließt ihre Implementierung in Azure AI Search jedoch die Fuzzysuche aus. Wenn Sie die Fuzzysuche 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" unterscheidet, und gültige Syntax. Der Abfragetyp ist zwar unten festgelegt, aber dies ist die Standardeinstellung und kann weggelassen werden, sofern Sie nicht einen alternativen Typ wiederherstellen. Im folgenden Beispiel wird eine Suche nach unabhängigen Begriffen durchgeführt, wobei alle übereinstimmenden Dokumente das Wort „Pool“ enthalten müssen.

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

Der Parameter searchMode ist in diesem Beispiel relevant. Wenn boolesche Operatoren in der Abfrage enthalten sind, sollten Sie im Allgemeinen searchMode=all festlegen, um sicherzustellen, dass alle Kriterien berücksichtigt werden. Andernfalls können Sie die Standardeinstellung searchMode=any verwenden, die den Abruf gegenüber der Genauigkeit bevorzugt.

Weitere Beispiele finden Sie unter Einfache Beispiele für die Abfragesyntax. Ausführliche Informationen zur Abfrageanforderung und zu den entsprechenden Parametern finden Sie unter Durchsuchen von Dokumenten (REST-API).

Stichwortsuche nach Begriffen und Ausdrücken

Zeichenfolgen, die an den Parameter search übergeben werden, können Begriffe oder Ausdrücke in jeder unterstützten Sprache, boolesche Operatoren, Rangfolgenoperatoren, Platzhalter- oder Präfixzeichen für „Beginnt mit“-Abfragen, Escapezeichen und URL-Codierungszeichen enthalten. Das search ist optional. Wenn keine Angabe erfolgt, werden bei der Suche (search=* oder search=" ") die ersten 50 Dokumente in beliebiger Reihenfolge (ohne Rangfolge) zurückgegeben.

  • Eine Begriffsuche ist eine Abfrage mit einem oder mehreren Begriffen, von denen jeder der Begriffe als Übereinstimmung betrachtet wird.

  • Eine Ausdruckssuche ist ein in Anführungszeichen (" ") eingeschlossener exakter Ausdruck. Beispiel: Roach Motel (ohne Anführungszeichen) sucht nach Dokumenten, die Roach oder Motel enthalten, und zwar überall in beliebiger Reihenfolge; "Roach Motel" (mit Anführungszeichen) stimmt nur mit Dokumenten überein, die den gesamten Ausdruck zusammen und in dieser Reihenfolge enthalten (die lexikalische Analyse gilt weiterhin).

Abhängig von Ihrem Suchclient müssen Sie die Anführungszeichen in einer Ausdruckssuche möglicherweise mit Escapezeichen versehen. Beispiel: In einer POST-Anforderung wird eine Ausdruckssuche nach "Roach Motel" im Anforderungstext möglicherweise mit "\"Roach Motel\"" angegeben. Wenn Sie die Azure SDKs verwenden, werden die Anführungszeichen beim Serialisieren des Suchtexts durch den Suchclient mit Escapezeichen versehen. Ihr Suchausdruck kann als „Roach Motel“ gesendet werden.

Alle im Parameter search übergebenen Zeichenfolgen werden standardmäßig einer lexikalischen Analyse unterzogen. Sie müssen daher unbedingt das Tokenisierungsverhalten des von Ihnen verwendeten Analysetools verstehen. Wenn Abfrageergebnisse unerwartet ausfallen, kann der Grund dafür häufig darauf zurückzuführen sein, wie Begriffe zur Abfragezeit 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 Ausführung der Abfrage. Azure AI Search findet Dokumente, die einen oder alle der Begriffe enthalten, einschließlich aller Variationen, die bei der Analyse des Textes gefunden wurden.

So einfach es klingt, es gibt einen Aspekt der Abfrageausführung in der Azure AI Search, der möglicherweise zu unerwarteten Ergebnissen führt, welche die Suchergebnisse eher erhöhen als verringern, da mehr Begriffe und Operatoren zur Eingabezeichenkette hinzugefügt werden. Ob diese Erweiterung tatsächlich erfolgt, hängt von der Einbeziehung eines NOT-Operators ab, kombiniert mit einer searchMode-Parametereinstellung, die bestimmt, wie NOT in Form von AND- oder OR-Verhalten interpretiert wird. Weitere Informationen zur Verwendung des NOT-Operators finden Sie unter Boolesche Operatoren.

Boolesche Operatoren

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

Zeichen Beispiel Verbrauch
+ pool + ocean Ein AND-Vorgang. Beispiel: Mit pool + ocean wird vorgegeben, dass ein Dokument beide Begriffe enthalten muss.
| pool | ocean Ein OR-Vorgang 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 pool oder ocean oder beide Begriffe enthalten. Da OR der standardmäßige Konjunktionsoperator ist, könnten Sie ihn auch weglassen, d. h. pool ocean entspricht pool | ocean.
- pool – ocean Ein NOT-Vorgang gibt Übereinstimmungen für Dokumente zurück, die den Begriff ausschließen.

Der searchMode-Parameter in einer Abfrageanforderung steuert, ob ein Begriff mit dem NOT-Operator mit anderen Begriffen in der Abfrage per AND oder OR verknüpft wird (vorausgesetzt, dass es keinen booleschen Operator für die anderen Begriffe gibt). Gültige Werte sind any oder all.

searchMode=any erhöht die Trefferquote von Abfragen, weil mehr Ergebnisse einbezogen werden, und - wird standardmäßig als „OR NOT“ interpretiert. So stimmt beispielsweise pool - ocean mit Dokumenten überein, die entweder den Begriff pool enthalten oder die den Begriff ocean nicht enthalten.

searchMode=all erhöht die Genauigkeit von Abfragen, weil weniger Ergebnisse einbezogen werden und - standardmäßig als „AND NOT“ interpretiert wird. Bei searchMode=any gleicht die Abfrage pool - ocean beispielsweise Dokumente ab, die den Begriff „Pool“ enthalten, und alle Dokumente, die den Begriff „Ozean“ nicht enthalten. Dies ist wohl ein intuitiveres Verhalten für den --Operator. Daher sollten Sie die Verwendung von searchMode=all statt searchMode=any in Betracht ziehen, wenn Sie Suchen im Hinblick auf die Genauigkeit statt auf die Trefferquote optimieren möchten und Ihre Benutzer den --Operator häufig bei Suchen verwenden.

Berücksichtigen Sie bei der Entscheidung über eine searchMode-Einstellung die Benutzerinteraktionsmuster für Abfragen in verschiedenen Anwendungen. Benutzer, die nach Informationen suchen, beziehen eher einen Operator in eine Abfrage mit ein – im Gegensatz zu e-Commerce-Websites mit mehr integrierten Navigationsstrukturen.

Präfixabfragen

Fügen Sie bei „Beginnt mit“-Abfragen einen Suffixoperator (*) als Platzhalter für den Rest eines Begriffs hinzu. Eine Präfixabfrage muss mit mindestens einem alphanumerischen Zeichen beginnen, damit Sie den Suffixoperator hinzufügen können.

Zeichen Beispiel Verwendung
* lingui* ergibt eine Übereinstimmung mit „linguistisch“ oder „linguini“. Das Sternchen (*) stellt ein oder mehrere Zeichen beliebiger Länge dar, wobei die Groß-/Kleinschreibung ignoriert wird.

Ähnlich wie Filter sucht eine Präfixabfrage nach einer genauen Übereinstimmung. Daher wird die Relevanz nicht bewertet (alle Ergebnisse erhalten die Suchbewertung 1,0). Achten Sie darauf, dass Präfixabfragen insbesondere dann langsam sein können, wenn der Index groß ist und das Präfix aus einer kleinen Anzahl von Zeichen besteht. Eine alternative Methode, z. B. die Edge-N-Gramm-Tokenisierung, kann möglicherweise schneller ausgeführt werden. Begriffe, die die Präfixsuche verwenden, dürfen nicht länger als 1.000 Zeichen sein.

Die einfache Syntax unterstützt nur den Abgleich von Präfixen. Verwenden Sie bei Suffix- oder Infixabgleichen mit dem Ende oder der Mitte eines Begriffs die vollständige Lucene-Syntax für die Platzhaltersuche.

Escaping-Suchoperatoren

In der einfachen Syntax schließen die Suchoperatoren die folgenden Zeichen ein: + | " ( ) ' \

Wenn eines dieser Zeichen Teil eines Tokens im Index ist, versehen Sie es mit einem einzelnen umgekehrten Schrägstrich (\) als Escapezeichen in der Abfrage. Angenommen, Sie haben eine benutzerdefinierte Analyse für die gesamte begriffsbasierte Tokenisierung verwendet, und Ihr Index enthält die Zeichenfolge „Luxury+Hotel“. Fügen Sie ein Escapezeichen ein, um eine genaue Übereinstimmung für dieses Token zu erhalten: search=luxury\+hotel.

Zur Vereinfachung für typischere Fälle gibt es zwei Ausnahmen von dieser Regel, bei denen kein Escapezeichen erforderlich ist:

  • Der NOT-Operator - muss nur dann mit einem Escapezeichen versehen werden, wenn es sich um das erste Zeichen nach einem Leerzeichen handelt. Wenn das - in der Mitte auftritt (z. B. in 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), können Sie das Escapezeichen auslassen.

  • Der Suffix-Operator * muss nur dann mit einem Escapezeichen versehen werden, wenn es sich um das letzte Zeichen vor einem Leerzeichen handelt. Wenn das * in der Mitte auftritt (z. B. in 4*4=16), ist kein Escapezeichen erforderlich.

Hinweis

Die Lucene-Standardanalyse löscht bei der lexikalischen Analyse standardmäßig Bindestriche, Leerzeichen, kaufmännische Und-Zeichen und andere Zeichen in Wörtern und teilt die Wörter an diesen Stellen auf. Wenn Sonderzeichen in der Abfragezeichenfolge beibehalten werden müssen, benötigen Sie möglicherweise ein Analysetool, das sie im Index belässt. 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 KI-Suche zum Trennen von Parametern und Angeben von Werten dienen. 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 hin zu Emojis reichen. Viele Analysetools, einschließlich des Standardanalysetools, schließen Sonderzeichen während der Indizierung aus, was bedeutet, dass sie in Ihrem Index nicht dargestellt werden.

Wenn Sie eine spezielle Zeichendarstellung benötigen, können Sie ein Analysetool zuweisen, das diese beibehält:

  • Das Leerzeichen-Analysetool betrachtet jede durch Leerzeichen getrennte Zeichenfolge als Token (sodass das ❤-Emoji als Token betrachtet wird).

  • Ein Sprachanalysetool wie das Microsoft-Analysetool für englische Sprache (en.microsoft) würde auch die Zeichenfolge „$“ oder „€“ als Token betrachten.

Zur Bestätigung können Sie ein Analysetool testen, um zu ermitteln, welche Token für eine bestimmte Zeichenfolge generiert werden. Wie Sie vielleicht schon erwartet haben, erhalten Sie möglicherweise keine vollständige Tokenisierung von einem einzelnen Analysetool. Eine Problemumgehung besteht darin, mehrere Felder zu erstellen, die denselben Inhalt enthalten, aber mit unterschiedlichen Analysezuweisungen (z. B. description_en, description_fr usw. für Sprachanalysetools).

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 Escapesequenz %E2%9D%A4+ verwendet werden). Einige Webclients 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 Begriff „motel“ und entweder „wifi“ oder „luxury“ (oder beides) enthalten.

Abfragegrößenlimits

Wenn Ihre Anwendung programmgesteuert Suchabfragen generiert, sollten Sie durch den Entwurf sicherstellen, dass sie keine Abfragen von unbegrenzter Größe erzeugt.

  • Bei GET-Anforderungen darf die Länge der URL 8 KB nicht überschreiten.

  • Für POST (und alle anderen Anforderungen), in denen der Anforderungstext search und andere Parameter wie filter und orderby enthält, beträgt die maximale Größe 16 MB. Zusätzliche Grenzwerte sind unter anderem:

    • Die maximale Länge der Suchklausel beträgt 100.000 Zeichen.
    • Die maximale Anzahl von Klauseln in search (durch AND oder OR getrennte Ausdrücke) beträgt 1.024.
    • Die maximale Suchbegriffgröße beträgt 1000 Zeichen für die Präfixsuche.
    • Für die Größe der einzelnen Begriffe in einer Abfrage gilt zudem ein Grenzwert von ungefähr 32 KB.

Weitere Informationen zu Abfragegrenzwerten finden Sie unter API-Anforderungslimits.

Nächste Schritte

Wenn Sie Abfragen programmgesteuert erstellen werden, lesen Sie die Informationen unter Volltextsuche in Azure AI Search, um die Phasen der Abfrageverarbeitung und die Auswirkungen der Textanalyse zu verstehen.

Sie können auch die folgenden Artikel lesen, um mehr über das Erstellen von Abfragen zu erfahren: