I cursori di query consentono a un'applicazione di recuperare i risultati di una query in pratiche batch e sono consigliati in caso di utilizzo di offset interi per l'impaginazione. Consulta Query per ulteriori informazioni su come strutturare le query per l'app.
Cursori di query
I cursori di query consentono a un'applicazione di recuperare le query in pratiche pratiche senza incorrere nell'overhead associato a un offset di query. Dopo aver eseguito un'operazione di recupero, l'applicazione può ottenere un cursore, che è una stringa opaca con codifica Base64 che indica la posizione dell'indice dell'ultimo risultato recuperato. L'applicazione può salvare questa stringa, ad esempio in
Datastore, in Memcache, in un payload dell'attività della coda di attività, o incorporata in una
pagina web come parametro HTTP GET
o POST
, quindi utilizzare il cursore come
punto di partenza per un'operazione di recupero successiva, in modo da ottenere il batch successivo
di risultati dal punto in cui è stato recuperato quello precedente. Un recupero può anche specificare un cursore finale, per limitare l'estensione del set di risultati restituito.
Differenza tra offset e cursore
Anche se Datastore supporta gli offset interi, dovresti evitare di utilizzarli. Utilizza invece i cursori. L'utilizzo di un offset impedisce solo di restituire le entità ignorate all'applicazione, ma queste vengono comunque recuperate internamente. Le entità ignorate influiscono sulla latenza della query e la fatturazione per le operazioni necessarie per recuperarle viene applicata all'applicazione. L'utilizzo di pubblichetti al posto degli offset consente di evitare tutti questi costi.
Esempio di cursore di query
Nell'API di basso livello, l'applicazione può utilizzare i cursori tramite le interfacce QueryResultList
, QueryResultIterable
e QueryResultIterator
, restituite rispettivamente dai metodi PreparedQuery
e asQueryResultList()
, asQueryResultIterable()
e asQueryResultIterator()
. Ciascuno di questi oggetti risultato fornisce un metodo getCursor()
, che a sua volta restituisce un oggetto Cursor
. L'applicazione può ottenere una stringa sicura del Web che rappresenta il cursore chiamando il metodo toWebSafeString()
dell'oggetto Cursor
e in seguito può utilizzare il metodo statico Cursor.fromWebSafeString()
per ricostituire il cursore dalla stringa.
L'esempio seguente mostra l'utilizzo dei cursori per l'impaginazione:
Limiti dei cursori
I cursore sono soggetti alle seguenti limitazioni:
- Un cursore può essere utilizzato solo dalla stessa applicazione che ha eseguito la query originale e solo per continuare la stessa query. Per utilizzare il cursore in un'operazione di recupero successiva, devi ricostituire esattamente la query originale, compresi lo stesso tipo di entità, il filtro predecessore, i filtri proprietà e gli ordini di ordinamento. Non è possibile recuperare i risultati utilizzando un cursore senza impostare la stessa query da cui è stato inizialmente generato.
- Poiché gli operatori
NOT_EQUAL
eIN
sono implementati con più query, le query che li utilizzano non supportano i runner, né le query composte create con il metodoCompositeFilterOperator.or
. - I cursore non funzionano sempre come previsto con una query che utilizza un filtro di disuguaglianza o un ordinamento su una proprietà con più valori. La logica di deduplicazione per tali proprietà a più valori non viene mantenuta tra i recuperi, causando probabilmente lo stesso risultato una o più volte.
- Le nuove release di App Engine potrebbero modificare i dettagli di implementazione interni, invalidando i cursori che dipendono da tali release. Se un'applicazione tenta di utilizzare un curriculum non più valido, Datastore genera un errore
IllegalArgumentException
(API di basso livello),JDOFatalUserException
(JDO) oPersistenceException
(JPA).
Cursori e aggiornamenti dei dati
La posizione del cursore è definita come la località nell'elenco dei risultati dopo l'ultimo risultato. Un cursore non è una posizione relativa nell'elenco (non è un offset); è un indicatore su cui Datastore può saltare quando si avvia una scansione dell'indice per ottenere risultati. Se i risultati di una query cambiano tra gli utilizzi di un cursore, la query rileva solo le modifiche che si verificano nei risultati dopo il cursore. Se un nuovo risultato viene visualizzato prima della posizione del cursore per la query, non verrà restituito quando vengono recuperati. Analogamente, se un'entità non è più un risultato per una query, ma è apparsa prima del cursore, i risultati che vengono visualizzati dopo il cursore non cambiano. Se l'ultimo risultato restituito viene rimosso dal set di risultati, il cursore sa ancora come individuare il risultato successivo.
Durante il recupero dei risultati della query, puoi utilizzare sia un cursore iniziale sia un cursore finale per restituire un gruppo continuo di risultati da Datastore. Quando utilizzi un cursore iniziale e finale per recuperare i risultati, non è garantito che le dimensioni dei risultati corrispondano a quelle generate durante la generazione dei cursore. Le entità possono essere aggiunte o eliminate da Datastore tra il momento in cui vengono generati i cursori e quando vengono utilizzate in una query.
Passaggi successivi
- Scopri come specificare cosa restituisce una query e controlla ulteriormente i risultati della query.
- Scopri le limitazioni comuni per le query su Datastore.
- Scopri la coerenza dei dati e come funziona la coerenza dei dati con i diversi tipi di query su Datastore.
- Scopri la sintassi e la struttura di base delle query per Datastore.