Nota: Java 8 ha raggiunto la fine del supporto il 31 gennaio 2024. Le applicazioni Java 8 esistenti continueranno a essere eseguite e a ricevere traffico. Tuttavia, App Engine potrebbe bloccare il ri deployment di applicazioni che utilizzano runtime dopo la data di fine del supporto. Ti consigliamo di eseguire la migrazione alla versione più recente supportata di Java.

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. Ti consente inoltre di personalizzare i contenuti dei documenti recuperati. Puoi richiedere solo identificatori dei documenti o richiedere che i documenti contengano solo un sottoinsieme dei loro 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 derivati da altri campi del documento).

Oltre alle opzioni di query, la classe Query può includere anche un'istanza della classe SortOptions. Con le opzioni di ordinamento, puoi modificare l'ordinamento e ordinare i risultati in base a più chiavi.

Eseguire ricerche con la classe Query

Quando esegui una ricerca con un'istanza della classe Query, devi creare un'istanza della classe in diversi passaggi. Ecco l'ordine generale:

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

Le varie opzioni di query e ordinamento vengono specificate richiamando 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

Per impostare le opzioni della query, devi utilizzare la QueryOptions.Builder. Non hai accesso diretto a queste proprietà.

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 i documenti selezionati da restituire nei risultati.

Proprietà	Descrizione	Predefinito	Massimo
`Limit`	Il numero massimo di documenti da restituire nei risultati.	20	1000
`NumberFoundAccuracy`	Questa proprietà determina l'accuratezza 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, nonché 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 la precisione non specificata è 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`	Al posto di un offset, puoi utilizzare un cursore per recuperare gruppi di documenti in ordine. Viene aggiornato un cursore quando viene passato all'interno e all'esterno di query consecutive, consentendo di continuare ogni nuova ricerca dalla fine di quella precedente. Cursore e offset sono discussi nella pagina Gestione dei risultati.	Nullo. I risultati conterranno tutti i documenti corrispondenti (fino al limite).	-
`SortOptions`	Imposta un oggetto `SortOptions` per controllare l'ordine dei risultati di ricerca. Un'istanza di `SortOptions` ha il proprio set di proprietà, descritte di seguito.	Nullo. Ordinare per diminuire il ranking del documento.	-

Queste proprietà controllano quali campi dei documenti vengono visualizzati nei risultati.

Proprietà	Descrizione	Predefinito
`ReturningIdsOnly`	Imposta su `True` o `False`. Quando `True`, i documenti restituiti nei risultati conterranno solo ID, nessun campo.	`False` (restituisci tutti i campi).
`FieldsToReturn`	Specifica quali campi del documento includere nei risultati. Non è possibile specificare più di 100 campi.	Restituisci tutti i campi del documento (fino a 100 campi).
`ExpressionsToReturn`	Espressioni di campo che descrivono i campi calcolati che vengono aggiunte a ciascun documento restituito nei risultati della ricerca. Questi campi vengono aggiunti alla proprietà delle espressioni del documento. Il valore del campo viene specificato scrivendo un'espressione che può includere uno o più campi del documento.	Nessuna
`FieldsToSnippet`	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 suo 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.	Nessuna

SortOptions

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

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

Proprietà	Descrizione	Predefinito
`SortExpressions`	Un elenco di `SortExpressions` che rappresenta una sorta di Documenti multidimensionali.	Nessuna
`MatchScorer`	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`. L'assegnazione di un punteggio ai documenti può essere costosa (sia per le operazioni fatturabili che per i tempi di esecuzione) e può rallentare le ricerche. Usa i punteggi con parsimonia.	Nessuna
`Limit`	Numero massimo di oggetti a cui assegnare un punteggio e/o ordinare. Non può essere superiore a 10.000.	1000

Ordinamento in base a 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 "expression" ha più significati quando si parla di opzioni di ordinamento: SortOption stesso ha un attributo expressions. Questo attributo è un elenco di SortExpression oggetti 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 nella sezione successiva.

Un elemento 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	Predefinito
`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`
`DefaultValue` `DefaultValueDate` `DefaultValueNumber`	Il 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 del testo. Per gli ordinamenti numerici è necessario specificare un valore numerico.	Nessuna

Ordinamento in base a campi a più valori

Quando ordini un campo con 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". Due valori sono assegnati al campo "colore" di DocA nell'ordine (rosso, blu) e due valori a DocB nell'ordine (verde, rosso). Quando esegui un ordinamento specificando il campo di testo "color", DocA viene ordinata in base al valore "red" e DocB al valore "green". Gli altri valori dei campi non vengono utilizzati nell'ordinamento.

Per ordinare o non ordinare

Se non specifichi alcuna opzione di ordinamento, i risultati di ricerca vengono restituiti automaticamente in base al ranking decrescente. Non c'è limite al numero di documenti restituiti in questo caso. Se specifichi opzioni di ordinamento, l'ordinamento viene eseguito dopo che sono stati selezionati tutti i documenti corrispondenti. Esiste una proprietà esplicita "OrdinaOptions.limit", che controlla le dimensioni dell'ordinamento. Non è mai possibile ordinare più di 10.000 documenti; il valore predefinito è 1000. Se sono presenti più documenti corrispondenti rispetto al numero specificato da "OrdinaOptions.limit", la ricerca recupera, ordina e restituisce solo quel 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 quanti tu possa ordinare. Se utilizzi le opzioni di ordinamento ed è importante recuperare tutti i documenti corrispondenti, devi assicurarti che la query restituisca un numero di documenti non superiore a quello che puoi ordinare.

Espressioni di scrittura

Le espressioni vengono utilizzate per definire le espressioni di campo (impostate in "QueryOptions") e per 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 incorporate elencate di seguito. Le espressioni che coinvolgono i campi di punti geografici possono utilizzare le funzioni di punto geografico e distanza. Le espressioni nei 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 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 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 l'argomento più grande.	`max(recommended_retail_price, discount_price, wholesale_price)`
`min`	Restituisce il più piccolo degli 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 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 tipo diverso con lo stesso nome. Nota: `count` può essere utilizzato solo in `FieldExpressions`. Non può essere visualizzato in `SortExpressions`.	`count(user)`

Funzioni geopoint

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

Funzione	Descrizione	Esempio
`geopoint`	Definisce un punto geografico con 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 punto geografico o la chiamata della funzione di punto geografico. Tuttavia, un solo argomento può essere un nome 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 body, con il testo corrispondente alla query in grassetto.