Ricerca con facet

La ricerca con facet ti consente di allegare informazioni categoriche ai documenti. Un facet è una coppia attributo/valore. Ad esempio, il facet denominato "size" potrebbe avere i valori "small", "medium" e "large".

Utilizzando i facet con la ricerca, puoi recuperare informazioni di riepilogo per perfezionare una query e "visualizzare in dettaglio" i risultati in una serie di passaggi.

Questa funzionalità è utile per applicazioni come i siti di shopping, in cui intendi offrire un insieme di filtri per consentire ai clienti di restringere i prodotti che vogliono vedere.

I dati aggregati di un facet mostrano la distribuzione dei valori di un facet. Ad esempio, il facet "size" potrebbe essere presente in molti documenti del set di risultati. I dati aggregati di questo facet potrebbero mostrare che il valore "small" è stato visualizzato 100 volte, "medium" 300 volte e "large" 250 volte. Ogni coppia facet/valore rappresenta un sottoinsieme di documenti nel risultato della query. A ogni coppia è associata una chiave, chiamata affinamento. Puoi includere gli affinamenti in una query per recuperare i documenti che corrispondono alla stringa di query e che hanno i valori dei facet corrispondenti a uno o più affinamenti.

Quando esegui una ricerca, puoi scegliere quali facet raccogliere e mostrare con i risultati oppure puoi attivare il rilevamento dei facet per selezionare automaticamente i facet che appaiono più spesso nei documenti.

Aggiungere facet a un documento

Aggiungi i facet a un documento prima di aggiungerlo a un indice. Esegui questa operazione contemporaneamente alla specifica dei campi del documento:

def add_faceted_document(index):
    document = search.Document(
        doc_id="doc1",
        fields=[search.AtomField(name="name", value="x86")],
        facets=[
            search.AtomFacet(name="type", value="computer"),
            search.NumberFacet(name="ram_size_gb", value=8),
        ],
    )

    index.put(document)

Un facet è simile a un campo del documento: ha un nome e accetta un valore.

I nomi dei facet seguono le stesse regole dei campi dei documenti: i nomi fanno distinzione tra maiuscole e minuscole e possono contenere solo caratteri ASCII. Devono iniziare con una lettera e possono contenere lettere, cifre o trattini bassi. Un nome non può superare i 500 caratteri.

Il valore di un facet può essere una stringa atomica (non più lunga di 500 caratteri) o un numero (un valore a virgola mobile a doppia precisione compreso tra -2.147.483.647 e 2.147.483.647).

Puoi assegnare più valori a un facet in un documento aggiungendo un facet con lo stesso nome e tipo più volte, utilizzando ogni volta un valore diverso.

Non esiste un limite al numero di valori che un facet può avere. Non esiste inoltre un limite al numero di facet che puoi aggiungere a un documento o al numero di facet con nomi univoci in un indice.

Tieni presente che ogni volta che utilizzi un facet, può assumere un valore atomico o numerico. Un facet con il nome "size" può essere collegato a un documento con il valore stringa "small" e a un altro documento con il valore numerico 8. Infatti, lo stesso facet può essere visualizzato più volte nello stesso documento con entrambi i tipi di valori. Anche se è consentito, non consigliamo di utilizzare valori atomici e numerici per lo stesso facet.

Anche se un facet ha un tipo specifico quando lo aggiungi a un documento, i risultati di ricerca raccolgono tutti i suoi valori. Ad esempio, i risultati del facet "size" potrebbero mostrare che sono state trovate 100 istanze del valore "small", 150 istanze di "medium" e 135 istanze di valori numerici nell'intervallo [4, 8). I valori numerici esatti e la relativa distribuzione di frequenza non vengono mostrati.

Quando recuperi un documento utilizzando una query, non puoi accedere direttamente ai relativi facet e valori. Devi richiedere che le informazioni sui facet vengano restituite con la query, come spiegato nella sezione successiva.

Utilizzare una ricerca con facet per recuperare le informazioni sui facet

Puoi chiedere al backend di ricerca di rilevare i facet utilizzati più di frequente. Questa operazione è chiamata rilevamento automatico dei facet. Puoi anche recuperare le informazioni sui facet in modo esplicito selezionando un facet per nome o per nome e valore. Puoi combinare tutti e tre i tipi di recupero dei facet in una singola query.

La richiesta di informazioni sui facet non influirà sui documenti restituiti dalla query. Può influire sul rendimento. L'esecuzione di una ricerca con facet con la profondità predefinita di 1000 ha lo stesso effetto dell'impostazione del limite di punteggio delle opzioni di ordinamento su 1000.

Rilevamento automatico dei facet

Il rilevamento automatico dei facet cerca i facet che appaiono più spesso in aggregato nei documenti. Ad esempio, supponiamo che i documenti che corrispondono alla query includano un facet "color" che appare 5 volte con il valore "red", 5 volte con il valore "white" e 5 volte con il colore "blue". Questo facet ha un conteggio totale di 15. Ai fini del rilevamento, avrebbe una classificazione più alta rispetto a un altro facet "shade" che appare negli stessi documenti corrispondenti 6 volte con il valore "dark" e 7 volte con il valore "light".

Devi attivare il rilevamento dei facet impostandolo nella query:

def facet_discovery(index):
    # Create the query and enable facet discovery.
    query = search.Query("name:x86", enable_facet_discovery=True)
    results = index.search(query)

    for facet in results.facets:
        print("facet {}.".format(facet.name))
        for value in facet.values:
            print(
                "{}: count={}, refinement_token={}".format(
                    value.label, value.count, value.refinement_token
                )
            )

Quando recuperi i facet tramite il rilevamento, per impostazione predefinita vengono restituiti solo i 10 valori più frequenti per un facet.

Puoi aumentare questo limite fino a 100 utilizzando il parametro FacetOptions discovery_limit.

Tieni presente che il rilevamento automatico dei facet non ha lo scopo di restituire tutti i facet possibili e i relativi valori. I facet restituiti dal rilevamento possono variare da un'esecuzione all'altra. Se vuoi un insieme fisso di facet, utilizza un parametro return_facets nella query.

I valori stringa vengono restituiti singolarmente. I valori numerici di un facet rilevato vengono restituiti in un singolo intervallo [min max). Puoi esaminare questo intervallo e creare un intervallo secondario più piccolo per una query successiva.

Selezionare i facet per nome

Per recuperare le informazioni su un facet solo in base al nome, aggiungi un parametro return_facets alla query, includendo il nome del facet nell'elenco:

def facet_by_name(index):
    # Create the query and specify to only return the "type" and "ram_size_gb"
    # facets.
    query = search.Query("name:x86", return_facets=["type", "ram_size_gb"])
    results = index.search(query)

    for facet in results.facets:
        print("facet {}".format(facet.name))
        for value in facet.values:
            print(
                "{}: count={}, refinement_token={}".format(
                    value.label, value.count, value.refinement_token
                )
            )

Quando recuperi i facet per nome, per impostazione predefinita vengono restituiti solo i 10 valori più frequenti per un facet.

Puoi aumentare questo limite fino a 20 utilizzando il parametro FacetOptions discovery_value_limit.

Selezionare i facet per nome e valore

Per recuperare informazioni solo su valori specifici di un facet, aggiungi un parametro return_facets che includa un oggetto FacetRequest con un elenco di valori:

def facet_by_name_and_value(index):
    # Create the query and specify to return the "type" facet with values
    # "computer" and "printer" and the "ram_size_gb" facet with value in the
    # ranges [0,4), [4, 8), and [8, max].
    query = search.Query(
        "name:x86",
        return_facets=[
            search.FacetRequest("type", values=["computer", "printer"]),
            search.FacetRequest(
                "ram_size_gb",
                ranges=[
                    search.FacetRange(end=4),
                    search.FacetRange(start=4, end=8),
                    search.FacetRange(start=8),
                ],
            ),
        ],
    )

    results = index.search(query)
    for facet in results.facets:
        print("facet {}".format(facet.name))
        for value in facet.values:
            print(
                "{}: count={}, refinement_token={}".format(
                    value.label, value.count, value.refinement_token
                )
            )

I valori in un singolo FacetRequest devono essere tutti dello stesso tipo, ovvero un elenco di valori stringa o, per i numeri, un elenco di FacetRanges, che sono intervalli chiusi a sinistra (inizio) e aperti a destra (fine). Se il facet ha un mix di valori stringa e numerici, aggiungi FacetRequests separati per ciascuno.

Opzioni

Puoi controllare la ricerca con facet aggiungendo il parametro facet_options a una chiamata Query. Questo parametro accetta una singola istanza di FacetOptions. Utilizza questo parametro per sostituire il comportamento predefinito della ricerca con facet.

options = FacetOptions(discover_facet_limit=5,
                       discover_facet_value_limit=10,
                       depth=6000);
Parametro Descrizione Predefinito
discover_facet_limit Numero di facet da rilevare se il rilevamento dei facet è attivo. Se è 0, il rilevamento dei facet verrà disattivato. 10
discover_facet_value_limit Numero di valori da restituire per ciascuno dei facet principali rilevati. 10
depth Il numero minimo di documenti nei risultati della query da valutare per raccogliere informazioni sui facet. 1000

L'opzione depth si applica a tutti e tre i tipi di aggregazione dei facet: per nome, nome e valore e rilevamento automatico. Le altre opzioni sono solo per il rilevamento automatico.

Tieni presente che la profondità dei facet è in genere molto maggiore del limite della query. I risultati dei facet vengono calcolati per almeno il numero di documenti di profondità.

Se hai impostato il limite di punteggio delle opzioni di ordinamento su un valore superiore alla profondità, verrà utilizzato il limite di punteggio.

Recuperare i risultati dei facet

Quando utilizzi i parametri di ricerca con facet in una query, le informazioni aggregate sui facet vengono fornite con il risultato della query stesso.

Una query avrà un elenco di FacetResult. Nell'elenco sarà presente un risultato per ogni facet visualizzato in un documento che corrisponde alla query. Per ogni risultato, riceverai:

  • Il nome del facet
  • Un elenco dei valori più frequenti per il facet. Per ogni valore è presente un conteggio approssimativo del numero di volte in cui è apparso e una chiave di affinamento che può essere utilizzata per recuperare i documenti che corrispondono a questa query e al valore del facet.

Tieni presente che l'elenco dei valori includerà i valori stringa e numerici di un facet. Se il facet è stato rilevato automaticamente, i relativi valori numerici vengono restituiti come un singolo intervallo [min max). Se hai richiesto in modo esplicito un facet numerico con uno o più intervalli nella query, l'elenco conterrà un intervallo chiuso-aperto [start end) per ogni intervallo.

L'elenco dei valori dei facet potrebbe non includere tutti i valori trovati nei documenti, poiché le opzioni della query determinano il numero di documenti da esaminare e il numero di valori da restituire.

Le informazioni aggregate per ogni facet possono essere lette dai risultati di ricerca:

query = search.Query(...)
results = index.search(query)
for facet_info in results.facets:
  ...

Ad esempio, una query potrebbe aver trovato documenti che includono un facet "size" con i valori stringa e numerici. Il FacetResult per questo facet verrà creato nel seguente modo:

FacetResult(name='size', values=[
  FacetResultValue(label='[8, 10)', 22, refinement=refinement_key),
  FacetResultValue(label='small', 100, refinement=refinement_key),
  FacetResultValue(label='medium', 300, refinement=refinement_key),
  FacetResultValue(label='large', 250, refinement=refinement_key)])

Il parametro label viene creato da un valore del facet. Per i valori numerici, label è la rappresentazione di un intervallo.

The refinement_key è una stringa sicura per il web/URL che può essere utilizzata in una query successiva per recuperare i documenti che corrispondono al nome e al valore del facet del risultato.

Utilizzare i facet per perfezionare/filtrare una query

L'affinamento associato a ogni FacetResultValue può essere utilizzato per restringere ulteriormente i risultati in modo da includere solo i documenti che hanno questi valori dei facet. Per perfezionare le query con una o più di queste chiavi, trasmettile all'oggetto query:

query = search.Query(..., facet_refinements=[refinement_key1, refinement_key2, refinement_key3])

Puoi combinare gli affinamenti per uno o più facet diversi nella stessa richiesta. Tutti gli affinamenti appartenenti allo stesso facet vengono uniti con un OR. Gli affinamenti per facet diversi vengono combinati con AND.

È anche possibile creare manualmente una chiave FacetRefinement personalizzata. Per ulteriori informazioni, consulta la documentazione della classe.