Opzioni di query e ordinamento

Quando chiami il metodo search() usando 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 in search() per modificare queste opzioni.

La classe Query ti consente di specificare il numero di documenti da restituire in una volta. Consente inoltre di personalizzare i contenuti dei documenti recuperati. Puoi richiedere solo identificatori di documento o richiedere che contengano solo un sottoinsieme dei loro campi. Puoi creare campi personalizzati anche 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. Usando le opzioni di ordinamento, puoi modificare l'ordinamento e visualizzare 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 diversi passaggi. Di seguito viene riportato l'ordine generale:

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

Le varie opzioni di query e ordinamento sono specificate chiamando metodi setter nelle 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 direttamente accesso a queste proprietà.

Queste proprietà controllano il numero di risultati restituiti e l'ordine di visualizzazione. Le opzioni di offset e cursore, che si escludono a vicenda, supportano l'impaginazione. Specificano i documenti selezionati da restituire nei risultati.

Proprietà Descrizione predefinita 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 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. Altrimenti, il conteggio è una stima basata sulle corrispondenze trovate, 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 l'accuratezza 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, è possibile utilizzare un cursore per recuperare i gruppi di documenti in ordine ordinato. Un cursore viene aggiornato man mano che viene passato da una query all'altra, consentendo di continuare ogni nuova ricerca dalla fine della precedente. Cursore e offset vengono illustrati 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. Ordina in base al ranking del documento in ordine decrescente. -

Queste proprietà controllano i campi dei documenti da visualizzare nei risultati.

Proprietà Descrizione 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 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 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 può includere uno o più campi del documento. Nessuno
FieldsToSnippet Un elenco di nomi dei 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 solo due argomenti, creando uno snippet con un massimo di una stringa corrispondente, basata sulla 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 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 direttamente accesso a queste proprietà.

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

Proprietà Descrizione predefinita
SortExpressions Un elenco di SortExpressions che rappresenta un ordinamento multidimensionale di documenti. Nessuno
MatchScorer Oggetto facoltativo MatchScorer. Se presente, i documenti saranno valutati in base alla frequenza dei termini di ricerca. Il punteggio sarà disponibile come campo _score. Il calcolo dei punteggi può essere costoso (sia in operazioni fatturabili che in tempi di esecuzione) e può rallentare le ricerche. Utilizza il punteggio con moderazione. Nessuno
Limit Numero massimo di oggetti da valutare 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 da diversi campi. Tieni presente che il termine 'espressione' viene utilizzato con più significati quando si parla di opzioni di ordinamento: SortOption stesso ha un attributo espressione. Questo attributo è un elenco di oggetti SortExpression corrispondenti 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 creata in base alle regole nella sezione successiva.

SortExpression definisce anche la direzione dell'ordinamento e un valore-chiave predefinito da utilizzare se l'espressione non può essere calcolata 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. Nessuno
Direction La direzione per 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. Per gli ordinamenti di testo è necessario specificare un valore di testo. È necessario specificare un valore numerico per l'ordinamento numerico. Nessuno

Ordinamento su campi con 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 con entrambi un campo di testo denominato "colore". Due valori vengono assegnati al campo DocA (colore) nell'ordine (rosso, blu) e due valori a DocB nell'ordine (verde, rosso). Quando esegui un ordinamento specificando il campo di colore "colore", DocA viene ordinato sul valore "rosso" e DocB sul valore "verde". Gli altri valori di campo non vengono utilizzati nell'ordinamento.

Per ordinare o meno

Se non specifichi alcuna opzione di ordinamento, i risultati di ricerca vengono automaticamente restituiti per ranking decrescente. Non esiste alcun limite al numero di documenti restituiti. Se specifichi le 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 sono presenti più documenti corrispondenti 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.

Scrittura di espressioni

Le espressioni vengono utilizzate per definire le espressioni di campo (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 includono campi numerici possono utilizzare gli operatori aritmetici (+, -, *, /) e le funzioni numeriche elencate di seguito. Le espressioni che interessano i campi del punto geografico possono utilizzare le funzioni del punto geografico e della 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 proprietà ranking di un documento. Può essere utilizzato nelle espressioni di campo e nell'ordinamento.
_score Il punteggio assegnato a un documento quando includi un elemento MatchScorer in SortOptions. Questo termine può essere visualizzato solo nelle espressioni di ordinamento e 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 campo o espressioni che utilizzano numeri e nomi di campi.

Funzione Descrizione Esempio
max Restituisce il più grande degli 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 Accetta due argomenti numerici. La chiamata pow(x, y) calcola il valore di x elevato alla potenza y. pow(x, 2)
count Utilizza come argomento un nome di campo. Restituisce il numero di campi nel documento con tale 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 Geopoint

Queste funzioni possono essere utilizzate per le espressioni che includono campi del punto geografico.

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 punto geografico o una chiamata della funzione di punto geografico. 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 del corpo, con il testo corrispondente alla query in grassetto.