Collections
Azure Cosmos DB est une base de données multimodèle distribuée à l’échelle mondiale qui prend en charge les modèles de données de document, de graphique et de clé-valeur. Le contenu de cette section est destiné à la création, à l’interrogation et à la gestion des ressources de collection à l’aide de l’API SQL via REST.
L’API REST prend en charge les opérations CRUD de base sur les ressources sous un compte de base de données. Une collection est un conteneur de documents JSON et de la logique d'application JavaScript associée, à savoir les procédures stockées, les déclencheurs et les fonctions définies par l'utilisateur. Cette rubrique décrit les opérations REST utilisées pour gérer les collections de documents.
Notes
Ces articles de référence sur les API montrent comment créer des ressources à l’aide de l’API de plan de données Azure Cosmos DB. Avec l’API de plan de données, vous pouvez configurer des options de base telles que la stratégie d’indexation et les clés de partition, comme vous le pouvez avec les SDK Cosmos DB. Si vous avez besoin d’une prise en charge complète des fonctionnalités pour toutes les ressources Azure Cosmos DB, nous vous recommandons d’utiliser le fournisseur de ressources Cosmos DB.
Une collection est mappée à un conteneur dans Azure Cosmos DB. Par conséquent, il s’agit d’une entité facturable, où le coût est déterminé par le débit provisionné exprimé en unités de requête par seconde. Les collections peuvent s’étendre sur une ou plusieurs partitions/serveurs et être mises à l’échelle en termes de débit. Les collections sont automatiquement partitionnées en un ou plusieurs serveurs physiques par Azure Cosmos DB.
Dans la mesure où une collection est une ressource système, son schéma est fixe. Le chemin d’accès à l’URI d’une collection est représenté par des colls dans le modèle de ressource.
L’exemple suivant illustre la définition JSON d’une collection :
{
"id": "testcoll",
"indexingPolicy": {
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*",
"indexes": [
{
"kind": "Range",
"dataType": "String",
"precision": -1
},
{
"kind": "Range",
"dataType": "Number",
"precision": -1
}
]
}
],
"excludedPaths": []
},
"partitionKey": {
"paths": [
"/AccountNumber"
],
"kind": "Hash"
},
"_rid": "PD5DALigDgw=",
"_ts": 1459200611,
"_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",
"_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",
"_docs": "docs/",
"_sprocs": "sprocs/",
"_triggers": "triggers/",
"_udfs": "udfs/",
"_conflicts": "conflicts/"
}
| Propriété | Description |
|---|---|
| id | Il s’agit du nom unique qui identifie la nouvelle collection. |
| indexingPolicy | Il s’agit des paramètres de stratégie d’indexation pour la collection. |
| partitionKey | Il s’agit des paramètres de configuration de partitionnement pour la collecte. |
| _Débarrasser | Il s’agit d’une propriété générée par le système. L’ID de ressource (_rid) est un identificateur unique qui est également hiérarchique en fonction de la pile de ressources sur le modèle de ressource. Il est utilisé en interne pour le positionnement et la navigation dans la ressource d'autorisation. |
| _Ts | Il s’agit d’une propriété générée par le système. Elle spécifie l'horodateur de la dernière mise à jour de la ressource. La valeur est un horodateur. |
| _self | Il s’agit d’une propriété générée par le système. Il s'agit de l'URI adressable unique pour la ressource. |
| _Etag | Il s’agit d’une propriété générée par le système qui représente l’etag de ressources requis pour le contrôle d’accès concurrentiel optimiste. |
| _Doc | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource documents. |
| _sprocs | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource de procédures stockées (sprocs). |
| _Déclenche | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource déclencheurs. |
| _Udf | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource de fonctions définies par l’utilisateur (udfs). |
| _Conflits | Il s’agit d’une propriété générée par le système qui spécifie le chemin d’accès adressable de la ressource de conflits. Lors d'une opération sur une ressource au sein d'une collection, si un conflit se produit, les utilisateurs peuvent inspecter les ressources en conflit en exécutant une commande GET sur le chemin d'accès à l'URI des conflits. |
Propriétés sous Stratégie d’indexation
| Propriété | Description |
|---|---|
| Automatique | Indique si l'indexation automatique est activée ou désactivée. La valeur par défaut est True. Par conséquent, tous les documents sont indexés. La définition de la valeur sur False permet la configuration manuelle des chemins d’indexation. |
| indexingMode | Par défaut, le mode d’indexation est Cohérent. Cela signifie que l’indexation se produit de manière synchrone pendant l’insertion, le remplacement ou la suppression de documents. Pour que l'indexation se produise de façon asynchrone, définissez le mode d'indexation différé. |
| includedPaths | Tableau contenant les chemins d'accès de documents à indexer. Par défaut, deux chemins d’accès sont inclus : le chemin /, qui spécifie que tous les chemins d’accès au document sont indexés, et le chemin d’accès _ts, qui indexe pour une comparaison de plage d’horodatages. |
| excludedPaths | Tableau contenant des chemins d'accès de documents à exclure de l'indexation. |
Propriétés sous Chemins inclus
| Propriété | Description |
|---|---|
| path | Chemin auquel le comportement d’indexation s’applique. Le chemin des index commence par la racine et se termine généralement par l’opérateur générique ?, ce qui signifie qu’il y a plusieurs valeurs possibles pour le préfixe. Par exemple, pour traiter SELECT * FROM Families F WHERE F.familyName = "Andersen", vous devez inclure un chemin d’index pour /familyName/? dans la stratégie d’index de la collection. Les chemins d’index peuvent aussi utiliser l’opérateur générique * pour spécifier le comportement des chemins de manière récursive sous le préfixe. Par exemple, /payload/* peut être utilisé pour inclure tout sous la propriété de charge utile de l’indexation. |
| dataType | Il s’agit du type de données auquel le comportement d’indexation est appliqué. Il peut s’agir de String, Number, Point, Polygon ou LineString. Les valeurs booléennes et null sont automatiquement indexées |
| kind | Type de l'index. Les index de hachage sont utiles pour les comparaisons d’égalité, tandis que les index range sont utiles pour l’égalité, les comparaisons de plages et le tri. Les index spatiaux sont utiles pour les requêtes spatiales. |
| precision | Précision de l’index. Peut être défini sur -1 pour une précision maximale ou entre 1 et 8 pour Nombre et 1-100 pour String. Non applicable aux types de données Point, Polygon etLineString . |
Propriétés sous Chemins d’accès exclus
| Propriété | Description |
|---|---|
| path | Chemin d’accès exclu de l’indexation. Les chemins d’index commencent par la racine (/) et se terminent généralement par l’opérateur * générique.. Par exemple, /payload/* permet d’exclure de l’indexation tout ce qui figure sous la propriété « payload ». |
Propriétés sous Clé de partition
| Propriété | Description |
|---|---|
| path | Tableau de chemins à l’aide desquels les données de la collection peuvent être partitionnée. Les chemins ne doivent pas contenir de caractère générique ou de barre oblique de fin. Par exemple, la propriété JSON « AccountNumber » est spécifiée en tant que « /AccountNumber ». Le tableau ne doit contenir qu’une seule valeur. |
| kind | Algorithme utilisé pour le partitionnement. Seul Le hachage est pris en charge. |
Stratégie d’indexation
Lorsque des documents sont ajoutés à une collection, Cosmos DB indexe automatiquement les documents par défaut, ce qui permet aux documents d’être interrogés. Vous configurez la stratégie d'indexation au niveau de la collection. Étant donné que la stratégie d'indexation est définie au niveau de la collection, chaque collection au sein d'une base de données peut avoir une stratégie d'indexation spécifique.
La stratégie d'indexation pour une collection peut spécifier les options suivantes :
Automatique : vous pouvez choisir si vous souhaitez que la collection indexe automatiquement tous les documents ou non. Par défaut, tous les documents sont indexés automatiquement, mais vous pouvez choisir de désactiver cette option. Lorsque l’indexation est désactivée, les documents sont accessibles uniquement par le biais de leurs liens réflexifs ou de requêtes avec l’ID.
Mode d’indexation : vous pouvez choisir entre les mises à jour d’index synchrones (cohérentes), asynchrones (différées) et aucune indexation (aucune). Par défaut, l'index est mis à jour de façon synchrone à chaque action d'insertion, de remplacement ou de suppression effectuée sur un document de la collection. Cette mise à jour permet aux requêtes de respecter le même niveau de cohérence que celui des lectures de document sans délai de rattrapage de l’index.
Types d’index et précision : le type ou le schéma utilisé pour les entrées d’index a un impact direct sur le stockage et les performances des index. Pour un schéma utilisant une précision supérieure, les requêtes sont généralement plus rapides. Toutefois, il existe également une surcharge de stockage plus importante pour l'index. Le choix d'une précision inférieure peut entraîner une augmentation du nombre de documents à traiter lors de l'exécution des requêtes, mais une baisse de la charge de stockage.
Chemins d’accès aux index : dans les documents, vous pouvez choisir les chemins qui doivent être inclus ou exclus de l’indexation, ce qui peut offrir des performances d’écriture améliorées et un stockage d’index inférieur pour les scénarios où les modèles de requête sont connus à l’avance.
Les tableaux suivants présentent des exemples de chemins d'accès d'indexation et la manière dont ils sont utilisés dans les requêtes.
| Propriété | Description |
|---|---|
| /* | Chemin par défaut de la collection. Récursif et s'applique à toute l'arborescence du document. |
| /prop/? | Chemin d’index requis pour traiter les requêtes comme les suivantes (avec, respectivement, les types hachage ou plage) : SELECT * FROM collection c WHERE c.prop = "value" SELECT * FROM collection c WHERE c.prop > 5 SELECT * FROM collection c ORDER BY c.prop |
| /prop/* | Chemin d'index pour tous les chemins d'accès sous l'étiquette spécifiée. Fonctionne avec les requêtes suivantes : SELECT * FROM collection c WHERE c.prop = "value" SELECT * FROM collection c WHERE c.prop.subprop > 5 SELECT * FROM collection c WHERE c.prop.subprop.nextprop = "value" SELECT * FROM collection c ORDER BY c.prop |
| /props/[]/? | Chemin d’index requis pour traiter les requêtes d’itération et JOIN sur des tableaux de scalaires tels que ["a », « b », « c"] : SELECT tag FROM tag IN collection.props WHERE tag = "value" SELECT tag FROM collection c JOIN tag IN c.props WHERE tag > 5 |
| /props/[] /subprop/? | Chemin d’index requis pour traiter les requêtes d’itération et JOIN sur des tableaux d’objets tels que [{subprop: « a"}, {subprop: « b"}] : SELECT tag FROM tag IN collection.props WHERE tag.subprop = "value" SELECT tag FROM collection c JOIN tag IN c.props WHERE tag.subprop = "value" |
| /prop/subprop/? | Chemin d’index requis pour traiter les requêtes (avec, respectivement, les types hachage ou plage) : SELECT * FROM collection c WHERE c.prop.subprop = "value" SELECT * FROM collection c WHERE c.prop.subprop > 5 SELECT * FROM collection c ORDER BY c.prop.subprop |
Pour plus d’informations sur les stratégies d’indexation Cosmos DB, consultez Stratégies d’indexation Cosmos DB. Dans le cadre de la documentation relative à l'API REST, tous les exemples utilisent une indexation automatique.
Offres et niveaux de performances
Lorsqu’une collection est créée, une ressource Offer est également créée qui fait référence à la collection créée. La ressource Offer contient des informations de configuration sur le débit de collecte en unités de requête par seconde et unités de requête par minute.
Le niveau de performances d’une collection peut être modifié à l’aide de Remplacer l’offre.
Tâches
Vous pouvez effectuer les opérations suivantes avec les collections de documents :