Cosmos DB : bien choisir sa clé de partition
Partitions logiques et physiques, limites, partitions chaudes, requêtes inter-partitions, clés synthétiques et hiérarchiques, avec exemples de bonnes et mauvaises clés.
Dans ma formation Cosmos DB, tout le monde répète la même chose : « le choix de la clé de partition est la décision la plus importante ». Quand on vient de SQL Server, où on peut ajouter un index après coup, c'est déroutant. Voici ce que je retiens, avec des exemples de bonnes et mauvaises clés (conteneur orders dans la base AppDb).
Partitions logiques et physiques
flowchart LR
A["Item (customerId = C42)"] --> B["Hash de la clé de partition"]
B --> C["Partition logique C42 (max 20 Go)"]
C --> D["Partition physique 1 (max 50 Go, 10 000 RU/s)"]
E["Partition logique C77"] --> D
F["Partition logique C99"] --> G["Partition physique 2"]
- Partition logique : tous les items qui partagent la même valeur de clé de partition. Max 20 Go de données et 10 000 RU/s. Elle définit aussi le périmètre des transactions (procédures stockées, triggers, batch transactionnel).
- Partition physique : le stockage réel, géré entièrement par le service (on ne la contrôle pas). Max 50 Go et 10 000 RU/s. Plusieurs partitions logiques tiennent dans une physique. Quand les données ou le débit grossissent, le service divise les partitions physiques sans interruption.
- Le débit provisionné se répartit à parts égales entre les partitions physiques. Exemple de la doc : 18 000 RU/s sur 3 partitions physiques = 6 000 RU/s chacune.
Côté SQL Server, la clé de partition ressemble à une clé de sharding : elle sert au routage, pas à un index secondaire.
Ce que doit être une bonne clé
D'après la doc, la propriété doit :
- avoir une valeur qui ne change pas (les valeurs de clé de partition sont immuables : pour « déplacer » un item il faut le recréer puis supprimer l'ancien, sans atomicité entre deux partitions) ;
- avoir une cardinalité élevée (beaucoup de valeurs distinctes) ;
- répartir uniformément le stockage et la consommation de RU ;
- idéalement apparaître dans les filtres d'égalité de vos requêtes ;
- avoir une valeur de 2048 octets au plus (101 octets si les « large partition keys » ne sont pas activées).
Le chemin accepte lettres, chiffres et underscores ; la valeur est une chaîne ou un nombre (la doc conseille des chaînes si les nombres peuvent dépasser la précision IEEE 754).
Exemples bons et mauvais
| Clé | Verdict | Pourquoi |
|---|---|---|
/customerId (nombreux clients, trafic équilibré) |
Bon | Cardinalité élevée, requêtes « commandes d'un client » en une seule partition |
/id |
Bon pour les lectures par id | Répartition parfaite, lecture par point efficace, mais toute requête sur une autre propriété devient inter-partitions |
/status (3 valeurs) |
Mauvais | Faible cardinalité, partitions chaudes et limite de 20 Go vite atteinte |
/orderDate en écriture intensive |
Mauvais | Toutes les écritures du jour tombent sur la même partition (exemple IoT de la doc) |
/tenantId avec un très gros locataire |
Risqué | Le gros locataire devient une partition chaude et peut dépasser 20 Go |
| GUID aléatoire que personne ne filtre | Piège | Les écritures se répartissent bien, mais chaque lecture par autre critère est inter-partitions |
Partition chaude et requêtes inter-partitions
Une partition chaude apparaît quand quelques valeurs de clé concentrent le trafic : la partition physique concernée dépasse son budget de RU et renvoie des 429, alors que le conteneur dans son ensemble a de la marge. Dans le portail : Insights, Throughput, « Normalized RU Consumption (%) By PartitionKeyRangeID ». Si une partition est à 100 % et les autres à 30 %, c'est suspect. Avec les journaux de diagnostic, on voit les clés les plus coûteuses :
CDBPartitionKeyRUConsumption
| where TimeGenerated >= ago(24h)
| where CollectionName == "orders"
| where isnotempty(PartitionKey)
| summarize sum(RequestCharge) by PartitionKey, OperationName, bin(TimeGenerated, 1s)
| order by sum_RequestCharge desc
Une requête sans la clé de partition dans son filtre est dite inter-partitions : elle interroge toutes les partitions physiques, avec un surcoût d'environ 2 à 3 RU par partition physique. Sur un petit conteneur (une ou deux partitions) ce n'est pas gênant. La doc place le seuil de vigilance autour de 30 000 RU/s provisionnés ou 100 Go de données.
Clés synthétiques et hiérarchiques
- Clé synthétique : on fabrique une propriété en combinant plusieurs champs (par exemple client + date) pour obtenir une meilleure répartition. Contrepartie : une requête qui ne filtre que sur un des deux champs redevient inter-partitions.
- Clé de partition hiérarchique (sous-partitionnement) : jusqu'à trois niveaux (par exemple
/tenantId,/userId,/sessionId). Une valeur du premier niveau peut alors dépasser 20 Go, et les requêtes qui filtrent sur le premier niveau (ou un préfixe) sont routées vers un sous-ensemble de partitions. Limites : à définir à la création du conteneur, API NoSQL uniquement, SDK récents requis. Le premier niveau doit avoir une cardinalité élevée.
Un filtre uniquement sur le deuxième ou troisième niveau reste une requête inter-partitions complète.
Retour d'expérience
- La clé ne se modifie pas sur place : il faut migrer vers un nouveau conteneur (jobs de copie de conteneur, ou flux de modifications). Les index secondaires globaux (global secondary indexes) offrent une autre piste pour des clés différentes selon les requêtes.
- Avant de choisir, lister les 3 à 5 requêtes principales et leurs filtres d'égalité.
- Surveiller la taille des partitions logiques avec une alerte Azure Monitor avant les 20 Go.
- Un petit conteneur pardonne beaucoup ; c'est la croissance qui révèle les mauvais choix.