DocumentDB in Azure: A Beginner's Guide

DocumentDB in Azure is a NoSQL database service that stores data in JSON format.

DocumentDB is designed for modern web and mobile applications, offering flexible schema and high scalability.

It's perfect for handling large amounts of unstructured or semi-structured data, such as documents, images, and videos.

DocumentDB provides a simple and intuitive API for interacting with the database, making it easy to get started with development.

You can store any type of document in DocumentDB, from simple key-value pairs to complex documents with nested structures.

See what others are reading: Azure Documentdb

To get started with DocumentDB in Azure, you'll need to create a DocumentDB account. This can be done through the Azure portal.

You can choose from three different pricing tiers: Basic, Standard, and Premium. Each tier has its own set of features and limitations.

DocumentDB accounts can be created in any Azure region, allowing for global distribution and scalability.

For more insights, see: Documentdb

To get started with Azure Cosmos DB, first read the official announcement blog and technical overview blog to understand the service's purpose and capabilities.

These two blogs will give you a solid foundation to build upon. Next, take some time to understand the core concepts of Azure Cosmos DB, including its features and how it works.

Once you have a good grasp of the basics, head over to the pricing page to understand how you'll be billed for using the service. This will help you plan and budget accordingly.

Finally, take some time to read the documentation, which will provide you with more in-depth information on Azure Cosmos DB's capabilities and how to use them effectively.

Microsoft.Azure 2.22.0 is a significant release that includes various features and improvements.

The README file provides a comprehensive overview of the library, including its purpose, usage, and installation instructions.

You can find the dependencies required for Microsoft.Azure 2.22.0 in the Dependencies section of the documentation.

Here's a list of the frameworks supported by Microsoft.Azure 2.22.0:

The Used By section highlights the projects and applications that utilize Microsoft.Azure 2.22.0.

Release Notes for Microsoft.Azure 2.22.0 are available, providing detailed information on the changes, bug fixes, and new features introduced in this release.

Versions of Microsoft.Azure are documented, allowing you to easily compare the features and changes between different releases.

Collections in Azure Cosmos DB are assigned a specific amount of storage space and transactional throughput, measured in Request Units (RUs).

You can manage the scaling of your Cosmos DB by adjusting the Request Units (RUs) for each collection, allowing you to control the throughput and storage needs of your application.

Partitioning is a feature of Azure Cosmos DB that allows you to distribute the provisioned throughput of a collection evenly among the partitions within a collection. This can be done automatically using a partition key.

DocumentDB now supports three new purchase options, which provide a guaranteed, reserved level of throughput and request processing over high-performance SSD-based storage.

These performance levels can be set through the Azure portal or one of the DocumentDB SDKs, making it easy to adjust them at any point to meet the unique needs of your application.

You can control how you consume service capacity with these performance levels, allowing you to scale your application as needed.

Hourly billing is also available for the standard pricing tier, giving you more flexibility in managing your costs.

Performance levels provide a guaranteed level of throughput and request processing, making them ideal for applications that require high performance and reliability.

Continuous Mode Properties are crucial for ensuring seamless backups in your system. ContinuousModeProperties is the configuration for continuous mode backup.

Continuous mode can be set to either 'Continuous30Days' or 'Continuous7Days', depending on your needs. The tier enum indicates the type of continuous backup mode.

Here's a breakdown of the two options:

The type of continuous mode should always be set to 'Continuous' for this configuration to work.

Collections in Cosmos DB are assigned a specific amount of storage space and transactional throughput, measured in Request Units (RUs).

You can choose to organize your documents into a collection in any manner that logically makes sense, such as creating a single collection per customer.

Partitioning is a feature of Azure Cosmos DB that allows you to shard your data automatically using a partition key. This is completely transparent to your application.

Partitioning is always done at the collection level, not at the Azure Cosmos DB account level. You can have a collection that is a single partition alongside multiple partition collections.

Single partition collections have a 10 GB storage limit and can have up to 10,000 RUs.

To manage scaling of Cosmos DB, you need to consider the provisioned throughput of a collection, which is distributed evenly among the partitions within a collection.

Here are some key things to keep in mind when managing Cosmos DB scaling:

Database configuration is crucial for Azure Cosmos DB. You can choose between 'FullFidelity' and 'WellDefined' schema types for analytical storage.

To configure your database account, you'll need to decide on the analytical storage configuration, which includes options like enabling storage analytics and choosing between 'FullFidelity' and 'WellDefined' schema types.

A good database configuration also involves setting up the account's capabilities, such as enabling automatic failover and burst capacity. You can enable automatic failover to ensure the write region is always available, and burst capacity to handle sudden increases in traffic.

Here are some key configuration options to consider:

Analytical Storage Configuration is a crucial aspect of database configuration, and it's essential to understand the options available to you.

The schemaType for analytical storage can be either 'FullFidelity' or 'WellDefined'.

To enable analytical storage, you'll need to set the enableAnalyticalStorage property to true. This will allow you to store and analyze data in a way that's optimized for business intelligence and analytics.

Here are the possible values for the schemaType:

By understanding these options, you can make informed decisions about how to configure your analytical storage and ensure that it meets your business needs.

Consistency Policy is a crucial aspect of database configuration, and it's essential to understand the different consistency levels available.

The default consistency level in Cosmos DB is 'Session', which guarantees strong consistency for writers that they have written, but readers and other writer sessions are eventually consistent.

There are five consistency levels in total, each with its own trade-offs between consistency and performance.

Here are the five consistency levels in Cosmos DB:

The 'Bounded Staleness' consistency level requires two additional settings: maxIntervalInSeconds and maxStalenessPrefix. These settings determine the amount of staleness tolerated and the number of stale requests tolerated, respectively.

The accepted range for maxIntervalInSeconds is 5-86400 seconds, and the accepted range for maxStalenessPrefix is 1-2,147,483,647.

Continuous backup is a crucial aspect of database configuration. It ensures that your data is safely backed up in real-time, preventing data loss in case of system failures or human errors.

The ContinuousModeBackupPolicy allows you to configure continuous mode backup. This policy is required for continuous backup mode.

Continuous backup mode can be configured in two different tiers: Continuous30Days and Continuous7Days. The tier you choose depends on your specific needs and data retention requirements.

Here's a summary of the continuous backup options:

The type of continuous backup mode is always 'Continuous' and is a required configuration value.

Managing multiple regions in Azure Cosmos DB is a powerful feature that allows you to distribute data globally and reduce latency for users. This can be achieved by replicating data to multiple regions, which can improve performance.

To distribute data globally, you need to enable geo-configuration for your Azure Cosmos DB account. This involves selecting regions to add as read regions, which can outnumber write regions and improve performance.

In the Azure portal, navigate to your Azure Cosmos DB account and click on Replicate data globally under the Settings menu.

You can select regions to add by clicking on the map. These new regions are read regions. Read regions often outnumber write regions, which can drastically improve the performance of your application.

Here's a summary of the key settings:

After setting up the new regions, click on Automatic Failover on the top of the Replicate data globally blade. You can then move the slider to on and optionally change the priority of the read regions by dragging them up or down.

DocumentDB takes a rather drastic approach to indexing, indexing all the fields of the documents by default.

This approach gives excellent query performance out of the box. However, it does come at a cost, wasting some processing time and storage space.

For those who prefer a more controlled approach, custom indexing policies can be defined to tailor indexing to specific needs.

Implementing a MongoDB database is a breeze with Azure Cosmos DB. Existing MongoDB drivers are compatible with Azure Cosmos DB, making the transition smooth and hassle-free.

You can switch from MongoDB to Azure Cosmos DB by simply changing the connection string. This is a huge time-saver, especially for large-scale applications.

Existing MongoDB tooling can also be used with Azure Cosmos DB, eliminating the need to learn new tools. This means you can leverage your existing expertise and workflow.

Discover more: Azure Mongodb Atlas

Creating a Cosmos DB database and collections is a straightforward process. You must have at least one database in your Cosmos DB account.

A database is a logical container that can hold collections of documents and users. Collections store JSON documents of the same type and purpose, similar to a SQL server table.

Collections don't enforce a particular schema, so documents can have different properties and data types. Azure Cosmos DB DocumentDB handles non-existent columns on a document by ignoring them.

To create a collection, you can add one to your existing database or create a new database and collection together. You can also create a single partition collection by following a specific process.

Here are the steps to create a single partition collection:

A good partition key should have a high number of distinct values without being unique to each individual document. This can be a geographic location, a large data range, department, or customer type.

The storage size for documents with the same partition key is 10 GB. It's essential to choose the right partition key, as it will also be a transaction boundary for stored procedures.

Creating a single partition collection in Azure Cosmos DB is a straightforward process. To get started, navigate to your Azure Cosmos DB account in the Azure portal and click on the "+"Add Collection" button on the Overview blade.

You'll then be taken to the Add Collection blade, where you'll need to provide a name for the database and collection, set the storage capacity, and choose the throughput. Don't worry about the partition key for now - leave it empty.

Here's a quick rundown of the key benefits of single partition collections: they have a 10 GB storage limit and can handle up to 10,000 Request Units (RUs). This makes them perfect for smaller datasets or applications that don't require a lot of scalability.

It's worth noting that single partition collections are always done at the collection level, not at the Azure Cosmos DB account level. This means you can have a mix of single and multi-partition collections within the same account.

In terms of choosing the right storage capacity, consider the size of your dataset and the expected growth rate. You can always scale up or down later if needed.

If you're not sure where to start, consider the following best practices for choosing a partition key: choose a key that has a high number of distinct values without being unique to each individual document. This could be based on geographic location, a large data range, department, or customer type.

Database Management is a crucial aspect of Azure Cosmos DB, and understanding its features can help you manage your database effectively. You can create and update properties for your database account using the DatabaseAccountCreateUpdatePropertiesOrDatabaseAccountGetProperties API.

To enable automatic failover, you need to set the enableAutomaticFailover property to true. This will ensure that your write region is automatically switched in the event of an outage. You can also enable or disable features like Burst Capacity Preview, Partition Merge, and Per-Region Per-partition Autoscale by setting the corresponding properties.

You can also configure your database account to write in multiple locations by setting the enableMultipleWriteLocations property to true. This can help improve data availability and redundancy. Additionally, you can enable or disable features like Virtual Network ACL rules and Network Acl Bypass by setting the corresponding properties.

Here are the different capacity modes available for your Cosmos DB account:

By understanding these features and properties, you can effectively manage your Azure Cosmos DB database and ensure high availability and performance.

Database Account Management is a crucial aspect of maintaining a healthy and efficient database. You can manage a Cosmos DB account through various properties and settings.

The analytical storage configuration is a key aspect of managing a database account. It allows you to configure analytical storage specific properties.

To manage the analytical storage configuration, you need to specify the analytical storage configuration object. This object contains properties such as the analytical storage mode and the analytical storage account name.

The capacity mode of a Cosmos DB account determines how the account is billed. There are three capacity modes: None, Provisioned, and Serverless.

Here's a breakdown of the capacity modes:

The enable automatic failover feature allows the write region to fail over to a different region in case of an outage. This feature is enabled by default, but you can disable it if needed.

The enable priority based execution feature allows you to prioritize requests based on their priority level. You can set the default priority level to High or Low.

The virtual network rules allow you to configure the virtual network ACL rules for the Cosmos DB account. You can specify the resource IDs for network ACL bypass for the account.

The public network access setting determines whether requests from public networks are allowed. You can set it to Disabled, Enabled, or Secured by Perimeter.

Transactions are a crucial aspect of database management, ensuring data consistency and integrity.

In DocumentDB, transactions can be run using Javascript stored procedures, which allow for ACID transactions on a collection.

This means that if a Javascript function completes, all write operations are committed, but if it throws an exception, all operations are rolled back.

In contrast, MongoDB doesn't have a concept of transactions beyond single-document atomicity, meaning that inserting or updating a document is atomic, but a write operation involving multiple documents is not atomic as a whole.

DocumentDB in Azure provides built-in security and access control by default, ensuring no password-less admin access.

With DocumentDB, you can control access to collections and documents in a fine-grained fashion by creating users and linking them to resources through password-protected permissions.

Microsoft invests heavily in security, making it a top priority for Azure Cosmos DB.

Encryption at rest is enabled by default, encrypting all physical files used to implement Cosmos DB on hard drives, as well as all backups of Azure Cosmos DB databases.

Recommended read: Azure Security

DocumentDB provides built-in security and access control that's there by default, so you don't have to worry about setting it up.

No password-less admin access is allowed, which means you'll always need a password to access sensitive areas.

This fine-grained access control lets you control who can access collections and documents in a very specific way, by creating users and linking them to those resources through password-protected permissions.

Microsoft invests heavily in security, so you can trust that your data is safe in Azure Cosmos DB.

Azure Cosmos DB has robust security features that are designed to protect your data from unauthorized access.

Worth a look: Azure Data Studio vs Azure Data Explorer

Encryption at rest is a crucial aspect of data security. Encryption at rest means that all physical files used to implement Cosmos DB are encrypted on the hard drives they are using.

This provides an additional layer of protection, as anyone with direct access to those files would have to unencrypt them in order to read the data.

All backups of Azure Cosmos DB databases are also encrypted, so you don't have to worry about configuration.

Azure Cosmos DB offers a range of features and functionality that make it a powerful tool for developers. The service now supports Gremlin and Table Storage APIs, providing a more robust set of capabilities for working with data.

One of the key benefits of Azure Cosmos DB is its ability to scale globally and elastically, allowing for consistent performance and low latency across different regions. This is made possible by the service's extended foundation for global and elastic scalability of throughput and storage.

Azure Cosmos DB also offers a range of consistency models, including the consistent prefix consistency model, which provides a high level of data consistency and reliability. This is just one of the many developer-facing manifestations of the service's continued work on global distribution and scalability.

Take a look at this: Azure Kubernetes Service vs Azure Container Apps

Azure Cosmos DB offers a range of extra capabilities beyond its SQL dialect, including support for Gremlin and Table Storage APIs.

One of the key benefits of these new APIs is that they provide access to more advanced features and data models, which can help improve performance and storage at a global scale.

You can now get access to other capabilities that were previously not accessible, such as global and elastic scalability of throughput and storage.

The RU/m is one of the first manifestations of this work, which helps reduce costs for customers with various workloads.

The consistent prefix consistency model is another developer-facing manifestation of this work, making it a total of five well-defined consistency models.

Implementing stored procedures in Azure Cosmos DB collections is a powerful feature that allows you to write JavaScript code to perform complex operations. You can create stored procedures, triggers, and user-defined functions to automate tasks and improve data consistency.

Stored procedures in Azure Cosmos DB can be used for batch operations, which are executed on the server, avoiding network latency and ensuring atomicity across multiple documents in a collection's partition. This means that either all operations in a stored procedure succeed or all fail, maintaining data integrity.

Azure Cosmos DB's stored procedures are written in JavaScript, which is a key feature of DocumentDB, allowing you to create data processing functions. You can use these stored procedures to insert, query, update, and perform other operations on documents in your collection.

Here are the three different forms that stored procedures can take:

By using stored procedures, you can simplify your code, improve performance, and reduce the complexity of your data operations. With Azure Cosmos DB, you can focus on writing efficient and effective code, rather than worrying about the underlying infrastructure.

Full-text indexes are a powerful feature in MongoDB, offering full-text search capabilities through text indexes.

MongoDB provides text indexes, which are specifically designed for full-text search capabilities.

DocumentDB, on the other hand, does not offer full-text indexing.

The recommended way to add full-text search to a DocumentDB database is to pair it with an Azure Search service.

Querying data from Azure Cosmos DB is a breeze, thanks to LINQ. This powerful tool allows you to retrieve data directly from the object model without needing to write any data layer code.

You can create queries in the Azure portal using SQL, which is a great option if you prefer a graphical interface. To do this, follow these steps:

Alternatively, you can create queries in C#. This is a great option if you're already familiar with the language and want to write more complex queries. For example, searching for all people Wolfgang knows is a simple query that can be written in C#.

Azure Cosmos DB offers a range of APIs to choose from, including Table, DocumentDB, and GraphDB. You can easily migrate an existing application that uses Azure Storage tables to Azure Cosmos DB Table API.

Azure Cosmos DB DocumentDB is an excellent choice for mobile, web, and IoT applications, allowing for rapid software development and compatibility with MongoDB. This means you can cut down on code and take advantage of automatic indexing of all fields.

Azure Cosmos DB also supports Gremlin, a popular graph API, which enables developers to write applications that explore relationships between entities. This is particularly useful for social media applications and defining relationships between entities.

REST Interface Access is a powerful way to interact with Azure Cosmos DB. You can create, query, and delete databases, collections, and documents using a REST API.

The REST API provides a programmatic interface to Azure Cosmos DB, allowing you to send HTTPS requests using GET, POST, PUT, and DELETE to a specific endpoint.

SDKs like the Azure Document DB SDK in C# simplify these calls and make them easier to implement, but you can also call the REST URIs directly without the SDK.

SDKs are available for various languages, including Python, JavaScript, Node.js, and Xamarin, which all call the REST API underneath.

This means you can use a language that might not have an SDK, like Elixir, to access Azure Cosmos DB through the REST API.

When choosing an API surface for Azure Cosmos DB, you have several options to consider.

You can choose between Table, DocumentDB, and GraphDB APIs.

The Table API provides the same functionality as Azure Storage tables, making it an easy migration path for existing applications.

DocumentDB is an excellent choice for mobile, web, and IoT applications due to its ease of implementation and JSON document storage.

It's also compatible with MongoDB, allowing for a seamless migration of existing MongoDB applications.

GraphDB, on the other hand, supports Gremlin, a popular graph API, ideal for applications that require graph traversal and relationship definition.

Graph databases excel at defining relationships and exploring network connections, making them a popular choice for social media applications.

Azure Cosmos DB also allows storing procedures, triggers, and functions in JavaScript, unlike SQL server which uses T-SQL.

In an ARM template, you can create a Microsoft.DocumentDB/databaseAccounts resource by adding a JSON object that defines the resource. The apiVersion property is required and must be set to '2025-05-01-preview'.

The identity property is used to define the identity for the resource, and it can be set to ManagedServiceIdentity. The kind property indicates the type of database account, and it can only be set at database account creation. It can be set to either 'GlobalDocumentDB', 'MongoDB', or 'Parse'.

The location property specifies the location of the resource group to which the resource belongs, and it must be a string. The name property is required and must be a string with a minimum length of 3 and a maximum length of 50. It must match the pattern ^[a-z0-9]+(-[a-z0-9]+)*.

The properties property is required and must be of type DatabaseAccountCreateUpdatePropertiesOrDatabaseAccountGetProperties. The tags property is used to define resource tags, and it can be a dictionary of tag names and values. The type property is required and must be set to 'Microsoft.DocumentDB/databaseAccounts'.

Here is a summary of the properties you need to define in an ARM template to create a Microsoft.DocumentDB/databaseAccounts resource:

Azure Cosmos DB offers a seamless transition for existing DocumentDB customers, with their data automatically migrated to the new service.

The DocumentDB Data Migration tool is an open source solution that imports data from various sources, including JSON files, CSV files, SQL Server, MongoDB, and existing DocumentDB collections.

This tool supports transforming tabular source data into hierarchical relationships during import, and offers options for handling date fields.

The reasons for migrating to Azure Cosmos DB are compelling. Azure Cosmos DB started as "Project Florence" in 2010 to address developer pain-points for large Internet-scale applications inside Microsoft.

One of the main reasons is that Azure Cosmos DB is the next big leap in globally distributed, at scale, cloud databases. This means you can build planet-scale apps with ease.

The exponential growth of the service has validated its design choices and unique tradeoffs. This gives you a high degree of confidence in the technology.

Azure Cosmos DB exposes multiple well-defined consistency models, giving you clear tradeoffs with respect to latency/availability, backed by SLAs. This is a game-changer for developers.

No data is born relational, so Cosmos DB allows you to store and query your data in its original form. This is a huge advantage over traditional relational databases.

Cosmos DB meets developers where they are, offering a multitude of APIs to access and query data. This includes SQL and various popular OSS APIs.

The DocumentDB Data Migration tool is a game-changer for those looking to ease the process of getting existing data into a new DocumentDB account.

This open source solution imports data from a variety of sources, including JSON files, CSV files, SQL Server, MongoDB, and existing DocumentDB collections.

Getting existing data into a new DocumentDB account can be a daunting task, but this tool simplifies the process.

The migration tool supports transforming tabular source data, such as SQL Server or CSV files, to create hierarchical relationships during import.

This means you can create subdocuments and handle date fields with ease.

The tool's source code is available on GitHub, and a compiled version can be downloaded from the Microsoft Download Center.

You can either compile the solution or download and extract the packaged version to a directory of your choice.

For full details on how to use the tool, including command line samples for each data source option, access the full documentation here.

To create a Microsoft.DocumentDB/databaseAccounts resource, you'll need to add Terraform to your template. This involves specifying the identity for the resource, which can be a ManagedServiceIdentity.

The kind parameter indicates the type of database account, and this can only be set at database account creation. You have three options: GlobalDocumentDB, MongoDB, or Parse.

The location parameter specifies the location of the resource group to which the resource belongs. This must be a string.

The name parameter is required and specifies the resource name. It must be a string with a minimum length of 3 and a maximum length of 50. The pattern is ^[a-z0-9]+(-[a-z0-9]+)*.

You'll also need to specify the parent_id parameter, which is the ID of the resource to apply this extension resource to. This is a required string.

Properties to create and update Azure Cosmos DB database accounts are specified using the properties parameter. This must be a DatabaseAccountCreateUpdatePropertiesOrDatabaseAccountGetProperties object.

Tags for the resource are specified using the tags parameter, which is a dictionary of tag names and values.

The type parameter specifies the resource type, which is "Microsoft.DocumentDB/databaseAccounts@2025-05-01-preview".

In the Azure portal, you can create a new Azure Cosmos DB account by clicking on "Create a new Service" and searching for Azure Cosmos DB.

To create an Azure Cosmos DB with a SQL API, you'll need to provide a unique ID, subscription, resource group, and location.

Select an API, such as SQL, and click Create.

Once Azure Cosmos DB is deployed, you can open Visual Studio 2015 or 2017 and create a new C# console application.

To connect to your Azure Cosmos DB, you'll need to install the Microsoft.Azure.DocumentDB NuGet Package.

You can then create a DocumentClient variable with your Azure Cosmos DB account URI and primary key.

Your primary key can be found by going to your Azure Cosmos DB and selecting Keys under the Settings menu.

To create a database, you can use the following code:

Create the database if it does not exist yet

If the database doesn’t exist yet, create it with the following code.

Take a look at this: Azure Data Studio Connect to Azure Sql

You can create a collection by using the following code:

Create the collection, if it does not exist yet.

To retrieve a list of customers, you can use a LINQ expression.

Get a list of customers which fit the LINQ expression

Here's a step-by-step guide to creating a database with a collection: