Filter in Azure SearchFilters in Azure Search

Ein Filter liefert Kriterien für die Auswahl von Dokumenten, die in einer Azure Search-Abfrage verwendet werden.A filter provides criteria for selecting documents used in an Azure Search query. Bei einer ungefilterten Suche werden alle Dokumente im Index durchsucht.Unfiltered search includes all documents in the index. Ein Filter begrenzt eine Suchabfrage auf eine Teilmenge von Dokumenten.A filter scopes a search query to a subset of documents. Beispielsweise kann ein Filter die Volltextsuche auf Produkte einer bestimmten Marke oder mit einer Farbe beschränken, wenn der Preis über einer bestimmten Schwelle liegt.For example, a filter could restrict full text search to just those products having a specific brand or color, at price points above a certain threshold.

Einige Suchumgebungen setzen Filterbedingungen im Rahmen der Implementierung durch. Sie können jedoch jederzeit Filter verwenden, wenn Sie die Suche mithilfe wertbasierter Kriterien einschränken möchten (z. B. die Suche nach dem Produkttyp "Bücher" auf die Kategorie "Sachbuch" von "Kiepenheuer & Witsch" begrenzen).Some search experiences impose filter requirements as part of the implementation, but you can use filters anytime you want to constrain search using value-based criteria (scoping search to product type "books" for category "non-fiction" published by "Simon & Schuster").

Wenn Sie stattdessen gezielt nach bestimmten Datenstrukturen suchen möchten (d.h. die Suche auf das Feld "Kundenrezensionen" begrenzen), gibt es alternative Methoden, die nachfolgend beschrieben werden.If instead your goal is targeted search on specific data structures (scoping search to a customer-reviews field), there are alternative methods, described below.

Einsatzmöglichkeiten von FilternWhen to use a filter

Filter sind die Grundlage mehrerer Suchoberflächen, darunter „In meiner Nähe finden“, Facettennavigation und Sicherheitsfilter, die nur die Dokumente anzeigen, die ein Benutzer sehen darf.Filters are foundational to several search experiences, including "find near me", faceted navigation, and security filters that show only those documents a user is allowed to see. Wenn Sie eine dieser Oberflächen implementieren, ist ein Filter erforderlich.If you implement any one of these experiences, a filter is required. Es ist der an die Suchabfrage angefügte Filter, der die Geolocationkoordinaten, die vom Benutzer ausgewählte Facettenkategorie oder die Sicherheits-ID des Anforderers angibt.It's the filter attached to the search query that provides the geolocation coordinates, the facet category selected by the user, or the security ID of the requestor.

Es folgen Beispielszenarien:Example scenarios include the following:

  1. Verwenden Sie einen Filter, um Ihren Index anhand von Datenwerten im Index zu segmentieren.Use a filter to slice your index based on data values in the index. Anhand eines Schemas mit Stadt, Gebäudetyp und Ausstattung können Sie einen Filter erstellen, um Dokumente explizit auszuwählen, die Ihren Kriterien entsprechen (in Seattle, Eigentumswohnungen, am Wasser).Given a schema with city, housing type, and amenities, you might create a filter to explicitly select documents that satisfy your criteria (in Seattle, condos, waterfront).

    Eine Volltextsuche mit den gleichen Eingaben führt oft zu ähnlichen Ergebnissen, doch ein Filter ist insofern präziser, als er eine exakte Übereinstimmung des Filterbegriffs mit dem Inhalt in Ihrem Index fordert.Full text search with the same inputs often produces similar results, but a filter is more precise in that it requires an exact match of the filter term against content in your index.

  2. Verwenden Sie einen Filter, wenn die Suchoberfläche eine Filteranforderung aufweist:Use a filter if the search experience comes with a filter requirement:

    • Facettennavigation verwendet einen Filter, um die vom Benutzer gewählte Facettenkategorie zurückzugeben.Faceted navigation uses a filter to pass back the facet category selected by the user.
    • Die geografische Suche verwendet einen Filter, um Koordinaten des aktuellen Standorts an Apps des Typs „In meiner Nähe finden“ zu übergeben.Geo-search uses a filter to pass coordinates of the current location in "find near me" apps.
    • Sicherheitsfilter übergeben Sicherheitsbezeichner als Filterkriterien, wobei eine Übereinstimmung im Index als Proxy für Zugriffsrechte für das Dokument dient.Security filters pass security identifiers as filter criteria, where a match in the index serves as a proxy for access rights to the document.
  3. Verwenden Sie einen Filter, wenn Suchkriterien für ein numerisches Feld gewünscht sind.Use a filter if you want search criteria on a numeric field.

    Numerische Felder sind im Dokument abrufbar und können in Suchergebnissen angezeigt werden, sind aber (bei einer Volltextsuche) nicht einzeln durchsuchbar.Numeric fields are retrievable in the document and can appear in search results, but they are not searchable (subject to full text search) individually. Wenn Sie Auswahlkriterien basierend auf numerischen Daten benötigen, verwenden Sie einen Filter.If you need selection criteria based on numeric data, use a filter.

Alternative Methoden zum Verkleinern des SuchbereichsAlternative methods for reducing scope

Wenn Sie Ihre Suchergebnissen eingrenzen möchten, sind Filter nicht die einzige Möglichkeit.If you want a narrowing effect in your search results, filters are not your only choice. Je nach Ziel können diese Alternativen besser geeignet sein:These alternatives could be a better fit, depending on your objective:

  • searchFields-Abfrageparameter binden die Suche an bestimmte Felder.searchFields query parameter pegs search to specific fields. Wenn Ihr Index beispielsweise getrennte Felder für englische und spanische Beschreibungen enthält, können Sie mithilfe von „searchFields“ festlegen, welche Felder für die Volltextsuche verwendet werden sollen.For example, if your index provides separate fields for English and Spanish descriptions, you can use searchFields to target which fields to use for full text search.

  • Der Parameter $select dient zur Angabe, welche Felder in ein Resultset aufgenommen werden sollen, wobei die Antwort vor dem Senden an die aufrufende Anwendung effektiv angepasst wird.$select parameter is used to specify which fields to include in a result set, effectively trimming the response before sending it to the calling application. Durch diesen Parameter wird weder die Abfrage optimiert noch die Dokumentsammlung verkleinert, aber wenn eine kleinere Antwort Ihr Ziel ist, sollten Sie diesen Parameter als Option in Betracht ziehen.This parameter does not refine the query or reduce the document collection, but if a smaller response is your goal, this parameter is an option to consider.

Weitere Informationen zu beiden Parametern finden Sie unter Dokumente durchsuchen > Anforderung > Abfrageparameter.For more information about either parameter, see Search Documents > Request > Query parameters.

Ausführen von FilternHow filters are executed

Zur Abfragezeit akzeptiert ein Filterparser Kriterien als Eingabe, wandelt den Ausdruck in unteilbare boolesche Ausdrücke um, die als Struktur dargestellt werden, und wertet dann die Filterstruktur über filterbare Felder in einem Index aus.At query time, a filter parser accepts criteria as input, converts the expression into atomic Boolean expressions represented as a tree, and then evaluates the filter tree over filterable fields in an index.

Die Filterung erfolgt zusammen mit Suche und bestimmt, welche Dokumente für den Dokumentabruf und die Relevanzbewertung in die nachgelagerte Verarbeitung einbezogen werden sollen.Filtering occurs in tandem with search, qualifying which documents to include in downstream processing for document retrieval and relevance scoring. In Kombination mit einem Suchbegriff reduziert der Filter wirkungsvoll die Abrufmenge des nachfolgenden Suchvorgangs.When paired with a search string, the filter effectively reduces the recall set of the subsequent search operation. Bei alleiniger Verwendung (z. B. wenn die Abfragezeichenfolge bei search=* leer ist) ist das Filterkriterium die einzige Eingabe.When used alone (for example, when the query string is empty where search=*), the filter criteria is the sole input.

Definieren von FilternDefining filters

Filter sind OData-Ausdrücke, die mittels einer in Azure Search unterstützten Teilmenge der OData V4-Syntax definiert werden.Filters are OData expressions, articulated using a subset of OData V4 syntax supported in Azure Search.

Sie können für jeden Suchvorgang einen Filter angeben. Doch der Filter selbst kann mehrere Felder, mehrere Kriterien und, wenn Sie eine ismatch-Funktion verwenden, mehrere Volltextsuchausdrücke enthalten.You can specify one filter for each search operation, but the filter itself can include multiple fields, multiple criteria, and if you use an ismatch function, multiple full-text search expressions. Bei einem mehrteiligen Filterausdruck können Sie Prädikate in beliebiger Reihenfolge angeben (gemäß den Regeln der Rangfolge von Operatoren).In a multi-part filter expression, you can specify predicates in any order (subject to the rules of operator precedence). Es ergibt sich kein nennenswerter Leistungszuwachs, wenn Sie versuchen, Prädikate in einer bestimmten Reihenfolge neu anzuordnen.There is no appreciable gain in performance if you try to rearrange predicates in a particular sequence.

Einer der Grenzwerte für einen Filterausdruck ist die maximale Größe der Anforderung.One of the limits on a filter expression is the maximum size limit of the request. Die gesamte Anforderung kann einschließlich Filter eine maximale Größe von 16 MB für POST- bzw. 8 KB für GET-Vorgänge haben.The entire request, inclusive of the filter, can be a maximum of 16 MB for POST, or 8 KB for GET. Die Anzahl der Klauseln in Ihrem Filterausdruck ist ebenfalls begrenzt.There is also a limit on the number of clauses in your filter expression. Gut merken lässt sich, dass Sie bei Hunderten von Klauseln Gefahr laufen, an den Grenzwert zu erreichen.A good rule of thumb is that if you have hundreds of clauses, you are at risk of running into the limit. Wir empfehlen Ihnen, Ihre Anwendung so zu entwerfen, dass sie keine Filter unbegrenzter Größe erzeugt.We recommend designing your application in such a way that it does not generate filters of unbounded size.

Die folgenden Beispiele veranschaulichen prototypische Filterdefinitionen in mehrere APIs.The following examples represent prototypical filter definitions in several APIs.

# Option 1:  Use $filter for GET
GET https://[service name].search.windows.net/indexes/hotels/docs?search=*&$filter=baseRate lt 150&$select=hotelId,description&api-version=2019-05-06

# Option 2: Use filter for POST and pass it in the request body
POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2019-05-06
{
    "search": "*",
    "filter": "baseRate lt 150",
    "select": "hotelId,description"
}
    parameters =
        new SearchParameters()
        {
            Filter = "baseRate lt 150",
            Select = new[] { "hotelId", "description" }
        };

    var results = searchIndexClient.Documents.Search("*", parameters);

Filtern von VerwendungsmusternFilter usage patterns

Die folgenden Beispiele veranschaulichen einige Verwendungsmuster für Filterszenarios.The following examples illustrate several usage patterns for filter scenarios. Weitere Vorschläge finden Sie unter OData-Ausdruckssyntax > Beispiele.For more ideas, see OData expression syntax > Examples.

  • Eigenständige $filter-Filter ohne Abfragezeichenfolge; nützlich, wenn der Filterausdruck Dokumente von Interesse vollständig qualifizieren kann.Standalone $filter, without a query string, useful when the filter expression is able to fully qualify documents of interest. Ohne Abfragezeichenfolge gibt es keine lexikalische oder linguistische Analyse, Bewertung und Rangfolge.Without a query string, there is no lexical or linguistic analysis, no scoring, and no ranking. Beachten Sie, dass die Suchzeichenfolge nur ein Sternchen ist, und alle Dokumente abgeglichen werden.Notice the search string is just an asterisk, which means "match all documents".

    search=*&$filter=(baseRate ge 60 and baseRate lt 300) and accommodation eq 'Hotel' and city eq 'Nogales'
    
  • Kombination aus Abfragezeichenfolge und $filter, wobei der Filter die Teilmenge erstellt und die Abfragezeichenfolge die Begriffseingaben für die Volltextsuche über die gefilterte Teilmenge liefert.Combination of query string and $filter, where the filter creates the subset, and the query string provides the term inputs for full text search over the filtered subset. Das Verwenden eines Filters mit einer Abfragezeichenfolge ist das verbreitetste Verwendungsmuster.Using a filter with a query string is the most common usage pattern.

    search=hotels ocean$filter=(baseRate ge 60 and baseRate lt 300) and city eq 'Los Angeles'
    
  • Zusammengesetzte Abfragen, getrennt durch "or", jede mit eigenen Filterkriterien (z.B. 'beagles' in' dog' oder' siamese' in' cat').Compound queries, separated by "or", each with its own filter criteria (for example, 'beagles' in 'dog' or 'siamese' in 'cat'). Ausdrücke in Kombination mit or werden einzeln ausgewertet. Dabei stimmt die Vereinigung der Dokumente mit jedem Ausdruck überein, der in der Antwort zurückgesendet wird.Expressions combined with or are evaluated individually, with the union of documents matching each expression sent back in the response. Dieses Nutzungsmuster erfolgt über die search.ismatchscoring-Funktion.This usage pattern is achieved through the search.ismatchscoring function. Sie können auch die nicht bewertende Version (search.ismatch) verwenden.You can also use the non-scoring version, 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'
    

    Es ist auch möglich, die Volltextsuche über search.ismatchscoring mit den Filtern and anstelle von or zu kombinieren. Diese Funktion entspricht der Suche mit den Parametern search und $filter in einer Suchanforderung.It is also possible to combine full-text search via search.ismatchscoring with filters using and instead of or, but this is functionally equivalent to using the search and $filter parameters in a search request. Die folgenden beiden Abfragen erzielen beispielsweise das gleiche Ergebnis:For example, the following two queries produce the same result:

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

Diese Artikel bieten eine umfassende Anleitung zu bestimmten Anwendungsfällen:Follow up with these articles for comprehensive guidance on specific use cases:

Feldanforderungen für das FilternField requirements for filtering

In der REST-API ist „filterable“ (filterbar) für einfache Felder standardmäßig aktiviert.In the REST API, filterable is on by default for simple fields. Filterbare Felder erhöhen die Indexgröße. Stellen Sie sicher, dass Sie "filterable": false für Felder festlegen, die Sie nicht in einem Filter verwenden möchten.Filterable fields increase index size; be sure to set "filterable": false for fields that you don't plan to actually use in a filter. Weitere Informationen zu Einstellungen für Felddefinitionen finden Sie unter Erstellen eines Indexes.For more information about settings for field definitions, see Create Index.

Im .NET SDK ist die Eigenschaft „filterable“ standardmäßig deaktiviert.In the .NET SDK, the filterable is off by default. Sie können Felder filterbar machen, indem Sie die Eigenschaft IsFilterable des entsprechenden Feld-Objekts auf true festlegen.You can make a field filterable by setting the IsFilterable property of the corresponding Field object to true. Das ist auch deklarativ möglich, indem Sie das Attribut IsFilterable verwenden.You can also do this declaratively by using the IsFilterable attribute. Im folgenden Beispiel ist das Attribut auf die BaseRate-Eigenschaft einer Modellklasse festgelegt, die der Indexdefinition zugeordnet wird.In the example below, the attribute is set on the BaseRate property of a model class that maps to the index definition.

    [IsFilterable, IsSortable, IsFacetable]
    public double? BaseRate { get; set; }

Aktivieren der Filterbarkeit für vorhandene FelderMaking an existing field filterable

Sie können vorhandene Felder nicht so ändern, dass sie filterbar sind.You can't modify existing fields to make them filterable. Sie müssen stattdessen ein neues Feld hinzufügen oder den Index neu erstellen.Instead, you need to add a new field, or rebuild the index. Weitere Informationen zur Neuerstellung eines Indexes oder der Wiederauffüllung von Feldern finden Sie unter How to rebuild an Azure Search index (Neuerstellen eines Azure Search-Indexes).For more information about rebuilding an index or repopulating fields, see How to rebuild an Azure Search index.

Grundlegendes zu TextfilternText filter fundamentals

Textfilter entsprechen Zeichenfolgefeldern mit Literalzeichenfolgen, die Sie im Filter angeben.Text filters match string fields against literal strings that you provide in the filter. Im Gegensatz zur Volltextsuche erfolgt bei Textfiltern keine lexikalische Analyse oder Worttrennung, sodass Vergleiche nur auf exakte Übereinstimmungen abzielen.Unlike full-text search, there is no lexical analysis or word-breaking for text filters, so comparisons are for exact matches only. Nehmen wir beispielsweise an, dass das Feld f „sunny day“ enthält. Dann stimmt zwar $filter=f eq 'Sunny' nicht überein, $filter=f eq 'sunny day' allerdings schon.For example, assume a field f contains "sunny day", $filter=f eq 'Sunny' does not match, but $filter=f eq 'sunny day' will.

Bei Textzeichenfolgen wird Groß-/Kleinschreibung berücksichtigt.Text strings are case-sensitive. Es gibt keine Kleinschreibung großgeschriebener Wörter. $filter=f eq 'Sunny day' findet deshalb „sunny day“ nicht.There is no lower-casing of upper-cased words: $filter=f eq 'Sunny day' will not find "sunny day".

Ansätze zum Filtern von TextApproaches for filtering on text

VorgehensweiseApproach BESCHREIBUNGDescription EinsatzgebieteWhen to use
search.in Eine Funktion, bei der ein Feld mit einer durch Trennzeichen getrennte Liste von Zeichenfolgen entspricht.A function that matches a field against a delimited list of strings. Dies wird für Sicherheitsfilter und alle anderen Filter empfohlen, in denen viele unformatierte Textwerte mit einem Zeichenfolgenfeld verglichen werden.Recommended for security filters and for any filters where many raw text values need to be matched with a string field. Die Funktion search.in ist auf Geschwindigkeit ausgelegt und viel schneller als das explizite Vergleichen des Felds mit jeder Zeichenfolge mithilfe von eq und or.The search.in function is designed for speed and is much faster than explicitly comparing the field against each string using eq and or.
search.ismatch Eine Funktion, die es erlaubt, Volltextsuchvorgänge mit strikt booleschen Filteroperationen im selben Filterausdruck zu kombinieren.A function that allows you to mix full-text search operations with strictly Boolean filter operations in the same filter expression. Verwenden Sie search.ismatch (oder das Äquivalent search.ismatchscoring), wenn Sie in einer Anforderung mehrere Suchfilterkombinationen möchten.Use search.ismatch (or its scoring equivalent, search.ismatchscoring) when you want multiple search-filter combinations in one request. Sie können sie auch für den Filter enthält verwenden, um auf eine Teilzeichenfolge innerhalb einer größeren Zeichenfolge zu filtern.You can also use it for a contains filter to filter on a partial string within a larger string.
$filter=field operator string Ein benutzerdefinierter Ausdruck bestehend aus Feldern, Operatoren und Werten.A user-defined expression composed of fields, operators, and values. Verwenden Sie diesen Ausdruck, wenn Sie genaue Übereinstimmungen zwischen Zeichenfolgefeldern und einem Zeichenfolgenwert finden möchten.Use this when you want to find exact matches between a string field and a string value.

Grundlegendes zu numerischen FilternNumeric filter fundamentals

Numerische Felder sind im Kontext der Volltextsuche nicht searchable.Numeric fields are not searchable in the context of full text search. Nur Zeichenfolgen werden einer Volltextsuche unterzogen.Only strings are subject to full text search. Wenn Sie z.B. 99,99 als Suchbegriff eingeben, werden keine Artikel mit dem Preis 99,99 USD zurückgegeben.For example, if you enter 99.99 as a search term, you won't get back items priced at $99.99. Stattdessen sehen Sie Elemente, die den Wert 99 in Zeichenfolgenfeldern des Dokuments enthalten.Instead, you would see items that have the number 99 in string fields of the document. Wenn Sie also numerische Daten haben, gilt die Annahme, dass Sie sie für Filter verwenden, einschließlich Bereiche, Facetten, Gruppen usw.Thus, if you have numeric data, the assumption is that you will use them for filters, including ranges, facets, groups, and so forth.

Dokumente, die numerische Felder enthalten (Preis, Größe, SKU, ID), geben diese Werte in Suchergebnissen zurück, wenn das Feld mit retrievable markiert ist.Documents that contain numeric fields (price, size, SKU, ID) provide those values in search results if the field is marked retrievable. Der Punkt hier ist, dass die Volltextsuche selbst nicht auf numerische Feldtypen anwendbar ist.The point here is that full text search itself is not applicable to numeric field types.

Nächste SchritteNext steps

Probieren Sie als Erstes den Suchexplorer im Portal aus, um Abfragen mit $filter-Parametern zu übermitteln.First, try Search explorer in the portal to submit queries with $filter parameters. Der Index von „real-estate-sample“ liefert interessante Ergebnisse für die folgenden gefilterten Abfragen, wenn Sie diese in die Suchleiste einfügen:The real-estate-sample index provides interesting results for the following filtered queries when you paste them into the search bar:

# 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-Filterausdrucksyntax > Beispiele.To work with more examples, see OData Filter Expression Syntax > Examples.

Weitere InformationenSee also