Cosmos DB Solves Common Data Challenges in App Development

Jasmine Greenaway [MSFT]

When considering how to implement your application with a relational database, it can change how you build it dramatically. Some of these challenges include adding an abstract implementation of the schema in the code, mapping data to objects, building queries, and preventing SQL injection attacks. Wouldn’t it be great if there was a way to reduce the number of problems that can arise with data when building your app? Cosmos DB could be the answer for you. Azure Cosmos DB is a fully managed, globally distributed database service that alleviates the common application development stressors of working with data. Cosmos DB also comes with guaranteed high availability, low latency, and scalable throughput and storage. Getting started is fast and easy, thanks to Cosmos DB’s schema agnostic database engine and extensive number of comprehensive APIs. In this blog post, we’ll walk through how Cosmos DB solves these problems in addition to some of its other benefits. With a sample .NET web application, we’ll walk through how to use the Cosmos DB SQL .NET API, which allows you to use familiar SQL syntax to query data.

Core Cosmos DB Concepts A Cosmos DB

database **is the central location of the data and users who have varying administrative rights to the data. Databases store **collections, which are a repository of documents, containing the raw data in JSON format. Each document relates to one unit of data, where its **properties **and respective values define it. These terms can be translated directly to a traditional database, like SQL Server for example, illustrated in the comparison table below.

SQL Server Cosmos DB
Database Database
Table Collection
Record Document
Column Property
Sample Overview

Imagine a common scenario where you expect a user to interact with your application and its underlying data. Usually, the user will want to view the data in a readable format, and a way to alter, add, or delete the data. The sample is an ASP.NET web application that allows a user to maintain a list of their favorite Microsoft documentation links and Channel 9 videos. The application’s data is stored and maintained in Cosmos DB, which contains the user populated data and web page metadata that the application finds from the provided documentation or video url.

Visit the Url Notes repository to view the complete sample

Domain model flexibility

The Cosmos DB SQL .NET API makes working with your model seamless by managing the object mapping for you. You can work directly with your domain objects; perfect for applications that require create, read, update, and delete (CRUD) operations. This will look familiar if you’ve worked with the object relational mapping provided by Entity Framework. In the sample, GetAllDocs demonstrates getting all documents that belong to a collection. Notice that this method has a generic type parameter, this is used to pass the model type that the data set will bind to. The sample uses generic methods as a straightforward way to pass types to CreateDocumentQuery, which requires a type parameter.

Here’s a example of the returned data in the debugger and the data in the portal.

Screenshot of an object while debugging the url notes app in visual studio
A Video object as seen while debugging in Visual Studio
Screenshot of a document in cosmos db
The same Video object as a document in Cosmos DB via the Cosmos DB Data Explorer in the Azure Portal

Queries with SQL-like syntax or LINQ** **

The API gives developers options how to query data using the familiar syntax of either SQL or LINQ to build queries. The API helps reduce query complexity as building queries on properties are much easier. Furthermore, you can still protect against SQL injection with parameters. The sample’s GetDocument method uses LINQ to search for a document by ID, a property of the Document type, as all documents have a unique ID.

Here’s a conceptual example of a query with a Video object:

In the sample, a user can choose up to two properties to go along with their search text, in searchTerms and searchText, respectively. The Search method uses these parameters to look for matches in the specified properties. The query is built based on those properties and are set as SQL parameters.

Reduce the complexities of inserts, updates, and deletes

The API provides operations for making changes to your data whether it be adding more records, altering them, or removing them. For most of these operations, the API only requires the collection, and the domain model object.

CreateDocumentAsync requires two parameters: the url to the collection, and the object to be inserted into the collection. For example, inserting a new document into the Video collection requires passing the name of the Video collection, and the Video object parameter. When adding a new document to a collection, the API takes care of serializing the object to JSON.

The API’s ReplaceDocumentAsync method reduces the complexities of updating by providing multiple ways to directly access and change properties. In the sample, the user-editable properties are accessed by their document’s property name.

Before updating a document in EditDocument, the sample confirms it exists, then returns it as a Document object in the doc variable. Finally, the document’s properties are updates the via object’s SetPropertyValue method before calling ReplaceDocumentAsync.

Alternatively, you can use your defined domain objects to update the document. Below is an example on how that could be done with the Video object:

Use your favorite database management features** **

Cosmos DB comes with the ability to create and manage stored procedures, user defined functions, and triggers. This functionality will be familiar to those using SQL Server or another database that has these features. Use either the API, Azure portal, command line (CLI), or the Cosmos DB Data Explorer  to manage these features. While this sample does not use any of these features, here’s an example stored procedure:

A Cosmos DB stored procedure in the Azure Portal
A Cosmos DB stored procedure in the Azure Portal

High Availability and Scaling** **

In addition to what the API offers, Cosmos DB also comes with the guarantee of optimal performance with features like low latency, automatic indexing, region-based availability, and scalable throughput. Cosmos DB enables region-based availability with their replication protocol that ensures database operations are performed in the region that is local to the client. One benefit of this is low latency at the 99th percentile, along with the promise of data consistency across all regions. By default, the level of consistency in Cosmos DB provides automatic indexing after each insert, delete, and replace/update of documents. Performance dependent variables like CPU, and memory are all calculated in a measurement specific to Cosmos DB called Request Units (RUs). With RUs, throughput is managed based on the computational complexity of operations done on a database. For common scenarios, databases with predictable performance will need 100 RUs/second, with the option to provide more as needed. You can use the request unit calculator to estimate RUs needed. Worried about throughput limits? With the Cosmos DB .NET APIs you get the added bonus of automatic retries for single clients that are operating above the provisioned rate. Additionally, you can catch the DocumentClientException rate limit exceptions and customize the retry process yourself.


Building data driven applications can come with several problems to solve, and Cosmos DB can lighten the load of addressing them. With an extensive and comprehensive API to work with domain objects directly for database operations, and a globally available and scalable database, Cosmos DB simplifies these complexities and allows developers to focus on what matters to them the most.

Interested in learning more about Cosmos DB? In depth information on the topics covered in this post can be found in the links below. New to Azure? 


Comments are closed. Login to edit/delete your existing comments

Feedback usabilla icon