Avviso: nei prossimi mesi, stiamo riorganizzando il sito della documentazione di App Engine per semplificarti la ricerca dei contenuti e l'allineamento con il resto dei prodotti Google Cloud. Saranno disponibili gli stessi contenuti, ma ora la navigazione corrisponderà al resto dei prodotti Cloud. Se hai feedback o domande durante la navigazione del sito, fai clic su Invia feedback.

Opzioni di query e ordinamento

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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 alla volta
  • I documenti recuperati contengono tutti i campi originali

Per modificare queste opzioni, puoi utilizzare un'istanza della classe Query come argomento a search().

La classe Query ti consente di specificare quanti documenti restituire alla volta. Inoltre, consente di personalizzare i contenuti dei documenti recuperati. Puoi richiedere solo gli 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) e espressioni di campi (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 ordinare i risultati in base a più chiavi.

Effettuare una ricerca 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:

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

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

appengine-java8/search/src/main/java/com/example/appengine/search/SearchOptionServlet.java 
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 di query devi utilizzare la QueryOptions.Builder. Non hai accesso direttamente a queste proprietà.

Queste proprietà controllano il numero di risultati che vengono restituiti e in quale ordine. Le opzioni di offset e cursore, che si escludono a vicenda, supportano l'impaginazione. Specificano i documenti selezionati che devono essere restituiti nei risultati.

Proprietà Descrizione Impostazione predefinita 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 conteggiate, interrompendo la ricerca quando viene raggiunto.

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 e sulla dimensione e la struttura dell'indice. Tieni presente che l'impostazione di un valore elevato per questa proprietà può influire sulla complessità dell'operazione di ricerca e potrebbe 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 a limite). 1000
Cursor È possibile utilizzare un cursore al posto di un offset per recuperare gruppi di documenti in ordine ordinato. Un cursore viene aggiornato quando si passa all'interno e all'esterno delle query consecutive, consentendo la continuazione di ogni nuova ricerca dalla fine della precedente. Il cursore e l'offset vengono illustrati nella pagina Gestione dei risultati. Nullo. I risultati conterranno tutti i documenti corrispondenti (fino a 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. Ordina in base al ranking del documento diminuendo. -

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

Proprietà Descrizione Impostazione predefinita
ReturningIdsOnly Da impostare su True o False. Quando True, i documenti restituiti nei risultati conterranno solo ID, non campi. False (restituisci tutti i campi).
FieldsToReturn Specifica i campi dei documenti da includere nei risultati. Non è possibile specificare più di 100 campi. Restituisci tutti i campi del documento (fino a 100 campi).
ExpressionsToReturn Espressioni campi che descrivono i campi calcolati che vengono aggiunti a ogni documento restituito nei risultati di ricerca. Questi campi vengono aggiunti alla proprietà delle espressioni del documento. Il valore del campo viene specificato scrivendo un'espressione che potrebbe includere uno o più campi del documento. Nessuno
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 dello snippet ha lo stesso nome del campo di origine.

Questa opzione utilizza implicitamente la funzione snippet con soli due argomenti, creando uno snippet con al massimo una stringa corrispondente, in base alla stessa stringa di query che la ricerca ha utilizzato per recuperare i risultati: snippet("query-string", field-name).

Puoi anche creare snippet personalizzati con l'opzione ExpressionsToReturn aggiungendo un'espressione di campo che chiama 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 direttamente a queste proprietà.

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

Proprietà Descrizione Impostazione predefinita
SortExpressions Un elenco di SortExpressions che rappresenta un tipo di documenti multidimensionale. Nessuno
MatchScorer Un oggetto MatchScorer facoltativo. Se presenti, i documenti verranno valutati in base alla frequenza dei termini di ricerca. Il punteggio sarà disponibile come campo _score. I documenti con punteggio possono essere costosi (sia durante le operazioni fatturabili sia nei tempi di esecuzione) e possono rallentare le ricerche. Usa il punteggio con moderazione. Nessuno
Limit Numero massimo di oggetti da classificare e/o ordinare. Non può essere superiore a 10.000. 1000

Ordinamento su più chiavi

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

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 Impostazione predefinita
Expression Un'espressione da valutare durante l'ordinamento dei risultati per ogni documento corrispondente. Nessuno
Direction La direzione in cui ordinare i risultati della 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 di testo. È necessario specificare un valore numerico per gli ordinamenti numerici. Nessuno

Ordinamento nei 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, prendi in considerazione due documenti: DocA e DocB, che hanno entrambi un campo di testo denominato "quot;color". Nel campo DocA "color" vengono assegnati due valori nell'ordine (rosso, blu) e due valori nel documento DocB (verde, rosso). Quando esegui un ordinamento specificando il campo di testo "color", DocA viene ordinato in base al valore "red" e DocB al valore "green"". Gli altri valori dei campi non vengono utilizzati nell'ordinamento.

Per ordinare o meno

Se non specifichi alcuna opzione di ordinamento, i risultati di ricerca vengono restituiti automaticamente in ordine di ranking decrescente. Non c'è limite al numero di documenti restituiti in questo caso. Se specifichi opzioni di ordinamento, l'ordinamento viene 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 esistono 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 quelli che puoi ordinare. Se utilizzi le opzioni di ordinamento ed è importante recuperare ogni documento corrispondente, devi assicurarti che la query non restituisca più documenti di quelli che puoi ordinare.

Scrivere espressioni

Le espressioni vengono utilizzate per definire 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 includono campi numerici possono utilizzare gli operatori aritmetici (+, -, *, /) e le funzioni numeriche elencate di seguito. Le espressioni che includono campi di geopunto possono utilizzare le funzioni di geopunto e distanza. Le espressioni per i campi Testo e HTML possono utilizzare la funzione snippet.

Le espressioni possono includere anche questi termini speciali:

Termine Descrizione
_rank Una ranking del documento. Può essere utilizzato nelle espressioni dei campi e nelle espressioni di ordinamento.
_score Il punteggio assegnato a un documento quando includi MatchScorer in SortOptions. Questo termine può essere visualizzato 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 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 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 diversi tipi con lo stesso nome. Nota: count può essere utilizzato solo in FieldExpressions. Non può essere visualizzato in SortExpressions. count(user)

Funzioni di geopunto

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

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. Uno dei due argomenti può essere il nome di un campo geopoint o una chiamata della funzione geopoint. 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 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.