Paginação no Azure Cosmos DB for NoSQL

  • Artigo

APLICA-SE A: NoSQL

No Azure Cosmos DB for NoSQL, as consultas podem ter várias páginas de resultados. Este documento explica os critérios que o mecanismo de consulta do Azure Cosmos DB for NoSQL utiliza para decidir se os resultados da consulta devem ser divididos em várias páginas. Opcionalmente, você pode usar tokens de continuação para gerenciar os resultados da consulta que abrangem várias páginas.

Execuções de consulta

Às vezes, os resultados da consulta são divididos em várias páginas. Uma execução de consulta separada gera os resultados de cada página. Quando os resultados da consulta não puderem ser retornados em uma execução única, o Azure Cosmos DB for NoSQL dividirá os resultados automaticamente em várias páginas.

Você pode especificar o número máximo de itens retornados por uma consulta definindo o MaxItemCount. O MaxItemCount é especificado por solicitação e informa ao mecanismo de consulta que retornará esse número de itens ou menos. Você pode definir MaxItemCount como -1 se não quer inserir um limite no número de resultados por execução de consulta.

Além disso, há outros motivos pelos quais o mecanismo de consulta pode precisar dividir os resultados da consulta em várias páginas. Esses motivos incluem:

  • O contêiner foi limitado e não havia RUs disponíveis para retornar mais resultados da consulta
  • A resposta da execução da consulta era muito grande
  • O tempo de execução da consulta era muito longo
  • Era mais eficiente para o mecanismo de consulta retornar resultados em execuções extra

O número de itens retornados por execução de consulta é menor ou igual a MaxItemCount. No entanto, é possível que outros critérios tenham limitado o número de resultados que a consulta pode retornar. Caso você execute a mesma consulta várias vezes, pode ser que o número de páginas não seja constante. Por exemplo, caso uma consulta seja restringida, pode haver menos resultados disponíveis por página, o que significa que a consulta possui páginas extra. Em alguns casos, também é possível que a consulta possa retornar uma página sem resultados.

Lidar com várias páginas de resultados

Para garantir os resultados de consulta precisos, você deve passar por todas as páginas. Você deve continuar executando consultas até que não haja nenhuma página extra.

Aqui estão alguns exemplos para processar resultados de consultas com várias páginas:

Tokens de continuação

Opcionalmente, no SDK do .NET e no SDK do Java, você pode usar tokens de continuação como um indicador para o progresso da consulta. O estado das execuções de consulta do Azure Cosmos DB for NoSQL não é monitorado do lado do servidor, e elas podem ser retomadas a qualquer momento usando o token de continuação. Para o SDK do Python, os tokens de continuação só são compatíveis com as consultas de partição única. A chave de partição precisa ser especificada no objeto de opções porque não é suficiente tê-la na própria consulta.

Aqui estão alguns exemplos de uso de tokens de continuação:

Se a consulta retornar um token de continuação, haverá resultados de consulta extra.

Na API REST do Azure Cosmos DB for NoSQL, você pode gerenciar tokens de continuação com o cabeçalho x-ms-continuation. Assim como acontece com a consulta com o SDK do .NET ou do Java, se o cabeçalho de resposta x-ms-continuation não estiver vazio, isso significa que a consulta possui resultados extra.

Contanto que você use a mesma versão do SDK, os tokens de continuação nunca expiram. Opcionalmente, você pode restringir o tamanho de um token de continuação. Independentemente da quantidade de dados ou do número de partições físicas no contêiner, as consultas retornam um único token de continuação.

Você não pode usar tokens de continuação para consultas com GROUP BY ou DISTINCT porque essas consultas exigirão o armazenamento de um estado significativo. Para consultas com DISTINCT, você poderá usar tokens de continuação se adicionar ORDER BY à consulta.

Aqui está um exemplo de uma consulta com DISTINCT que poderia usar um token de continuação:

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

Conteúdo relacionado