You are currently viewing Must know terms before working with Azure Cosmos DB containers and items

Must know terms before working with Azure Cosmos DB containers and items

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.

From Azure documentation


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 DBDatabase ContainerItem
Core SQL APIDatabaseContainerDocument
Cassandra APIKeyspaceTableRow
MongoDB APIDatabaseCollectionDocument
Gremlin APIDatabaseGraphNode or Edge
Table APIN/ATableItem


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.

_ridThe unique resource identifier for container
_etagEntity tag for optimistic concurrency
_tsLast updated timestamp of container
_selfAddressable URI of container
idUser defined unique name for the container
indexingPolicyAbility to change index path / mode / type.
TimeToLiveSet expiry time on container, after which container will be automatically deleted.
changeFeedPolicyUsed to read changes to items in container
uniqueKeyPolicyUsed to ensure uniqueness of one or more values in logical partition


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.

_ridUnique identifier for an item
_etagEntity tag for optimistic concurrency
_tsTimestamp of last update of an item
_selfAddressable URI of item
idThis 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.

Leave a ReplyCancel reply

This Post Has 6 Comments

  1. devlopingwebs

    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

    1. Manoj Choudhari
      Manoj Choudhari

      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 –

  2. devlopingwebs
    Rathnakar Reddy


    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.
    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?

    1. Manoj Choudhari
      Manoj Choudhari

      I think best option is to use Db Migration Tool. You can refer this post for more details-

  3. Gopalakrishnan Chinnasamy

    The best one. Even Microsoft doesn’t have this much detailed documentation. Especially differences between collection, container and items, documents well explained.