Condividi tramite

Paginazione - Linguaggio di query in Cosmos DB (in Azure e Fabric)

  • Si applica a: ✅ Azure Cosmos DB for NoSQL, ✅ Cosmos DB in Microsoft Fabric

In Cosmos DB (in Azure e Fabric) le query potrebbero avere più pagine di risultati. Questo documento illustra i criteri usati dal motore di query di Cosmos DB 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, Cosmos DB 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 meno. È possibile impostare su MaxItemCount-1 se non si vuole applicare un limite al numero di risultati per esecuzione di query.

Esistono anche altri motivi per cui il motore di query potrebbe dover suddividere i risultati delle query in più pagine. Questi motivi includono:

  • Il contenitore è stato limitato e non sono state disponibili unità richiesta (UR) 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 di query è minore o uguale a 'MaxItemCount'. Tuttavia, è possibile che altri criteri limitassero il numero 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 essere presenti 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 garantire risultati accurati delle 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 di Cosmos DB 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 Cosmos DB è 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 nel contenitore, le query restituiscono un singolo token di continuazione.

Non è possibile usare i 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

Contenuti correlati

  • Last updated on