Partilhar via

Paginação no Azure Cosmos DB para NoSQL

  • Artigo

APLICA-SE A: NoSQL

No Azure Cosmos DB para 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 para NoSQL usa 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 resultados de 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 podem ser retornados em uma única execução, o Azure Cosmos DB para NoSQL divide automaticamente os resultados 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 diz ao mecanismo de consulta para retornar esse número de itens ou menos. Você pode definir MaxItemCount como -1 se não quiser colocar 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. Estas razões incluem:

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

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. Se você executar a mesma consulta várias vezes, o número de páginas pode não ser constante. Por exemplo, se uma consulta for limitada, pode haver menos resultados disponíveis por página, o que significa que a consulta tem páginas extras. Em alguns casos, também é possível que sua consulta retorne uma página vazia de resultados.

Lidar com várias páginas de resultados

Para garantir resultados de consulta precisos, você deve progredir em todas as páginas. Você deve continuar a executar consultas até que não haja páginas extras.

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

Fichas de continuação

No SDK do .NET e no SDK do Java, você pode, opcionalmente, usar tokens de continuação como um marcador para o progresso da consulta. As execuções de consulta do Azure Cosmos DB para NoSQL são sem monitoração de estado no lado do servidor e podem ser retomadas a qualquer momento usando o token de continuação. Para o SDK do Python, os tokens de continuação são suportados apenas para consultas de partição única. A chave de partição deve ser especificada no objeto options porque não é suficiente tê-la na própria consulta.

Aqui estão alguns exemplos para usar tokens de continuação:

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

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

Contanto que você esteja usando 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 em seu contêiner, as consultas retornam um único token de continuação.

Não é possível usar tokens de continuação para consultas com GROUP BY ou DISTINCT porque essas consultas exigiriam o armazenamento de uma quantidade significativa de estado. Para consultas com DISTINCT, poderá utilizar tokens de continuação se adicionar ORDER BY à consulta.

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

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

Conteúdos relacionados