Ricerca con facet

La ricerca per sfaccettature ti consente di allegare informazioni categoriche ai tuoi documenti. Un facet è una coppia attributo/valore. Ad esempio, la sfaccettatura denominata "taglia" potrebbe avere i valori "piccola", "media" e "grande".

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

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

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

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

Aggiungere facet a un documento

Aggiungi sfaccettature 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. Il nome non può contenere più di 500 caratteri.

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

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

Non esiste un limite al numero di valori che un facet può avere. Inoltre, non esiste alcun limite al numero di sfaccettature che puoi aggiungere a un documento o al numero di sfaccettature con nome univoco in un indice.

Tieni presente che ogni volta che utilizzi una sfaccettatura, questa può assumere un valore atomico o numerico. Una sfaccettatura con il nome "size" può essere associata a un documento con il valore stringa "small" e a un altro documento con il valore numerico 8. Infatti, la stessa sfaccettatura può apparire più volte nello stesso documento con entrambi i tipi di valori. Non è consigliabile utilizzare valori atomici e numerici per la stessa sfaccettatura, anche se è consentito.

Anche se una sfaccettatura ha un tipo specifico quando la aggiungi a un documento, i risultati di ricerca raggruppano tutti i suoi valori. Ad esempio, i risultati per la sfaccettatura "size" potrebbero mostrare che sono state rilevate 100 istanze del valore "small", 150 istanze di "medium" e 135 istanze di valori numerici nell'intervallo [4, 8). Non vengono mostrati i valori numerici esatti e la loro distribuzione di frequenza.

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

Utilizzo di una ricerca con facet per recuperare le informazioni sui facet

Puoi chiedere al backend di ricerca di scoprire le sfaccettature più utilizzate per te. Questa operazione è chiamata scoperta automatica delle sfaccettature. Puoi anche recuperare le informazioni sulle sfaccettature in modo esplicito selezionando una sfaccettatura per nome o per nome e valore. Puoi combinare tutti e tre i tipi di recupero dei facet in un'unica query.

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

Rilevamento automatico dei facet

Il rilevamento automatico dei prospetti cerca i prospetti che compaiono più spesso nell'aggregato dei tuoi documenti. Ad esempio, supponiamo che i documenti corrispondenti alla tua query includano una sfaccettatura "colore" che compare 5 volte con il valore "rosso", 5 volte con il valore "bianco" e 5 volte con il colore "blu". Questo aspetto ha un conteggio totale di 15. Ai fini della scoperta, avrebbe un ranking superiore a un'altra sfaccettatura "tonalità" che compare negli stessi documenti corrispondenti 6 volte con il valore "scuro" e 7 volte con il valore "chiaro".

Devi attivare l'individuazione dei facet impostandola 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 per scoperta, 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 l'individuazione automatica delle sfaccettature non ha lo scopo di restituire tutte le sfaccettature possibili e i relativi valori. Le sfaccettature restituite dalla scoperta possono variare da un'esecuzione all'altra. Se è necessario un insieme fisso di sfaccettature, utilizza un parametro return_facets nella query.

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

Selezionare i facet per nome

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

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 la sfaccettatura contiene un mix di valori di stringa e numerici, aggiungi FacetRequest separati per ciascuno.

Opzioni

options = FacetOptions(discover_facet_limit=5,
                       discover_facet_value_limit=10,
                       depth=6000);

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

Tieni presente che la profondità delle sfaccettature è in genere molto maggiore del limite delle query. I risultati delle sfaccettature vengono calcolati in base ad almeno il numero di documenti della profondità. Se hai impostato il limite di punteggio delle opzioni di ordinamento superiore alla profondità, verrà utilizzato il limite di punteggio.

Recupero dei risultati dei facet

Quando utilizzi i parametri di ricerca con facet in una query, le informazioni sui facet aggregati vengono fornite insieme al risultato della query.

Una query avrà un elenco di FacetResult. Nell'elenco sarà presente un risultato per ogni sfaccettatura che è apparsa in un documento corrispondente alla tua query. Per ogni risultato, otterrai:

• 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 è stato visualizzato e una chiave di perfezionamento che può essere utilizzata per recuperare i documenti che corrispondono a questa query e a questo valore del facet.

Tieni presente che l'elenco dei valori includerà i valori numerici e stringa di una sfaccettatura. Se la sfaccettatura è stata rilevata automaticamente, i relativi valori numerici vengono restituiti come un singolo intervallo [min max). Se hai richiesto esplicitamente una sfaccettatura numerica con uno o più intervalli nella query, l'elenco conterrà un intervallo chiuso-aperto [inizio fine) per ogni intervallo.

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

Le informazioni aggregate per ogni sfaccettatura 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 includevano un facet "size" con valori stringa e valori numerici. FacetResult per questo aspetto 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 è costruito a partire da un valore di sfaccettatura. Per i valori numerici, label è la rappresentazione di un intervallo.

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 della sfaccettatura del risultato.

Utilizzare i facet per perfezionare/filtrare una query

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

Puoi combinare i perfezionamenti per una o più sfaccettature diverse nella stessa richiesta. Tutti i perfezionamenti appartenenti alla stessa sfaccettatura sono uniti con OR. I perfezionamenti per sfaccettature diverse sono combinati con AND.

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