Filtri per la ricerca di parole chiave in Azure AI Search

Un filtro fornisce criteri basati su valori per includere o escludere il contenuto prima dell'esecuzione della query per la ricerca di parole chiave oppure prima o dopo l'esecuzione della query per la ricerca vettoriale. I filtri vengono applicati ai campi non di filtro, ma possono essere usati nella ricerca vettoriale se i documenti includono campi non di filtro. Ad esempio, per gli indici organizzati intorno al contenuto in blocchi, è possibile che siano presenti campi a livello padre o campi di metadati che possono essere filtrati.

Questo articolo illustra il filtro per la ricerca di parole chiave. Per altre informazioni sui vettori, vedere Aggiungere un filtro in una query vettoriale.

Viene specificato un filtro usando la sintassi dell'espressione filtro OData. A differenza della ricerca di parole chiave e vettore, un filtro ha esito positivo solo se la corrispondenza è esatta.

Quando usare un filtro

I filtri sono fondamentali per diverse esperienze di ricerca, tra cui la ricerca geospaziale "trova vicino a me", la navigazione facettata e i filtri di sicurezza che mostrano solo i documenti che un utente può visualizzare. Se si implementa una di queste esperienze, è necessario un filtro. Si tratta del filtro associato alla query di ricerca che fornisce le coordinate di georilevazione, la categoria facet selezionata dall'utente o l'ID di sicurezza del richiedente.

Gli scenari comuni includono:

• Sezionare i risultati della ricerca in base al contenuto nell'indice. Dato uno schema con posizione, categorie e servizi dell'hotel, è possibile creare un filtro per corrispondere in modo esplicito ai criteri (a Seattle, sull'acqua, con una vista).

• Implementare un'esperienza di ricerca con una dipendenza del filtro:

  • L'esplorazione in base a facet usa un filtro per passare la categoria di facet selezionata dall'utente.
  • La ricerca geospaziale usa un filtro per passare le coordinate della posizione corrente nelle app e nelle funzioni "trova vicino a me" che corrispondono all'interno di un'area o per distanza.
  • I filtri di sicurezza passano gli identificatori di sicurezza come criteri di filtro, in cui una corrispondenza nell'indice funge da proxy per i diritti di accesso al documento.

• Eseguire una "ricerca di numeri". I campi numerici sono recuperabili e possono essere visualizzati nei risultati della ricerca, ma non sono ricercabili (soggetti alla ricerca full-text) singolarmente. Se sono necessari criteri di selezione in base ai dati numerici, usare un filtro.

Modalità di esecuzione dei filtri

In fase di query, un parser di filtri accetta criteri come input, converte l'espressione in espressioni booleane atomiche rappresentate come albero e quindi valuta l'albero dei filtri su campi filtrabili in un indice.

Il filtro si verifica in combinazione con la ricerca, qualificando i documenti da includere nell'elaborazione downstream per il recupero dei documenti e l'assegnazione dei punteggi di pertinenza. Se abbinato a una stringa di ricerca, il filtro riduce efficacemente il set di richiamo dell'operazione di ricerca successiva. Se usato da solo (ad esempio, quando la stringa di query è vuota search=*dove ), i criteri di filtro sono l'unico input.

Modalità di definizione dei filtri

I filtri si applicano al contenuto di testo e numerico (non vettoriale) nei campi attribuiti come filterable.

I filtri sono espressioni OData, articolate nella sintassi filter supportata da Azure AI Search.

È possibile specificare un filtro per ogni operazione di ricerca , ma il filtro stesso può includere più campi, più criteri e se si usa una ismatch funzione, più espressioni di ricerca full-text. In un'espressione di filtro in più parti è possibile specificare predicati in qualsiasi ordine (soggetto alle regole di precedenza dell'operatore). Se si tenta di riorganizzare i predicati in una particolare sequenza, non è possibile ottenere prestazioni ottimali.

Uno dei limiti per un'espressione di filtro è il limite massimo di dimensioni della richiesta. L'intera richiesta, inclusa il filtro, può essere un massimo di 16 MB per POST o 8 KB per GET. Esiste anche un limite al numero di clausole nell'espressione di filtro. Una buona regola generale è che se si dispone di centinaia di clausole, si rischia di raggiungere il limite. È consigliabile progettare l'applicazione in modo che non generi filtri di dimensioni illimitate.

Gli esempi seguenti rappresentano le definizioni di filtro prototipico in diverse API.

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" }
};

Criteri di filtro

Gli esempi seguenti illustrano diversi modelli di utilizzo per gli scenari di filtro. Per altre idee, vedere Esempi di sintassi > delle espressioni OData.

• Elemento $filter autonomo, senza una stringa di query, utile quando l'espressione filtro è in grado di specificare il nome completo dei documenti di interesse. Senza una stringa di query, non esiste alcuna analisi lessicale o linguistica, nessun punteggio e nessuna classificazione. Si noti che la stringa di ricerca è solo un asterisco, ovvero "corrisponde a tutti i documenti".

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

• Combinazione di stringa di query e $filter, in cui il filtro crea il subset e la stringa di query fornisce l'input di termini per la ricerca full-text del subset filtrato. L'aggiunta di termini (teatri a distanza percorribile a piedi) introduce punteggi di ricerca nei risultati, dove i documenti che meglio corrispondono ai termini vengono classificati più in alto. L'uso di un filtro con una stringa di query è il modello di utilizzo più comune.

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

• Query composte, separate da "or", ciascuna con i propri criteri di filtro (ad esempio, 'beagle' in 'cane' or 'siamese' in 'gatto'). Le espressioni combinate con or vengono valutate singolarmente, con l'unione di documenti corrispondenti a ogni espressione inviata nella risposta. Questo modello di utilizzo viene ottenuto tramite la search.ismatchscoring funzione . È anche possibile usare la versione search.ismatch senza punteggio.

  # 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
  

  È anche possibile combinare la ricerca full-text tramite search.ismatchscoring con filtri usando and invece di or, ma questo è funzionalmente equivalente all'uso dei search parametri e $filter in una richiesta di ricerca. Ad esempio, le due query seguenti producono lo stesso risultato:

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

Requisiti dei campi per il filtro

Nell'API REST, "filtrabile" è attivato per impostazione predefinita per i campi semplici. I campi filtrabili aumentano le dimensioni dell'indice; Assicurarsi di impostare "filterable": false per i campi che non si prevede di usare effettivamente in un filtro. Per altre informazioni sulle impostazioni per le definizioni dei campi, vedere Creare un indice.

Nei Azure SDK, filtrabile è off per impostazione predefinita. È possibile rendere filtrabile un campo impostando la proprietà IsFilterable dell'oggetto SearchField corrispondente su true. Nell'esempio successivo, l'attributo viene impostato sulla Rating proprietà di una classe modello mappata alla definizione dell'indice.

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

Rendere filtrabile un campo esistente

Non è possibile modificare i campi esistenti per renderli filtrabili. È invece necessario aggiungere un nuovo campo o ricompilare l'indice. Per altre informazioni sulla ricompilazione di un indice o sul ripopolamento dei campi, vedere Come ricompilare un indice Azure AI Search.

Nozioni fondamentali sul filtro del testo

I filtri di testo confrontano i campi stringa con le stringhe letterali specificate nel filtro: $filter=Category eq 'Resort and Spa'

A differenza della ricerca full-text, non esiste un'analisi lessicale o un'interruzione di parole per i filtri di testo, quindi i confronti sono solo per corrispondenze esatte. Si supponga, ad esempio, che un campo f contenga "giorno di sole", $filter=f eq 'sunny' non corrisponda, ma $filter=f eq 'sunny day' lo farà.

Le stringhe di testo fanno distinzione tra maiuscole e minuscole, il che significa che i filtri di testo fanno distinzione tra maiuscole e minuscole per impostazione predefinita. Ad esempio, $filter=f eq 'Sunny day' non troverà "giorno di sole". Tuttavia, è possibile usare un normalizzatore per renderlo in modo che il filtro non faccia distinzione tra maiuscole e minuscole.

Approcci per filtrare il testo

Nozioni fondamentali sul filtro numerico

I campi numerici non sono searchable nel contesto della ricerca a testo completo. Solo le stringhe sono soggette alla ricerca di testo completo. Ad esempio, se si immette 99,99 come termine di ricerca, non si otterranno gli articoli a prezzo di $ 99,99. Vengono invece visualizzati gli elementi con il numero 99 nei campi stringa del documento. Pertanto, se si dispone di dati numerici, si presuppone che vengano usati per i filtri, inclusi intervalli, facet, gruppi e così via.

I documenti che contengono campi numerici (prezzo, dimensioni, SKU, ID) forniscono tali valori nei risultati della ricerca se il campo è contrassegnato come retrievable. Il punto è che la ricerca full-text non è applicabile ai tipi di campo numerici.

Passaggi successivi

Provare prima di tutto Search Explorer nel portale di Azure per inviare query con parametri $filter. L'indice di esempio immobiliare fornisce risultati interessanti per le query filtrate seguenti quando vengono incollate nella barra di ricerca:

# 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'

Per lavorare con più esempi, vedere Esempi di sintassi delle espressioni filtro OData>.

Vedere anche

• Come funziona la ricerca full-text in Azure AI Search
• API REST per la ricerca di documenti
• Sintassi di query semplice
• Sintassi di query Lucene
• Tipi di dati supportati