Condividi tramite

Paginazione in Azure Cosmos DB per NoSQL

  • Articolo

SI APPLICA A: NoSQL

In Azure Cosmos DB per NoSQL le query possono avere più pagine di risultati. Questo documento illustra i criteri usati dal motore di query di Azure Cosmos DB per NoSQL per decidere se suddividere i risultati delle query in più pagine. Facoltativamente, è possibile usare i token di continuazione per gestire i risultati delle query che si estendono su più pagine.

Esecuzioni di query

A volte i risultati delle query vengono suddivisi in più pagine. Un'esecuzione di query separata genera i risultati di ogni pagina. Quando i risultati della query non possono essere restituiti in un'unica esecuzione, Azure Cosmos DB per NoSQL suddivide automaticamente i risultati in più pagine.

È possibile specificare il numero massimo di elementi restituiti da una query impostando MaxItemCount. L'oggetto MaxItemCount viene specificato per richiesta e indica al motore di query di restituire tale numero di elementi o un numero inferiore. È possibile impostare MaxItemCount su -1 se non si vuole applicare un limite al numero di risultati per ogni esecuzione di query.

Esistono anche altri motivi per cui il motore di query potrebbe dover suddividere i risultati delle query in più pagine. Di seguito sono elencati alcuni motivi per cui questa scelta è consigliabile:

  • Il contenitore è stato limitato e non sono state rese disponibili RU per restituire altri risultati della query
  • La risposta dell'esecuzione della query era troppo grande
  • Il tempo di esecuzione della query era troppo lungo
  • È stato più efficiente per il motore di query restituire risultati in esecuzioni aggiuntive

Il numero di elementi restituiti per esecuzione della query è minore o uguale a MaxItemCount. È tuttavia possibile che altri criteri abbiano un numero limitato di risultati restituiti dalla query. Se si esegue la stessa query più volte, il numero di pagine potrebbe non essere costante. Ad esempio, se una query è limitata, potrebbero esserci meno risultati disponibili per pagina, il che significa che la query ha pagine aggiuntive. In alcuni casi, è anche possibile che la query restituisca una pagina vuota di risultati.

Gestire più pagine di risultati

Per accertarsi di aver ricevuto risultati accurati alle query, è necessario scorrere tutte le pagine. È consigliabile continuare a eseguire query fino a quando non sono presenti pagine aggiuntive.

Ecco alcuni esempi per l'elaborazione dei risultati delle query con più pagine:

Token di continuazione

In .NET SDK e Java SDK è possibile usare facoltativamente i token di continuazione come segnalibro per lo stato della query. Le esecuzioni di query NoSQL di Azure Cosmos DB per NoSQL sono senza stato sul lato server e possono essere riprese in qualsiasi momento usando il token di continuazione. Per Python SDK, i token di continuazione sono supportati solo per le query a partizione singola. La chiave di partizione deve essere specificata nell'oggetto options perché non è sufficiente per includerla nella query stessa.

Ecco alcuni esempi per l'uso dei token di continuazione:

Se la query restituisce un token di continuazione, sono disponibili risultati di query aggiuntivi.

Nell'API REST di Azure Cosmos DB per NoSQL è possibile gestire i token di continuazione con l'intestazione x-ms-continuation . Come per l'esecuzione di query con .NET o Java SDK, se l'intestazione della x-ms-continuation risposta non è vuota, significa che la query ha risultati aggiuntivi.

Finché si usa la stessa versione dell'SDK, i token di continuazione non scadono mai. Facoltativamente, è possibile limitare le dimensioni di un token di continuazione. Indipendentemente dalla quantità di dati o dal numero di partizioni fisiche presenti nel contenitore, le query restituiscono un singolo token di continuazione.

Non è possibile usare token di continuazione per le query con GROUP BY o DISTINCT perché queste query richiedono l'archiviazione di una quantità significativa di stato. Per le query con DISTINCT, è possibile usare i token di continuazione se si aggiunge ORDER BY alla query.

Di seguito è riportato un esempio di query con DISTINCT che può usare un token di continuazione:

SELECT DISTINCT VALUE
    e.name
FROM
    employees e
ORDER BY
    e.name

Contenuto correlato