If you have created Cosmos DB account, then you must be knowing some basic things about containers and items. You also must be knowing that Cosmos DB also supports multiple APIs in addition to its Core SQL API.
Let’s have a look at different terms that can be used to refer containers and items and what operations can be used on them. We will also have look at what are system properties added to every item and what do they mean. This will be very handy when you will write code.
Cosmos DB Entities Hierarchy
There are different entities available under Cosmos DB accounts, databases, containers and items. Cosmos DB also has entities like stored procedures, user defined functions, triggers, conflicts.
The following diagram shows hierarchy of these entities.
Databases
Every Cosmos DB account can have one or more databases. It is like namespaces, which is used to manage the containers. You can perform Create New, Update database, Read Database and Enumerate all databases operations on Cosmos DB account.
Below table shows the APIs vs the terminology used for databases. Please note that for table API, there is no concept of database.
| Azure Cosmos DB | Database | Container | Item |
|---|---|---|---|
| Core SQL API | Database | Container | Document |
| Cassandra API | Keyspace | Table | Row |
| MongoDB API | Database | Collection | Document |
| Gremlin API | Database | Graph | Node or Edge |
| Table API | N/A | Table | Item |
Containers
Every database can have multiple containers. An Azure Cosmos DB container is unit of scalability for both provisioned throughput and storage.
A container horizontally partitioned based on partition key and then the data can be replicated across different Azure regions. A container can scale elastically based on either dedicated throughput or shared throughput settings.
One important characteristics of container is absence of schema management. In a container, you can create items of varying schema. That is because container does not enforce schema on the containers.
You can also set time to live for item or for the container to gracefully remove them. When time to live expires, then the items are automatically removed by Cosmos DB.
You can register stored procedures, triggers, user-defined functions (UDFs), and merge procedures for your Azure Cosmos container.
You can perform Create new container, Update container, Read container, Delete container and Enumerate all containers operations on the containers.
Below are the system properties of every container. First four properties are system generated, while others can be configured by users.
| Property | Purpose |
|---|---|
| _rid | The unique resource identifier for container |
| _etag | Entity tag for optimistic concurrency |
| _ts | Last updated timestamp of container |
| _self | Addressable URI of container |
| id | User defined unique name for the container |
| indexingPolicy | Ability to change index path / mode / type. |
| TimeToLive | Set expiry time on container, after which container will be automatically deleted. |
| changeFeedPolicy | Used to read changes to items in container |
| uniqueKeyPolicy | Used to ensure uniqueness of one or more values in logical partition |
Items
You can use any of the APIs to add items to the container. Every item in container has some system generated properties or user defined properties.
User defined properties are the properties required for your application. Below are the system generated properties and their purposes.
Depending on which API are you using to interact with items some of these may not be exposed. The Core SQL API for Cosmos DB can be used to access all of them.
| Property | Purpose |
|---|---|
| _rid | Unique identifier for an item |
| _etag | Entity tag for optimistic concurrency |
| _ts | Timestamp of last update of an item |
| _self | Addressable URI of item |
| id | This property can either be generated by system or user can specify them while creating container. It is to uniquely identify the item. |
You can perform Insert, Replace, Upsert, Delete and Read operations on the items.
I hope this helps you to increase your vocabulary around Cosmos DB. Let me know your thoughts.
Hi,
Thanks for providing the information.
I have question, on Cosmos DB, Single Database with multiple Containers vs Multiple Databases within that single Container.
Which one is the best practice to choose for a micro-service applications.
And what are the PROS and CONS for it
I dont think it is possible to have multiple databases within a single container. Generally, a cosmosdb database can have one or more containers ( think of container somewhat similar to SQL table, but not same as SQL table) and every container can have items (think of each item somewhat similar to row in a SQL table, but row and item is not same construct). Refer docs for more details – https://docs.microsoft.com/en-us/azure/cosmos-db/account-databases-containers-items
Hi,
I have another question,
Compare to SQL Vs No Sql what is best approach to do when we want to migrate the application from sql to cosmos.
Example:
I have four table in SQL in that two tables are tightly coupled like Parent and Child and the other two tables are loosely coupled but have reference in each of the table
How should i migrate these model in cosmos?
I think best option is to use Db Migration Tool. You can refer this post for more details-https://thecodeblogger.com/2019/12/17/migrate-your-data-to-azure-cosmos-db-using-data-migration-tool/
The best one. Even Microsoft doesn’t have this much detailed documentation. Especially differences between collection, container and items, documents well explained.
Glad to know it helped ! Enjoy !