Filter für die Schlüsselwortsuche in Azure KI-Suche

Ein Filter stellt wertbasierte Kriterien für das Einschließen oder Ausschließen von Inhalten vor der Abfrageausführung für die Stichwortsuche oder vor oder nach der Abfrageausführung für die Vektorsuche bereit. Filter werden auf Nichtvektorfelder angewendet, können aber in der Vektorsuche verwendet werden, wenn Dokumente Nichtvektorfelder enthalten. Zum Beispiel könnten Sie bei Indexen, die um zerlegte Inhalte organisiert sind, übergeordnete Felder oder Metadatenfelder haben, die gefiltert werden können.

In diesem Artikel wird die Filterung für die Stichwortsuche erläutert. Weitere Informationen zu Vektoren finden Sie unter Hinzufügen eines Filters in einer Vektorabfrage.

Ein Filter wird mithilfe der OData-Filterausdruckssyntax angegeben. Im Gegensatz zur Schlüsselwort- und Vektorsuche ist ein Filter nur erfolgreich, wenn die Übereinstimmung exakt ist.

Wann ein Filter verwendet werden soll

Filter sind grundlegende Elemente für mehrere Suchfunktionen, einschließlich der Geospatialsuche "In meiner Nähe suchen", der Faceted Navigation und der Sicherheitsfilter, die nur die Dokumente anzeigen, die ein Benutzer anzeigen darf. Wenn Sie eines dieser Erlebnisse implementieren, wird ein Filter benötigt. Es ist der Mit der Suchabfrage angefügte Filter, der die Geolocation-Koordinaten, die vom Benutzer ausgewählte Facetkategorie oder die Sicherheits-ID des Anforderers bereitstellt.

Zu den gängigen Szenarien gehören:

• Slice-Suchergebnisse basieren auf den Inhalten im Index. Aufgrund eines Schemas mit Hotelstandort, Kategorien und Annehmlichkeiten können Sie einen Filter erstellen, der explizit nach Kriterien übereinstimmt (in Seattle, auf dem Wasser, mit Sicht).

• Implementieren Sie eine Suchumgebung, die mit einer Filterabhängigkeit zusammenkommt:

  • Die Faceted-Navigation verwendet einen Filter, um die vom Benutzer ausgewählte Facetkategorie zurück zu übergeben.
  • Geospatialsuche nutzt einen Filter, um Koordinaten des aktuellen Standorts in „In meiner Nähe finden“-Apps und Funktionen zu übergeben, die innerhalb eines Bereichs oder nach Entfernung passen.
  • Sicherheitsfilter übergeben Sicherheitsbezeichner als Filterkriterien, wobei eine Übereinstimmung im Index als Proxy für Zugriffsrechte für das Dokument dient.

• Führen Sie eine "Zahlensuche" aus. Numerische Felder können abgerufen werden und können in Suchergebnissen angezeigt werden, sind aber nicht einzeln durchsuchbar (vorbehaltlich der Volltextsuche). Wenn Sie Auswahlkriterien basierend auf numerischen Daten benötigen, verwenden Sie einen Filter.

So werden Filter ausgeführt

Zur Abfragezeit akzeptiert ein Filterparser Kriterien als Eingabe, konvertiert den Ausdruck in atomische boolesche Ausdrücke, die als Struktur dargestellt werden, und wertet dann die Filterstruktur über filterbare Felder in einem Index aus.

Die Filterung erfolgt in Kombination mit der Suche, um zu bestimmen, welche Dokumente weiterverarbeitet werden sollen, für die Dokumentenabruf- und Relevanzbewertung. Bei Kombination mit einer Suchzeichenfolge reduziert der Filter effektiv den Rückrufsatz des nachfolgenden Suchvorgangs. Wenn sie allein verwendet wird (z. B. wenn die Abfragezeichenfolge leer ist, wo search=*leer ist), sind die Filterkriterien die einzige Eingabe.

Wie Filter definiert werden

Ein Filter gilt für Text- und numerischen (nicht vektorisierten) Inhalt in Feldern, die als filterable attribuiert sind.

Filter sind OData-Ausdrücke, die in der Filtersyntax, unterstützt von Azure KI-Suche, artikuliert werden.

Sie können einen Filter für jeden Suchvorgang angeben, aber der Filter selbst kann mehrere Felder, mehrere Kriterien enthalten und wenn Sie eine ismatch Funktion verwenden, mehrere Volltext-Suchausdrücke. In einem mehrteiligen Filterausdruck können Sie Prädikate in beliebiger Reihenfolge angeben (vorbehaltlich der Regeln der Operatorrangfolge). Es gibt keinen spürbaren Leistungsgewinn, wenn Sie versuchen, Prädikate in einer bestimmten Sequenz neu anzuordnen.

Einer der Grenzwerte für einen Filterausdruck ist die maximale Größenbeschränkung der Anforderung. Die gesamte Anforderung (einschließlich des Filters) kann maximal 16 MB für POST oder 8 KB für GET sein. Es gibt auch einen Grenzwert für die Anzahl der Klauseln in Ihrem Filterausdruck. Eine gute Faustregel ist, dass Sie, wenn Sie Hunderte von Klauseln haben, riskieren, den Grenzwert zu erreichen. Es wird empfohlen, Ihre Anwendung so zu entwerfen, dass sie keine Filter von ungebundener Größe generiert.

Die folgenden Beispiele stellen prototypische Filterdefinitionen in mehreren APIs dar.

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2025-09-01
{
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate lt 150.0)",
    "select": "HotelId, HotelName, Rooms/Description, Rooms/BaseRate"
}

options = new SearchOptions()
{
    Filter = "Rating gt 4",
    OrderBy = { "Rating desc" }
};

Filtermuster

Die folgenden Beispiele veranschaulichen mehrere Verwendungsmuster für Filterszenarien. Weitere Ideen finden Sie unter OData-Ausdruckssyntaxbeispiele>.

• Eigenständiger $filter, ohne eine Abfragezeichenfolge, nützlich, wenn der Filterausdruck fähig ist, interessante Dokumente vollständig zu qualifizieren. Ohne Eine Abfragezeichenfolge gibt es keine lexikalische oder sprachliche Analyse, keine Bewertung und keine Rangfolge. Beachten Sie, dass die Suchzeichenfolge nur ein Sternchen ist, was bedeutet, dass "alle Dokumente übereinstimmen".

  {
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Honolulu"
  }
  

• Kombination aus Abfragezeichenfolge und $filter, wobei der Filter die Teilmenge erstellt, und die Abfragezeichenfolge stellt die Ausdruckseingaben für die Volltextsuche über die gefilterte Teilmenge bereit. Durch das Hinzufügen von Begriffen (Kinos in Laufnähe) führt zu Suchergebnissen, wobei die Dokumente, die am besten mit den Begriffen übereinstimmen, höher bewertet werden. Die Verwendung eines Filters mit einer Abfragezeichenfolge ist das am häufigsten verwendete Verwendungsmuster.

  {
    "search": "walking distance theaters",
    "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Seattle'"
  }
  
  

• Zusammengesetzte Abfragen, getrennt durch "oder", jeweils mit eigenen Filterkriterien (z. B. 'Beagles' in 'Hund' oder 'Siamkatze' in 'Katze'). Ausdrücke, die mit or kombiniert werden, werden einzeln ausgewertet, wobei die Vereinigung der Dokumente, die mit jedem Ausdruck übereinstimmen, in der Antwort zurückgesendet wird. Dieses Verwendungsmuster wird über die search.ismatchscoring Funktion erreicht. Sie können auch die Nichtbewertungsvariante verwenden. search.ismatch

  # Match on hostels rated higher than 4 OR 5-star motels.
  $filter=search.ismatchscoring('hostel') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 5
  
  # Match on 'luxury' or 'high-end' in the description field OR on category exactly equal to 'Luxury'.
  $filter=search.ismatchscoring('luxury | high-end', 'Description') or Category eq 'Luxury'&$count=true
  

  Es ist auch möglich, die Volltextsuche mit search.ismatchscoring mit and-Filtern anstelle von or zu kombinieren, aber dies entspricht funktionell der Verwendung der Parameter search und $filter in einer Suchanforderung. Die folgenden beiden Abfragen erzeugen z. B. dasselbe Ergebnis:

  $filter=search.ismatchscoring('pool') and Rating ge 4
  
  search=pool&$filter=Rating ge 4
  

Feldanforderungen für die Filterung

In der REST-API ist filterbar standardmäßig für einfache Felder aktiviert . Filterbare Felder erhöhen die Indexgröße; achten Sie darauf, "filterable": false für Felder festzulegen, die Sie nicht tatsächlich in einem Filter verwenden möchten. Weitere Informationen zu Einstellungen für Felddefinitionen finden Sie unter Create Index.

In den Azure-SDKs ist filterbar standardmäßig deaktiviert. Sie können ein Feld filtern, indem Sie die IsFilterable-Eigenschaft des entsprechenden SearchField-Objekts auf truefestlegen. Im nächsten Beispiel wird das Attribut für die Rating Eigenschaft einer Modellklasse festgelegt, die der Indexdefinition zugeordnet ist.

[SearchField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
public double? Rating { get; set; }

Erstellen eines vorhandenen Felds, das gefiltert werden kann

Vorhandene Felder können nicht so geändert werden, dass sie gefiltert werden können. Stattdessen müssen Sie ein neues Feld hinzufügen oder den Index neu erstellen. Weitere Informationen zum Neuerstellen eines Indexes oder neuerstellen von Feldern finden Sie unter Wie sie einen Azure KI-Suche Index neu erstellen.

Grundlagen des Textfilters

Textfilter vergleichen String-Felder mit Literalen, die Sie im Filter angeben: $filter=Category eq 'Resort and Spa'

Im Gegensatz zur Volltextsuche gibt es keine lexikalische Analyse oder Worttrennung für Textfilter, sodass Vergleiche nur für genaue Übereinstimmungen gelten. Angenommen, ein Feld f enthält "Sonnentag", $filter=f eq 'sunny' stimmt nicht überein, aber $filter=f eq 'sunny day' wird übereinstimmen.

Textzeichenfolgen sind case-sensitive, was bedeutet, dass Textfilter standardmäßig groß- und kleinschreibungssensitiv sind. Beispielsweise $filter=f eq 'Sunny day' wird "sonniger Tag" nicht gefunden. Sie können jedoch einen Normalisierer verwenden, damit die Filterung nicht auf die Groß-/Kleinschreibung achtet.

Ansätze zum Filtern nach Text

Grundlagen des numerischen Filters

Numerische Felder befinden sich nicht searchable im Kontext der Volltextsuche. Nur Zeichenfolgen unterliegen der Volltextsuche. Wenn Sie beispielsweise 99,99 als Suchbegriff eingeben, erhalten Sie keine Artikel mit einem Preis von 99,99 $. Stattdessen werden Elemente mit der Zahl 99 in Zeichenfolgenfeldern des Dokuments angezeigt. Wenn Sie also numerische Daten haben, wird davon ausgegangen, dass Sie sie für Filter verwenden, einschließlich Bereiche, Facets, Gruppen usw.

Dokumente, die numerische Felder (Preis, Größe, SKU, ID) enthalten, stellen diese Werte in Suchergebnissen bereit, wenn das Feld markiert retrievableist. Der folgende Punkt ist, dass die Volltextsuche selbst nicht auf numerische Feldtypen anwendbar ist.

Nächste Schritte

Probieren Sie zunächst Search-Explorer im Azure-Portal aus, um Abfragen mit parametern $filter zu übermitteln. Der Immobilienbeispielindex bietet interessante Ergebnisse für die folgenden gefilterten Abfragen, wenn Sie sie in die Suchleiste einfügen:

# Geo-filter returning documents within 5 kilometers of Redmond, Washington state
# Use $count=true to get a number of hits returned by the query
# Use $select to trim results, showing values for named fields only
# Use search=* for an empty query string. The filter is the sole input

search=*&$count=true&$select=description,city,postCode&$filter=geo.distance(location,geography'POINT(-122.121513 47.673988)') le 5

# Numeric filters use comparison like greater than (gt), less than (lt), not equal (ne)
# Include "and" to filter on multiple fields (baths and bed)
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=baths gt 3 and beds gt 4

# Text filters can also use comparison operators
# Wrap text in single or double quotes and use the correct case
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=city gt 'Seattle'

Weitere Beispiele finden Sie unter OData-Filterausdruckssyntaxbeispiele>.

Siehe auch

• Wie die Volltextsuche in Azure KI-Suche
• REST-API für Dokumente durchsuchen
• Einfache Abfragesyntax
• Lucene-Abfragesyntax
• Unterstützte Datentypen