Nota: il 31 gennaio 2024 è terminato il supporto di Java 8. Le tue applicazioni Java 8 esistenti continueranno a essere eseguite e a ricevere traffico. Tuttavia, App Engine potrebbe bloccare il nuovo deployment delle applicazioni che utilizzano i runtime dopo la data di fine del supporto. Ti consigliamo di eseguire la migrazione all'ultima versione supportata di Java.

Questa pagina è stata tradotta dall'API Cloud Translation.

Opzioni di query e ordinamento

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 in ordine decrescente
I documenti vengono restituiti in gruppi di 20 alla volta
I documenti recuperati contengono tutti i campi originali

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

La classe Query ti consente di specificare quanti documenti restituire alla volta. Inoltre, ti consente di personalizzare i contenuti dei documenti recuperati. Puoi richiedere solo gli identificatori dei documenti o chiedere 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 che circonda una stringa corrispondente) ed espressioni di campo (campi con valori ricavati da altri campi del documento).

Oltre alle opzioni di query, la classe Query può includere anche un'istanza della classe SortOptions. Utilizzando le opzioni di ordinamento, puoi cambiare l'ordine di ordinamento e ordinare i risultati in base a 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. Questa è la procedura generale:

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

Le varie opzioni di query e ordinamento vengono specificate chiamando i metodi setter sulle istanze delle classi QueryOptions.Builder e SortOptions.Builder, come in questo esempio:

try {
  // Build the SortOptions with 2 sort keys
  SortOptions sortOptions =
      SortOptions.newBuilder()
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("price")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValueNumeric(0))
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("brand")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValue(""))
          .setLimit(1000)
          .build();

  // Build the QueryOptions
  QueryOptions options =
      QueryOptions.newBuilder()
          .setLimit(25)
          .setFieldsToReturn("model", "price", "description")
          .setSortOptions(sortOptions)
          .build();

  // A query string
  String queryString = "product: coffee roaster AND price < 500";

  //  Build the Query and run the search
  Query query = Query.newBuilder().setOptions(options).build(queryString);
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);
  Results<ScoredDocument> result = index.search(query);
  return result;
} catch (SearchException e) {
  // handle exception...
}

QueryOptions

Devi utilizzare QueryOptions.Builder per impostare le opzioni di query. Non hai accesso diretto a queste proprietà.

Queste proprietà controllano il numero di risultati restituiti e l'ordine in cui vengono restituiti. Le opzioni offset e cursor, che si escludono a vicenda, supportano la paginazione. Specificano quali documenti selezionati restituire nei risultati.

Proprietà	Descrizione	Predefinito	Massimo
`Limit`	Il numero massimo di documenti da restituire nei risultati.	20	1000
`NumberFoundAccuracy`	Questa proprietà determina la precisione del risultato restituito da `Results.getNumberFound()` . 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 conteggio restituito è esatto. In caso contrario, il conteggio è una stima basata sulle corrispondenze trovate, sulle dimensioni e sulla struttura dell'indice. Tieni presente che l'impostazione di un valore elevato per questa proprietà può influire sulla complessità dell'operazione di ricerca e causare timeout.	Se non specificato, 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`	Un cursore può essere utilizzato al posto di un offset per recuperare gruppi di documenti in ordine alfabetico. Un cursore viene aggiornato quando viene passato a query consecutive e viceversa, consentendo di continuare ogni nuova ricerca dalla fine di quella precedente. Il cursore e l'offset sono descritti nella pagina Gestione dei risultati.	Null. I risultati conterranno tutti i documenti corrispondenti (fino al limite).	-
`SortOptions`	Imposta un oggetto `SortOptions` per controllare l'ordinamento dei risultati di ricerca. Un'istanza di `SortOptions` ha un proprio insieme di proprietà, descritto di seguito.	Null. Ordina in base al ranking decrescente dei documenti.	-

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

Proprietà	Descrizione	Predefinito
`ReturningIdsOnly`	Da impostare su `True` o `False`. Se `True`, i documenti restituiti nei risultati conterranno solo ID, senza campi.	`False` (restituisce tutti i campi).
`FieldsToReturn`	Specifica i campi del documento da includere nei risultati. Non è possibile specificare più di 100 campi.	Restituisce tutti i campi del documento (fino a 100 campi).
`ExpressionsToReturn`	Espressioni di campo che descrivono i campi calcolati aggiunti a ogni documento restituito nei risultati di ricerca. Questi campi vengono aggiunti alla proprietà expressions del documento. Il valore del campo viene specificato scrivendo un'espressione che può includere uno o più campi del documento.	Nessuno
`FieldsToSnippet`	Un elenco di nomi di campi di testo. Viene generato uno snippet per ogni campo. Si tratta di un campo calcolato che viene aggiunto alla proprietà expressions 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 `ExpressionsToReturn` aggiungendo un'espressione di campo che chiami esplicitamente la funzione snippet.	Nessuno

SortOptions

Le proprietà di SortOptions controllano l'ordinamento e il punteggio dei risultati di ricerca. Devi utilizzare SortOptions.Builder per impostare le opzioni di ordinamento. Non hai accesso diretto a queste proprietà.

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

Proprietà	Descrizione	Predefinito
`SortExpressions`	Un elenco di `SortExpressions` che rappresenta una classificazione multidimensionale dei documenti.	Nessuno
`MatchScorer`	Un oggetto `MatchScorer` facoltativo. In questo caso, i documenti verranno valutati in base alla frequenza del termine di ricerca. Il punteggio sarà disponibile come campo `_score`. L'assegnazione del punteggio ai documenti può essere costosa (sia in termini di operazioni fatturabili che di tempo di esecuzione) e può rallentare le ricerche. Utilizza il punteggio con parsimonia.	Nessuno
`Limit`	Numero massimo di oggetti da valutare e/o ordinare. Non può essere superiore a 10.000.	1000

Ordinamento per più chiavi

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

Un SortExpression definisce anche l'ordine di ordinamento e un valore della chiave predefinito da utilizzare se l'espressione non può essere calcolata per un documento. Ecco l'elenco completo delle proprietà:

Proprietà	Descrizione	Predefinito
`Expression`	Un'espressione da valutare durante l'ordinamento dei risultati per ogni documento corrispondente.	Nessuno
`Direction`	L'ordine di ordinamento dei risultati di ricerca, `ASCENDING` o `DESCENDING`.	`DESCENDING`
`DefaultValue` `DefaultValueDate` `DefaultValueNumber`	Il valore predefinito dell'espressione, se non è presente alcun campo e non può essere calcolato per un documento. Per le ordinamento di testo deve essere specificato un valore di testo. Per le ordinamento numeriche deve essere specificato un valore numerico.	Nessuno

Ordinamento in base a campi con più valori

Quando ordini in base a un campo con più valori di un determinato tipo, viene utilizzato solo il primo valore assegnato al campo. Ad esempio, prendiamo in considerazione due documenti, DocA e DocB, che hanno entrambi un campo di testo denominato "colore". Al campo "colore" del documento A vengono assegnati due valori nell'ordine (rosso, blu) e due valori al documento B nell'ordine (verde, rosso). Quando esegui un ordinamento specificando il campo di testo "colore", il documento A viene ordinato in base al valore "rosso" e il documento B in base al valore "verde". Gli altri valori di campo non vengono utilizzati nell'ordinamento.

Ordinare o meno

Se non specifichi opzioni di ordinamento, i risultati di ricerca vengono visualizzati automaticamente in ordine decrescente. In questo caso non esiste alcun limite al numero di documenti che vengono restituiti. Se specifichi opzioni di ordinamento, l'ordinamento viene eseguito dopo la selezione di tutti i documenti corrispondenti. Esiste una proprietà esplicita, "SortOptions.limit", che controlla le dimensioni dell'ordinamento. Non puoi mai ordinare più di 10.000 documenti. Il valore predefinito è 1000. Se esistono più documenti corrispondenti rispetto al numero specificato da "SortOptions.limit", la ricerca recupera, ordina e restituisce solo questo 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 opzioni di ordinamento ed è importante recuperare tutti i documenti corrispondenti, devi assicurarti che la query non restituisca più documenti di quanti puoi ordinare.

Scrivere espressioni

Le espressioni vengono utilizzate per definire le espressioni dei campi (impostate in "QueryOptions") e le espressioni di ordinamento, 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 predefinite elencate di seguito. Le espressioni che coinvolgono i campi geopoint possono utilizzare le funzioni geopoint e distanza. Le espressioni per i campi di testo e HTML possono utilizzare la funzione snippet.

Le espressioni possono includere anche questi termini speciali:

Termine	Descrizione
`_rank`	La proprietà rank di un documento. Può essere utilizzato nelle espressioni dei campi e nelle espressioni di ordinamento.
`_score`	Il punteggio assegnato a un documento quando includi un `MatchScorer` in `SortOptions`. Questo termine può essere utilizzato solo nelle espressioni di ordinamento; non può essere utilizzato nelle espressioni dei campi.

Funzioni numeriche

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

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`	Richiede due argomenti numerici. La chiamata pow(x, y) calcola il valore di x elevato alla potenza y.	`pow(x, 2)`
`count`	Prende un nome di 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 punto geografico

Queste funzioni possono essere utilizzate per le espressioni che coinvolgono i campi geopoint.

Funzione	Descrizione	Esempio
`geopoint`	Definisce un punto geografico a partire da una latitudine e una longitudine.	`geopoint(-31.3, 151.4)`
`distance`	Calcola la distanza in metri tra due geopoint. Tieni presente che uno dei due argomenti può essere il nome di un campo geopoint o un'invocazione della funzione geopoint. Tuttavia, solo un argomento può essere un nome di 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 valore predefinito è 160 caratteri.

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