Condividi tramite

Filtri nella ricerca di parole chiave

  • Articolo

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

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

Un filtro viene specificato utilizzando la sintassi dell'espressione di filtro OData. A differenza della ricerca di parole chiave e vettoriale, un filtro ha esito positivo solo se la corrispondenza è esatta.

Quando usare un filtro

I filtri sono fondamentali per diverse esperienze di ricerca, ad esempio la ricerca geospaziale di elementi nelle vicinanze, l'esplorazione in base a facet e i filtri di sicurezza, che mostrano solo i documenti che un utente è autorizzato a visualizzare. Se si implementa una di queste esperienze, è necessario un filtro. Le coordinate di georilevazione, la categoria di facet selezionata dall'utente o l'ID di sicurezza del richiedente vengono forniti dal filtro associato alla query di ricerca.

Gli scenari comuni includono:

  • Sezionare i risultati della ricerca in base al contenuto nell'indice. Dato uno schema con la posizione dell'hotel, le categorie e i servizi, si potrebbe creare un filtro per soddisfare esplicitamente alcuni criteri (a Seattle, sull'acqua, con vista).

  • Implementare un'esperienza di ricerca include una dipendenza di filtro:

    • L'esplorazione in base a facet usa un filtro per passare la categoria di facet selezionata dall'utente.
    • La ricerca geospaziale utilizza un filtro per passare le coordinate della posizione corrente nelle app e nelle funzioni "nelle vicinanze" che corrispondono a un'area o a una 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 possono essere recuperati e visualizzati nei risultati della ricerca, ma non sono disponibili per la ricerca (soggetti a ricerca full-text) individualmente. Se sono necessari criteri di selezione basati su dati numerici, usare un filtro.

Come vengono eseguiti i filtri

In fase di query, un parser di filtro accetta i criteri come input, converte l'espressione in espressioni booleane atomiche rappresentate in forma di albero e poi valuta l'albero di filtro sui campi filtrabili in un indice.

Il filtro viene applicato insieme alla ricerca, definendo i documenti da includere nell'elaborazione a valle per il recupero dei documenti e l'assegnazione dei punteggi relativi alla pertinenza. Quando viene usato in combinazione con una stringa di ricerca, il filtro riduce in modo efficace il set di richiamo dell'operazione di ricerca successiva. Se usato da solo (ad esempio, quando la stringa di query è vuota con search=*), il criterio di filtro è l'unico input.

Come vengono definiti i filtri

I filtri si applicano al contenuto alfanumerico nei campi attribuiti come filterable.

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

È possibile specificare un filtro per ogni operazione di ricerca, ma il filtro può includere più campi, più criteri e, se si usa una funzione ismatch, più espressioni di ricerca full-text. In un'espressione filtro multiparte è possibile specificare i predicati in qualsiasi ordine (a seconda dei ruoli di precedenza dell'operatore). Il riposizionamento dei predicati in una sequenza specifica non offre un miglioramento delle prestazioni rilevante.

Uno dei limiti per un'espressione filtro è il limite massimo delle dimensioni per la richiesta. L'intera richiesta, compreso il filtro, può avere dimensioni massime di 16 MB per POST o 8 KB per GET. Inoltre, c'è un limite al numero di clausole nell'espressione filtro. In genere, se si hanno centinaia di clausole, è probabile che si superi il limite. È consigliabile progettare l'applicazione in modo che non generi filtri con dimensioni non vincolate.

Gli esempi seguenti rappresentano definizioni di filtro prototipo in diverse API.

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2024-07-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" }
};

Modelli di filtro

Gli esempi seguenti illustrano diversi modelli di utilizzo per gli scenari di filtro. Per altre idee, vedere OData expression syntax > Examples> (Sintassi delle espressioni OData -> Esempi).

  • 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 ci sono un'analisi lessicale o linguistica, un'assegnazione del punteggio e una classificazione. Si noti che la stringa di ricerca è solo un asterisco, il che sta per "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, dove il filtro crea il subset e la stringa di query fornisce gli input dei termini per la ricerca full-text nel subset filtrato. L'aggiunta di termini (teatri raggiungibili a piedi) introduce i punteggi di ricerca nei risultati, dove i documenti che meglio corrispondono ai termini vengono classificati in cima. 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 ciascuna espressione inviata nella risposta. Questo modello di utilizzo viene ottenuto tramite la funzione search.ismatchscoring. È 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

    Inoltre, è possibile combinare la ricerca full-text tramite search.ismatchscoring con filtri utilizzando and invece di or, ma ciò equivale funzionalmente all'uso dei parametri search e $filter in una richiesta di ricerca. Ad esempio, le due query seguenti consentono di ottenere 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 la proprietà filtrabile è attivata per impostazione predefinita per i campi semplici. I campi filtrabili causano un aumento delle dimensioni dell'indice. Assicurarsi di impostare "filterable": false per i campi che non si prevede di usare in un filtro. Per altre informazioni sulle impostazioni delle definizioni di campo, vedere l'articolo relativo all'operazione Create Index.

Negli SDK di Azure, la proprietà filterable è disattivata per impostazione predefinita. È possibile rendere un campo filtrabile impostando la proprietà IsFilterable dell'oggetto SearchField corrispondente a true. Nell'esempio seguente l'attributo viene impostato sulla proprietà Rating di una classe di 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 di Azure AI Search.

Concetti fondamentali sui filtri di testo

I filtri di testo corrispondono ai campi stringa rispetto alle stringhe letterali specificate nel filtro: $filter=Category eq 'Resort and Spa'

A differenza della ricerca full-text, non c'è un'analisi lessicale o una separazione delle parole per i filtri di testo, quindi i confronti riguardano solo le corrispondenze esatte. Si supponga, ad esempio, che un campo f contenga "giornata di sole": non viene trovata la corrispondenza con $filter=f eq 'sunny', mentre con $filter=f eq 'sunny day' sì.

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à "giornata di sole". Tuttavia, è possibile utilizzare un normalizzatore per fare sì che il filtro non faccia distinzione tra maiuscole e minuscole.

Approcci per filtrare il testo

Approccio Descrizione Quando utilizzare
search.in Funzione che confronta un campo con un elenco delimitato di stringhe. Consigliato per i filtri di sicurezza e per tutti i filtri in cui è necessario associare molti valori di testo non elaborati a un campo stringa. La funzione search.in è progettata per la velocità ed è molto più veloce rispetto al confronto esplicito del campo con ogni stringa utilizzando eq e or.
search.ismatch Funzione che consente di combinare le operazioni di ricerca full-text con operazioni di filtro esclusivamente booleane nella stessa espressione filtro. Usare search.ismatch (o il relativo equivalente di punteggio, search.ismatchscoring) quando si desiderano più combinazioni di filtri di ricerca in una richiesta. Può essere usata anche con un filtro contains per applicare un filtro su una stringa parziale all'interno di una stringa più grande.
$filter=field operator string Espressione definita dall'utente composta da campi, operatori e valori. Usare questa opzione quando si desidera trovare corrispondenze esatte tra un campo stringa e un valore stringa.

Concetti fondamentali sui filtri numerici

I campi numerici non sono di tipo searchable nel contesto della ricerca full-text. Solo le stringhe sono soggette a ricerca full-text. Se, ad esempio, si immette 99,99 come termine di ricerca, non si otterranno gli articoli con prezzo $99,99. Verranno invece visualizzati gli articoli con il numero 99 nei campi stringa del documento. Se quindi si hanno dati numerici, il presupposto è che verranno 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 concetto è che la ricerca full-text non è applicabile ai tipi di campi numerici.

Passaggi successivi

Provare a usare Esplora ricerche nel portale per inviare query con parametri $filter. L'indice real-estate-sample fornisce risultati interessanti per le query di filtro seguenti quando le si incolla 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 altri esempi, vedere OData Filter Expression Syntax > Examples (Sintassi delle espressioni di filtro OData > Esempi).

Vedi anche