Home CosmosDB Hierarchy

CosmosDB Hierarchy


As with any database system, there must be some kind of hierarchy behind it that allows grouping of resources together and allow for a smooth flow from the top to the bottom. Cosmos is no different its main hierarchy is:

  • Database Account
  • Database
  • Container

Below is a great image from the MS documentation to show this model


A Database Account is the account you first create in azure when you create a cosmos instance.


Then within a Database Account you can have multiple databases a database much like any other database language allows you to separate out functionality into its own repositories of sorts.


Then within Databases you can have multiple containers. Now think of containers as a namespace within your database, that allows you to further chunk up items.


If you look at our first visual on this page you can see that containers have many child properties underneath. Within a container you can have items obviously, but you can also have Triggers, Stored Procs and User Defined Functions to allow you to control and communicate with your data.



Containers are where you set the majority of your control rules and where you control throughput. When you create a container you can set it up with either Dedicated Throughput or Shared Throughput.

Dedicated Throughput allows you to provision your container with a specific amount of RU/s, essentially allowing you to fine tune your load at a container level. At that level you can also enable standard or autoscale, allowing you to further configure whether or not the throughput should autoscale if it is reached.

Shared Throughput is set at a database level. You set the throughput/RU setting that you would like that database to have, then dependant on the amount of containers you have underneath, the container value is a division of the database limit. For example:

  • Database Throughput – 1000RU/s
  • Container Throughput – 4 Containers under the database @250RU/s reach

System Defined Properties

Both containers and items have system defined properties, these can be likened to SQL properties you’ll find in its base tables. These are used for identification in parts but also allows for viewing key settings set at a container or item level. The below visuals are taken from the MS documentation and list the available properties.

Container Properties

System-defined propertySystem-generated or user-configurablePurposeAPI for NoSQLAPI for CassandraAPI for MongoDBAPI for GremlinAPI for Table
_ridSystem-generatedUnique identifier of containerYesNoNoNoNo
_etagSystem-generatedEntity tag used for optimistic concurrency controlYesNoNoNoNo
_tsSystem-generatedLast updated timestamp of the containerYesNoNoNoNo
_selfSystem-generatedAddressable URI of the containerYesNoNoNoNo
idUser-configurableName of the containerYesYesYesYesYes
indexingPolicyUser-configurableProvides the ability to change indexesYesNoYesYesYes
TimeToLiveUser-configurableProvides the ability to delete items automatically from a container after a set time period. For details, see Time to Live.YesNoNoNoYes
changeFeedPolicyUser-configurableUsed to read changes made to items in a container. For details, see Change feed.YesNoNoNoYes
uniqueKeyPolicyUser-configurableUsed to ensure the uniqueness of one or more values in a logical partition. For more information, see Unique key constraints.YesNoNoNoYes
AnalyticalTimeToLiveUser-configurableProvides the ability to delete items automatically from a container after a set time period. For details, see Time to Live.YesNoYesNoNo
This post is licensed under CC BY 4.0 by the author.