Partager via

Pagination dans Azure Cosmos DB for NoSQL

  • Article

S’APPLIQUE À : NoSQL

Dans Azure Cosmos DB for NoSQL, les requêtes peuvent comporter plusieurs pages de résultats. Ce document explique les critères que le moteur de requête d’Azure Cosmos DB for NoSQL utilise pour décider s’il faut répartir les résultats de la requête sur plusieurs pages. Vous pouvez éventuellement utiliser des jetons de continuation pour gérer les résultats de requête qui s’étendent sur plusieurs pages.

Exécutions de requête

Les résultats d’une requête sont parfois répartis sur plusieurs pages. Une exécution de requête distincte génère les résultats de chaque page. Lorsque les résultats de la requête ne peuvent pas être retournés en une seule exécution, Azure Cosmos DB for NoSQL répartit automatiquement les résultats sur plusieurs pages.

Vous pouvez spécifier le nombre maximal d’éléments retournés par une requête en définissant MaxItemCount. Le MaxItemCount est spécifié par requête et indique au moteur de requête de renvoyer ce nombre d’éléments au maximum. Vous pouvez définir MaxItemCount sur -1 si vous ne voulez pas limiter le nombre de résultats par exécution de requête.

De plus, il existe d’autres raisons pour lesquelles le moteur de requête peut être amené à répartir les résultats d’une requête sur plusieurs pages. Les raisons sont les suivantes :

  • Le conteneur a fait l’objet d’une limitation et il n’existait pas d’unités de requête disponibles pour retourner davantage de résultats de requête
  • La réponse d’exécution de requête était trop volumineuse
  • La durée d’exécution de requête était trop longue
  • Il était plus efficace pour le moteur de requête de retourner les résultats dans des exécutions supplémentaires

Le nombre d’éléments retournés par exécution de requête est inférieur ou égal à MaxItemCount. Toutefois, il est possible que d’autres critères aient limité le nombre de résultats que la requête a pu retourner. Si vous exécutez la même requête plusieurs fois, le nombre de pages risque de ne pas être constant. Par exemple, si une requête fait l’objet d’une limitation, il peut y avoir moins de résultats disponibles par page, ce qui signifie que la requête a des pages supplémentaires. Dans certains cas, il est également possible que votre requête retourne une page de résultats vide.

Gérer plusieurs pages de résultats

Pour garantir des résultats de requête précis, vous devez progresser tout au long des pages. Vous devez continuer à exécuter les requêtes jusqu’à ce qu’il n’y ait plus de pages supplémentaires.

Voici quelques exemples de traitement des résultats à partir de requêtes avec plusieurs pages :

Jetons de continuation

Dans les kits SDK .NET et Java, vous pouvez éventuellement utiliser des jetons de continuation comme signet pour la progression de votre requête. Les exécutions de requête Azure Cosmos DB for NoSQL sont sans état côté serveur et peuvent reprendre à tout moment à l’aide du jeton de continuation. Pour le SDK Python, les jetons de continuation ne sont pris en charge que pour les requêtes de partition unique. La clé de partition doit être spécifiée dans l’objet d’options, car elle n’est pas suffisante dans la requête elle-même.

Voici quelques exemples d’utilisation de jetons de continuation :

Si la requête retourne un jeton de continuation, il existe des résultats de requête supplémentaires.

Dans l’API REST d’Azure Cosmos DB for NoSQL, vous pouvez gérer les jetons de continuation avec l’en-tête x-ms-continuation. Comme pour l’interrogation avec le kit SDK .NET ou Java, si l’en-tête de réponse x-ms-continuation n’est pas vide, cela signifie que la requête a des résultats supplémentaires.

Tant que vous utilisez la même version du kit SDK, les jetons de continuation n’expirent pas. Vous pouvez éventuellement restreindre la taille d’un jeton de continuation. Quels que soient la quantité de données et le nombre de partitions physiques dans votre conteneur, les requêtes renvoient un jeton de continuation unique.

Vous ne pouvez pas utiliser de jetons de continuation pour les requêtes avec GROUP BY ou DISTINCT, car ces requêtes nécessitent le stockage d’une grande quantité d’informations d’état. Pour les requêtes avec DISTINCT, vous pouvez utiliser des jetons de continuation si vous ajoutez ORDER BY à la requête.

Voici un exemple de requête avec DISTINCT qui pourrait utiliser un jeton de continuation :

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

Contenu connexe