You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/cosmos-db/account-databases-containers-items.md
+39-30Lines changed: 39 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,32 +1,47 @@
1
1
---
2
-
title: Azure Cosmos DB resource model
3
-
description: This article describes Azure Cosmos DB resource model which includes the Azure Cosmos DB account, database, container, and the items. It also covers the hierarchy of these elements in an Azure Cosmos DB account.
2
+
title: Databases, containers, and items
3
+
titleSuffix: Azure Cosmos DB
4
+
description: The Azure Cosmos DB resource model includes the hierarchy of each of an account's elements including; database, container, and items.
4
5
author: seesharprun
5
6
ms.author: sidandrews
6
7
ms.reviewer: mjbrown
7
8
ms.service: cosmos-db
8
-
ms.custom: ignite-2022
9
9
ms.topic: conceptual
10
-
ms.date: 08/03/2022
10
+
ms.date: 02/27/2023
11
+
ms.custom: ignite-2022
11
12
---
12
13
13
-
# Azure Cosmos DB resource model
14
+
# Databases, containers, and items in Azure Cosmos DB
Azure Cosmos DB is a fully managed platform-as-a-service (PaaS). To begin using Azure Cosmos DB, create an Azure Cosmos DB account in an Azure resource group in your subscription. You then create databases and containers within the account.
18
19
19
-
Your Azure Cosmos DB account contains a unique DNS name and can be managed using the Azure portal, ARM or Bicep templates, Azure PowerShell, Azure CLI, or any of the Azure Management SDK's or REST API. For more information, see [how to manage your Azure Cosmos DB account](how-to-manage-database-account.md). For replicating your data and throughput across multiple Azure regions, you can add and remove Azure regions to your account at any time. You can configure your account to have either a single region or multiple write regions. For more information, see [how to add and remove Azure regions to your account](how-to-manage-database-account.md). You can configure the [default consistency](consistency-levels.md) level on an account.
20
+
Your Azure Cosmos DB account contains a unique DNS name and can be managed using many tools including, but not limited to:
21
+
22
+
- Azure portal
23
+
- Azure Resource Manager templates
24
+
- Bicep templates
25
+
- Azure PowerShell
26
+
- Azure CLI
27
+
- Azure Management SDKs
28
+
- Azure REST API
29
+
30
+
For more information, see [how to manage your Azure Cosmos DB account](how-to-manage-database-account.md).
31
+
32
+
For replicating your data and throughput across multiple Azure regions, you can add and remove Azure regions to your account at any time. You can configure your account to have either a single region or multiple write regions. For more information, see [how to add and remove Azure regions to your account](how-to-manage-database-account.md). You can configure the [default consistency](consistency-levels.md) level on an account.
20
33
21
34
## Elements in an Azure Cosmos DB account
22
35
23
-
Currently, you can create a maximum of 50 Azure Cosmos DB accounts under an Azure subscription (this is a soft limit that can be increased via support request). A single Azure Cosmos DB account can virtually manage an unlimited amount of data and provisioned throughput. To manage your data and provisioned throughput, you can create one or more databases within your account, then one or more containers to store your data. The following image shows the hierarchy of elements in an Azure Cosmos DB account:
36
+
Currently, you can create a maximum of 50 Azure Cosmos DB accounts under an Azure subscription. This limitation is a soft limit that can be increased via support request.
37
+
38
+
A single Azure Cosmos DB account can virtually manage an unlimited amount of data and provisioned throughput. To manage your data and provisioned throughput, you can create one or more databases within your account, than one or more containers to store your data. The following image shows the hierarchy of elements in an Azure Cosmos DB account:
24
39
25
-
:::image type="content" source="./media/account-databases-containers-items/hierarchy.png" alt-text="Hierarchy of an Azure Cosmos DB account" border="false":::
40
+
:::image type="content" source="./media/account-databases-containers-items/hierarchy.png" alt-text="Diagram of the hierarchy of an Azure Cosmos DB account including an account, database, and container." :::
26
41
27
42
The following image shows the hierarchy of different entities in an Azure Cosmos DB account:
28
43
29
-
:::image type="content" source="./media/account-databases-containers-items/cosmos-entities.png" alt-text="Azure Cosmos DB account entities" border="false":::
44
+
:::image type="content" source="./media/account-databases-containers-items/cosmos-entities.png" alt-text="Diagram of the relationship between a container and items including sibling entities such as stored procedures, UDFs, and triggers." :::
30
45
31
46
## Azure Cosmos DB databases
32
47
@@ -41,28 +56,27 @@ In Azure Cosmos DB, a database is similar to a namespace. A database is simply a
41
56
42
57
## Azure Cosmos DB containers
43
58
44
-
An Azure Cosmos DB container is where data is stored. Unlike most relational databases which scale up with larger VM sizes, Azure Cosmos DB scales out. Data is stored on one or more servers, called partitions. To increase throughput or storage, more partitions are added. This provides a virtually an unlimited amount of throughput and storage for a container. When a container is created, you need to supply a partition key. This is a property you select from your documents to store. The value of that property is then used to route data to the partition to be written, updated, or deleted. It can also be used in the WHERE clause in queries for efficient data retrieval.
59
+
An Azure Cosmos DB container is where data is stored. Unlike most relational databases which scale up with larger VM sizes, Azure Cosmos DB scales out. Data is stored on one or more servers, called partitions. To increase throughput or storage, more partitions are added. This relationship provides a virtually an unlimited amount of throughput and storage for a container. When a container is created, you need to supply a partition key. The partition key is a property you select from your items to help Azure Cosmos DB distribute the data efficiently across partitions. The value of this property is then used to route data to the appropriate partition to be written, updated, or deleted. The partition key can also be used in the WHERE clause in queries for efficient data retrieval.
45
60
46
-
The underlying storage mechanism for data in Azure Cosmos DB is called a physical partition. These can have a throughput amount up to 10,000 RU/s and store up to 50 GB of data. Azure Cosmos DB abstracts this with a logical partition which can store up to 20 GB of data. Logical partitions allow the service to provide greater elasticity and better management of data on the underlying physical partitions as more partitions are added. To learn more about partitioning and partition keys, see [Partition data](partitioning-overview.md).
61
+
The underlying storage mechanism for data in Azure Cosmos DB is called a physical partition. These physical partitions can have a throughput amount up to 10,000 RU/s and store up to 50 GB of data. Azure Cosmos DB abstracts this partitioning concept with a logical partition, which can store up to 20 GB of data. Logical partitions allow the service to provide greater elasticity and better management of data on the underlying physical partitions as more partitions are added. To learn more about partitioning and partition keys, see [Partition data](partitioning-overview.md).
47
62
48
63
When you create a container, you configure throughput in one of the following modes:
49
64
50
-
***Dedicated throughput**: The throughput provisioned on a container is exclusively reserved for that container. There are two types of dedicated throughput, standard and autoscale. To learn more, see [How to provision throughput on a container](how-to-provision-container-throughput.md).
51
-
52
-
***Shared throughput**: Here throughput is specified at the database level, then shared with up to 25 containers within the database, (excluding containers that have been configured with dedicated throughput). This can be a good option when all of the containers in the database have similar requests and storage needs or when you don't need predictable performance on the data. To learn more, see [How to provision throughput on a database](how-to-provision-database-throughput.md).
65
+
-**Dedicated throughput**: The throughput on a container is exclusively reserved for that container. There are two types of dedicated throughput, standard and autoscale. To learn more, see [How to assign throughput to a container](how-to-provision-container-throughput.md).
66
+
-**Shared throughput**: Here throughput is specified at the database level, then shared with up to 25 containers within the database. Sharing of throughput excludes containers that have been configured with their own dedicated throughput. Shared throughput can be a good option when all of the containers in the database have similar requests and storage needs or when you don't need predictable performance on the data. To learn more, see [How to assign throughput to a database](how-to-provision-database-throughput.md).
53
67
54
68
> [!NOTE]
55
69
> You can not go between dedicated and shared throughput. Containers created in a shared throughput database, cannot be updated to have dedicated throughput. To change a container from shared to dedicated throughput, a new container must be created and data copied to it.
56
70
57
71
Containers are schema-agnostic. Items within a container can have arbitrary schemas or different entities so long as they share the same partition key. For example, an item that represents a customer and one or more items representing all their orders, can be placed in the *same container*. By default, all data added to a container is automatically indexed without requiring explicit indexing. You can customize the indexing for a container by configuring its [indexing policy](index-overview.md).
58
72
59
-
You can set [Time to Live (TTL)](time-to-live.md) on selected items in a container or for the entire container to silently delete those items automatically in the background with unused throughput to avoid impacting performance. However, even if not deleted, any data that has expired will not appear in any reads made. To learn more, see [Configure TTL on your container](how-to-time-to-live.md).
73
+
You can set [Time to Live (TTL)](time-to-live.md) on selected items in a container or for the entire container to silently delete those items automatically in the background with unused throughput to avoid impacting performance. However, even if not deleted, expired data doesn't appear in any read operations. To learn more, see [Configure TTL on your container](how-to-time-to-live.md).
60
74
61
75
Azure Cosmos DB provides a built-in change data capture capability called, [change feed](change-feed.md) that can be used to subscribe to all the changes to data within your container. For more information, see [Change feed in Azure Cosmos DB](change-feed.md).
62
76
63
77
You can register [stored procedures, triggers, user-defined functions (UDFs)](stored-procedures-triggers-udfs.md), and [merge procedures](how-to-manage-conflicts.md) for your container.
64
78
65
-
Data within a container must have a unique `id` property value for each logical partition key value. This can be useful when you want to have a unique constraint within your container. You can also specify a [unique key constraint](unique-keys.md) on your Azure Cosmos DB container that uses one or more different properties and ensures uniqueness of one or more values per logical partition key. If you create a container by using a unique key policy, no new or updated items with values that duplicate the values specified by the unique key constraint can be created. To learn more, see [Unique key constraints](unique-keys.md).
79
+
Data within a container must have a unique `id` property value for each logical partition key value. This property can be useful when you want to have a unique constraint within your container. You can also specify a [unique key constraint](unique-keys.md) on your Azure Cosmos DB container that uses one or more different properties and ensures uniqueness of one or more values per logical partition key. If you create a container by using a unique key policy, no new or updated items with values that duplicate the values specified by the unique key constraint can be created. To learn more, see [Unique key constraints](unique-keys.md).
66
80
67
81
A container is specialized into API-specific entities as shown in the following table:
68
82
@@ -83,16 +97,16 @@ An Azure Cosmos DB container has a set of system-defined properties. Depending o
83
97
|\_etag | System-generated | Entity tag used for optimistic concurrency control | Yes | No | No | No | No |
84
98
|\_ts | System-generated | Last updated timestamp of the container | Yes | No | No | No | No |
85
99
|\_self | System-generated | Addressable URI of the container | Yes | No | No | No | No |
86
-
|id| User-configurable | Name of the container | Yes | Yes | Yes | Yes | Yes |
87
-
|indexingPolicy | User-configurable |Provides the ability to change indexes| Yes | No | Yes | Yes | Yes |
88
-
|TimeToLive | User-configurable |Provides the ability to delete items automatically from a container after a set time period. For details, see [Time to Live](time-to-live.md). | Yes | No | No | No | Yes |
100
+
|ID| User-configurable | Name of the container | Yes | Yes | Yes | Yes | Yes |
101
+
|indexingPolicy | User-configurable |Policy used to build the index for the container.| Yes | No | Yes | Yes | Yes |
102
+
|TimeToLive | User-configurable |Automatically deletes item from a container after a set time period. For details, see [Time to Live](time-to-live.md). | Yes | No | No | No | Yes |
89
103
|changeFeedPolicy | User-configurable | Used to read changes made to items in a container. For details, see [Change feed](change-feed.md). | Yes | No | No | No | Yes |
90
104
|uniqueKeyPolicy | User-configurable | Used to ensure the uniqueness of one or more values in a logical partition. For more information, see [Unique key constraints](unique-keys.md). | Yes | No | No | No | Yes |
91
-
|AnalyticalTimeToLive | User-configurable |Provides the ability to delete items automatically from a container after a set time period. For details, see [Time to Live](analytical-store-introduction.md). | Yes | No | Yes | No | No |
105
+
|AnalyticalTimeToLive | User-configurable |Automatically deletes item a container after a set time period, in the context of an analytical store. For details, see [Analytical store](analytical-store-introduction.md). | Yes | No | Yes | No | No |
92
106
93
107
## Azure Cosmos DB items
94
108
95
-
Depending on which API you use, data can represent either an item in a container, a document in a collection, a row in a table, or a node or edge in a graph. The following table shows the mapping of API-specific entities to an Azure Cosmos DB item:
109
+
Depending on which API you use, individual data entities can represent in many different ways:
96
110
97
111
| Azure Cosmos DB entity | API for NoSQL | API for Cassandra | API for MongoDB | API for Gremlin | API for Table |
98
112
| --- | --- | --- | --- | --- | --- |
@@ -108,7 +122,7 @@ Every Azure Cosmos DB item has the following system-defined properties. Dependin
108
122
|\_etag | System-generated | Entity tag used for optimistic concurrency control | Yes | No | No | No | No |
109
123
|\_ts | System-generated | Timestamp of the last update of the item | Yes | No | No | No | No |
110
124
|\_self | System-generated | Addressable URI of the item | Yes | No | No | No | No |
111
-
|id| Either | User-defined unique name in a logical partition. | Yes | Yes | Yes | Yes | Yes |
125
+
|ID| Either | User-defined unique name in a logical partition. | Yes | Yes | Yes | Yes | Yes |
0 commit comments