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 Reply