Quando una chiamata di query viene completata normalmente, il risultato viene restituito come oggetto SearchResults
. L'oggetto risultati indica quanti documenti corrispondenti sono stati trovati nell'indice e quanti documenti corrispondenti sono stati restituiti. Include inoltre un elenco di ScoredDocuments
corrispondenti. Di solito, l'elenco contiene una parte di tutti i documenti corrispondenti trovati, poiché la ricerca restituisce un numero limitato di documenti ogni volta che viene richiamata. L'utilizzo di un offset o di un cursore ti consente di recuperare tutti i documenti corrispondenti, un sottoinsieme alla volta.
Risultati
A seconda del valore dell'opzione di query limit
, il numero di documenti corrispondenti restituiti nel risultato potrebbe essere inferiore al numero trovato. Ricorda che il numero trovato sarà una stima se l'accuratezza del numero trovato è inferiore al numero trovato. Indipendentemente da come configuri le opzioni di ricerca, una chiamata a search()
non troverà più di 10.000 documenti corrispondenti.
Se sono stati trovati più documenti che restituiti e vuoi recuperarli tutti, devi ripetere la ricerca utilizzando un offset o un cursore, come spiegato di seguito.
Documenti con punteggio
I risultati di ricerca includeranno un elenco di ScoredDocuments
che corrispondono alla query. Puoi ripetere l'elenco per elaborare ciascun documento alla volta:
Per impostazione predefinita, un documento con punteggio contiene tutti i campi del documento originale indicizzato. Se le tue opzioni di query hanno specificato returned_fields
, solo questi campi vengono visualizzati nella proprietà campi del documento. Se hai creato campi calcolati specificando returned_expressions
o snippeted_fields
, verranno visualizzati
separatamente nella proprietà expressions del documento.
Utilizzare gli offset
Se la ricerca trova più documenti di quelli che puoi restituire contemporaneamente, utilizza un offset per indicizzare nell'elenco dei documenti corrispondenti. Ad esempio, il limite predefinito di query è 20 documenti. Dopo aver eseguito una ricerca la prima volta (con offset 0) e recuperato i primi 20 documenti, recupera i successivi 20 documenti impostando l'offset su 20 ed eseguendo di nuovo la stessa ricerca. Continua a ripetere la ricerca, incrementando l'offset ogni volta per il numero di documenti restituiti:
Gli offset possono essere inefficienti quando si ripete un insieme di risultati molto ampio.
Uso dei cursori
Puoi anche utilizzare i cursori per recuperare un sottointervallo di risultati. I cursori sono utili quando intendi presentare i risultati di ricerca in pagine consecutive e vuoi assicurarti di non saltare nessun documento nel caso in cui un indice possa essere modificato tra una query e l'altra. I cursori sono anche più efficienti quando si ripete un insieme di risultati molto ampio.
Per utilizzare i cursori, devi creare un cursore iniziale e includerlo nelle opzioni della query. Esistono due tipi di cursori, per query e per risultato. Un cursore di query consente di associare un cursore separato all'oggetto dei risultati restituito dalla chiamata di ricerca. Un cursore per risultato consente di associare un cursore a ogni documento con punteggio nei risultati.
Utilizzo di un cursore di query
Per impostazione predefinita, un cursore appena creato è un cursore di query. Questo cursore contiene la posizione dell'ultimo documento restituito nei risultati della ricerca. Viene aggiornato a ogni ricerca. Per enumerare tutti i documenti corrispondenti in un indice, esegui la stessa ricerca finché il risultato non restituisce un cursore nullo:
Utilizzo di un cursore per risultato
Per creare cursori per risultato, devi impostare la proprietà cursore per_result su true quando crei il cursore iniziale. Quando viene restituita la ricerca, a ogni documento è associato un cursore. Puoi utilizzare il cursore per specificare una nuova ricerca con risultati che iniziano con un documento specifico. Tieni presente che quando passi un cursore per risultato alla ricerca, non ci sarà alcun cursore di query associato al risultato stesso. result.getCursor() restituirà un valore nullo, quindi non puoi utilizzarlo per verificare se hai recuperato tutte le corrispondenze.
Salvataggio e ripristino dei cursori
Un cursore può essere serializzato come stringa sicura per il web, salvato e quindi ripristinato per un utilizzo futuro: