Opzioni di query e ordinamento

Questa API è supportata per i runtime di prima generazione e può essere utilizzata durante l'upgrade ai runtime di seconda generazione corrispondenti. Se stai eseguendo l'aggiornamento al runtime Python 3 di App Engine, fai riferimento alla guida alla migrazione per saperne di più sulle opzioni di migrazione per i servizi in bundle legacy.

Quando chiami il metodo search() utilizzando solo una stringa di query, i risultati vengono restituiti in base alle opzioni di query predefinite:

• I documenti vengono restituiti ordinati in ordine decrescente
• I documenti vengono restituiti in gruppi di 20 documenti alla volta
• I documenti recuperati contengono tutti i campi originali

Puoi utilizzare un'istanza della classe Query come argomento per search() per modificare queste opzioni.

La classe Query consente di specificare quanti documenti restituire contemporaneamente. Consente inoltre di personalizzare i contenuti dei documenti recuperati. Puoi richiedere solo identificatori di documenti o richiedere che i documenti contengano solo un sottoinsieme dei relativi campi. Puoi anche creare campi personalizzati nei documenti recuperati: snippet (frammenti di campi di testo che mostrano il testo circostante una stringa corrispondente) ed espressioni di campo (campi con valori derivati da altri campi del documento).

Oltre alle opzioni di query, la classe Query può includere anche un'istanza della classe SortOptions. Le opzioni di ordinamento ti consentono di modificare l'ordinamento e di ordinare i risultati in più chiavi.

Ricerca con la classe Query

Quando esegui una ricerca con un'istanza della classe Query, devi creare un'istanza della classe in più passaggi. Questo è l'ordine generale:

1. Crea una stringa di query.
2. Crea SortOptions, se necessario.
3. Crea QueryOptions.
4. Crea un oggetto Query che includa la stringa di query e (facoltativo) QueryOptions.
5. Chiama il metodo di ricerca sull'oggetto Query.

I costruttori QueryOptions e SortOptions utilizzano argomenti con nome, come mostrato in questo esempio:

def query_options():
    index = search.Index('products')
    query_string = "product: piano AND price < 5000"

    # Create sort options to sort on price and brand.
    sort_price = search.SortExpression(
        expression='price',
        direction=search.SortExpression.DESCENDING,
        default_value=0)
    sort_brand = search.SortExpression(
        expression='brand',
        direction=search.SortExpression.DESCENDING,
        default_value="")
    sort_options = search.SortOptions(expressions=[sort_price, sort_brand])

    # Create field expressions to add new fields to the scored documents.
    price_per_note_expression = search.FieldExpression(
        name='price_per_note', expression='price/88')
    ivory_expression = search.FieldExpression(
        name='ivory', expression='snippet("ivory", summary, 120)')

    # Create query options using the sort options and expressions created
    # above.
    query_options = search.QueryOptions(
        limit=25,
        returned_fields=['model', 'price', 'description'],
        returned_expressions=[price_per_note_expression, ivory_expression],
        sort_options=sort_options)

    # Build the Query and run the search
    query = search.Query(query_string=query_string, options=query_options)
    results = index.search(query)
    for scored_document in results:
        print(scored_document)

QueryOptions

Queste proprietà controllano quanti risultati vengono restituiti e in quale ordine. Le opzioni di offset e cursore, che si escludono a vicenda, supportano l'impaginazione. Specifica quali documenti selezionati restituire nei risultati.

Proprietà	Descrizione	Predefinita	Massimo
limit	Il numero massimo di documenti da restituire nei risultati.	20	1000
number_found_accuracy	Questa proprietà determina l'accuratezza del risultato restituito da SearchResults.number_found(). Imposta un limite per il numero di corrispondenze effettivamente conteggiate, interrompendo la ricerca quando viene raggiunto il limite. Se il numero di corrispondenze nell'indice è inferiore o uguale al limite, il numero restituito è esatto. In caso contrario, il conteggio è una stima basata sulle corrispondenze trovate, nonché sulle dimensioni e sulla struttura dell'indice. Tieni presente che l'impostazione di un valore alto per questa proprietà può influire sulla complessità dell'operazione di ricerca e causare timeout.	Se il valore non è specificato o se viene impostato su None, la precisione viene impostata sullo stesso valore di limit	25000
offset	L'offset del primo documento nei risultati da restituire.	0. I risultati conterranno tutti i documenti corrispondenti (fino al limite).	1000
cursor	È possibile utilizzare un cursore al posto di un offset per recuperare gruppi di documenti in ordine. Un cursore viene aggiornato man mano che viene passato dentro e fuori una query consecutive, consentendo di continuare ogni nuova ricerca a partire dalla fine della precedente. Il cursore e l'offset vengono discussi nella pagina Gestione dei risultati.	Nullo. I risultati conterranno tutti i documenti corrispondenti (fino al limite).	-
sort_options	Imposta un oggetto SortOptions per controllare l'ordine dei risultati di ricerca. Un'istanza di SortOptions ha il proprio insieme di proprietà, descritte di seguito.	Nullo. Ordina in base al ranking del documento diminuendo.	-

Queste proprietà controllano quali campi del documento vengono visualizzati nei risultati.

Proprietà	Descrizione	Predefinita
ids_only	Imposta su True o False. Quando True, i documenti restituiti nei risultati conterranno solo ID, nessun campo.	False (restituisce tutti i campi).
returned_fields	Specifica i campi del documento da includere nei risultati. Non è possibile specificare più di 100 campi.	Restituisci tutti i campi del documento (fino a 100 campi).
returned_expressions	Espressioni di campo che descrivono i campi calcolati che vengono aggiunti a ciascun documento restituito nei risultati della ricerca. Questi campi vengono aggiunti alla proprietà relativa alle espressioni del documento. Il valore del campo viene specificato scrivendo un'espressione che può includere uno o più campi del documento.	Nessuna
snippeted_fields	Un elenco di nomi di campi di testo. Per ogni campo viene generato uno snippet. Si tratta di un campo calcolato che viene aggiunto alla proprietà delle espressioni dei documenti nei risultati di ricerca. Il campo snippet ha lo stesso nome del campo di origine. Questa opzione utilizza implicitamente la funzione snippet con solo due argomenti, creando uno snippet con al massimo una stringa corrispondente, in base alla stessa stringa di query utilizzata dalla ricerca per recuperare i risultati: snippet("query-string", field-name). Puoi anche creare snippet personalizzati con l'opzione returned_expressions aggiungendo un'espressione di campo che chiama esplicitamente la funzione snippet.	Nessuna

SortOptions

Le proprietà di SortOptions controllano l'ordine e il punteggio dei risultati di ricerca.

Proprietà	Descrizione	Predefinita
expressions	Un elenco di SortExpressions che rappresenta un tipo di Documenti multidimensionale.	Nessuna
match_scorer	Un oggetto MatchScorer facoltativo. Se presente, ai documenti verrà assegnato un punteggio in base alla frequenza dei termini di ricerca. Il punteggio sarà disponibile nel campo _score. La valutazione dei documenti può essere costosa (sia per le operazioni fatturabili che per i tempi di esecuzione) e può rallentare le ricerche. Usa il punteggio con parsimonia.	Nessuna
limit	Numero massimo di oggetti a cui assegnare un punteggio e/o che vuoi ordinare. Non può essere superiore a 10.000.	1000

Ordinamento su più chiavi

Puoi ordinare i risultati della ricerca in base a più chiavi di ordinamento. Ogni chiave può essere un semplice nome di campo o un valore calcolato da diversi campi. Tieni presente che il termine "espressione" viene utilizzato con più significati quando si parla di opzioni di ordinamento: lo stesso SortOption ha un attributo espressioni. Questo attributo è un elenco di oggetti SortExpression che corrispondono alle chiavi di ordinamento. Infine, ogni oggetto SortExpression contiene un attributo espressione che specifica come calcolare il valore della chiave di ordinamento. Questa espressione viene creata in base alle regole della prossima sezione.

Un SortExpression definisce anche la direzione dell'ordinamento e una coppia chiave-valore predefinita da utilizzare se non è possibile calcolare l'espressione per un documento. Ecco l'elenco completo delle proprietà:

Proprietà	Descrizione	Predefinita
expression	Un'espressione da valutare durante l'ordinamento dei risultati per ogni documento corrispondente.	Nessuna
direction	La direzione in cui ordinare i risultati di ricerca, ASCENDING o DESCENDING.	DESCENDING
default_value	Valore predefinito dell'espressione, se non è presente alcun campo e non può essere calcolato per un documento. È necessario specificare un valore di testo per gli ordinamenti testuali. Per gli ordinamenti numerici è necessario specificare un valore numerico.	Nessuna

Ordinamento in base ai campi a più valori

Quando ordini un campo a più valori di un determinato tipo, viene utilizzato solo il primo valore assegnato al campo. Ad esempio, considera due documenti, DocA e DocB, che hanno entrambi un campo di testo denominato "color". Al campo "colore" DocA vengono assegnati due valori nell'ordine (rosso, blu) e due valori a DocB nell'ordine (verde, rosso). Quando esegui un ordinamento che specifica il campo di testo "color", DocA viene ordinata in base al valore "red" e DocB sul valore "green". Gli altri valori degli altri campi non vengono utilizzati nell'ordinamento.

Come ordinare o meno

Se non specifichi alcuna opzione di ordinamento, i risultati di ricerca vengono restituiti automaticamente in base al ranking decrescente. Non esiste alcun limite al numero di documenti restituiti in questo caso. Se specifichi le opzioni di ordinamento, l'ordinamento verrà eseguito dopo aver selezionato tutti i documenti corrispondenti. Esiste una proprietà esplicita, "OrdinaOptions.limit", che controlla le dimensioni dell'ordinamento. Non puoi mai ordinare più di 10.000 documenti. Il valore predefinito è 1000. Se ci sono più documenti corrispondenti rispetto al numero specificato da "OrdinaOptions.limit", la ricerca recupera, ordina e restituisce solo il numero limitato. Seleziona i documenti da ordinare dall'elenco di tutti i documenti corrispondenti, in ordine decrescente. È possibile che una query selezioni più documenti corrispondenti di quelli che puoi ordinare. Se utilizzi le opzioni di ordinamento ed è importante recuperare ogni documento corrispondente, dovresti cercare di assicurarti che la query non restituisca più documenti di quelli che puoi ordinare.

Scrittura di espressioni

Le espressioni vengono utilizzate per definire le espressioni di campo (impostate in "QueryOptions") e ordinare le espressioni, che sono impostate in SortOptions. Sono scritte come stringhe:

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

Le espressioni che coinvolgono i campi numerici possono utilizzare gli operatori aritmetici (+, -, *, /) e le funzioni numeriche integrate elencate di seguito. Le espressioni che riguardano i campi di punti geografici possono utilizzare le funzioni di punti geografici e distanza. Le espressioni per i campi di testo e HTML possono utilizzare la funzione snippet.

Le espressioni possono includere anche i seguenti termini speciali:

Termine	Descrizione
_rank	La proprietà ranking di un documento. Può essere utilizzata nelle espressioni di campo e nelle espressioni di ordinamento.
_score	Il punteggio assegnato a un documento quando includi un elemento MatchScorer in SortOptions. Questo termine può apparire solo nelle espressioni di ordinamento. Non può essere utilizzato nelle espressioni di campo.

Funzioni numeriche

Le espressioni per definire i valori numerici per FieldExpressions e SortExpressions possono utilizzare queste funzioni integrate. Gli argomenti devono essere numeri, nomi di campi o espressioni che utilizzano numeri e nomi di campi.

Funzione	Descrizione	Esempio
max	Restituisce il più grande dei suoi argomenti.	max(recommended_retail_price, discount_price, wholesale_price)
min	Restituisce il più piccolo dei suoi argomenti.	min(height, width, length)
log	Restituisce il logaritmo naturale.	log(x)
abs	Restituisce il valore assoluto.	abs(x)
pow	Prende due argomenti numerici. La chiamata pow(x, y) calcola il valore di x elevato alla potenza di y.	pow(x, 2)
count	Prende il nome di un campo come argomento. Restituisce il numero di campi nel documento con quel nome. Ricorda che un documento può contenere più campi di tipi diversi con lo stesso nome. Nota: count può essere utilizzato solo in FieldExpressions. Non può essere visualizzato in SortExpressions.	count(user)

Funzioni dei punti geografici

Queste funzioni possono essere utilizzate per espressioni che coinvolgono i campi di punti geografici.

Funzione	Descrizione	Esempio
geopoint	Definisce un punto geografico in base a latitudine e longitudine.	geopoint(-31.3, 151.4)
distance	Calcola la distanza in metri tra due punti geografici. Tieni presente che uno dei due argomenti può essere il nome di un campo di punti geografici o una chiamata della funzione di punto geografico. Tuttavia, un solo argomento può essere il nome di un campo.	distance(geopoint(23, 134), store_location)

Snippet

Uno snippet è un frammento di un campo di testo che corrisponde a una stringa di query e include il testo circostante. Gli snippet vengono creati chiamando la funzione snippet:

snippet(query, body, [max_chars])

query

Una stringa di query tra virgolette che specifica il testo da trovare nel campo.

body

Il nome di un campo di testo, HTML o atom.

max_chars

Il numero massimo di caratteri da restituire nello snippet. Questo argomento è facoltativo; il suo valore predefinito è 160 caratteri.

La funzione restituisce una stringa HTML. La stringa contiene uno snippet del valore del campo body, con il testo corrispondente alla query in grassetto.