Paginación en Azure Cosmos DB for NoSQL

  • Artículo

SE APLICA A: NoSQL

En Azure Cosmos DB for NoSQL, las consultas pueden tener varias páginas de resultados. En este documento se explican los criterios que el motor de consultas de Azure Cosmos DB for NoSQL utiliza para decidir si dividir los resultados de la consulta en varias páginas. Opcionalmente, puede usar tokens de continuación para administrar los resultados de la consulta que abarcan varias páginas.

Ejecuciones de consultas

A veces, los resultados de la consulta se dividen en varias páginas. Una ejecución de consulta independiente genera los resultados de cada página. Cuando los resultados de la consulta no se pueden devolver en una sola ejecución, Azure Cosmos DB for NoSQL divide automáticamente los resultados en varias páginas.

Puede especificar el número máximo de elementos devueltos por una consulta estableciendo el elemento MaxItemCount. MaxItemCount se especifica por solicitud e indica que el motor de consulta devolverá ese número de elementos o menos. Puede establecer MaxItemCount en -1 si no desea establecer un límite para el número de resultados por ejecución de consulta.

Además, hay otras razones por las que el motor de consultas puede necesitar dividir los resultados de la consulta en varias páginas. Estas razones incluyen las siguientes:

  • El contenedor estaba limitado y no había ninguna RU disponible para devolver más resultados de la consulta.
  • La respuesta de la ejecución de la consulta era demasiado grande.
  • La hora de ejecución de la consulta era demasiado larga.
  • Era más eficaz que el motor de consultas devolviera los resultados en ejecuciones adicionales

El número de elementos devueltos por la ejecución de la consulta siempre es menor o igual que MaxItemCount. Sin embargo, es posible que otros criterios hayan limitado el número de resultados que la consulta podría devolver. Si ejecuta la misma consulta varias veces, el número de páginas puede no ser constante. Por ejemplo, si una consulta está limitada, puede haber menos resultados disponibles por página, lo que significa que la consulta tiene páginas adicionales. En algunos casos, también es posible que la consulta devuelva una página vacía de resultados.

Administrar varias páginas de resultados

Para garantizar resultados de consulta precisos, debe supervisar todas las páginas. Debe continuar ejecutando las consultas hasta que no haya ninguna página adicional.

Estos son algunos ejemplos del procesamiento de los resultados de las consultas con varias páginas:

Tokens de continuación

En el SDK de .NET y el SDK de Java, puede usar opcionalmente los tokens de continuación como un marcador del progreso de la consulta. Las ejecuciones de consultas de Azure Cosmos DB for NoSQL no tienen estado en el lado servidor y se pueden reanudar en cualquier momento con el token de continuación. Para el SDK de Python, los tokens de continuación solo se admiten para consultas de partición única. La clave de partición debe especificarse en el objeto de opciones porque no es suficiente para que sea en la propia consulta.

Este es un ejemplo de uso de los tokens de continuación:

Si la consulta devuelve un token de continuación, significa que hay resultados de consulta adicionales.

En la API de REST de Azure Cosmos DB for NoSQL, puede administrar los tokens de continuación con el encabezado x-ms-continuation. Al igual que con las consultas mediante el SDK de .NET o Java, si el encabezado de respuesta x-ms-continuation no está vacío, significa que la consulta tiene resultados adicionales.

Siempre que use la misma versión del SDK, los tokens de continuación nunca expiran. Opcionalmente, puede restringir el tamaño de un token de continuación. Independientemente de la cantidad de datos o el número de particiones físicas del contenedor, las consultas devuelven un único token de continuación.

No puede usar tokens de continuación para las consultas con GROUP BY o DISTINCT, porque estas consultas requerirían almacenar una cantidad significativa de estados. En el caso de las consultas con DISTINCT, puede usar tokens de continuación si agrega ORDER BY a la consulta.

Este es un ejemplo de una consulta con DISTINCT que podría usar un token de continuación:

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

Contenido relacionado