Cosmos DB - Intro
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
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.