Azure Cosmos DB - Part Three - Getting Started With Azure Document DB

Understanding the Azure Document DB

Azure Document DB is a Document based No SQL subset of CosmosDb, so if you’re not familiar with it, I request you to go through my following articles,

• Azure Cosmos DB - Part One - Introduction To The World Of NOSQL
• Azure Cosmos DB - Part Two - Understanding The Azure Cosmos DB Concept
  

Azure DB is a subset of Azure DocumentDB, and a schema-free database that combines rich and familiar SQL query capabilities with consistent low latencies on JSON-based data models, targeting solutions for web, mobile, gaming, and IoT. Since DocumentDB is schema agnostic, this makes it extremely easy to adjust and adapt data models on the fly as business logic and application scenarios change.

With DocumentDB, you no longer have to deploy constant updates to the data-tier and worry about managing schema and relationships. All content in DocumentDB is automatically indexed, which makes it possible to query data across entire structures at any time. The term “NoSQL” is more of a marketing buzzword, and actually means “no requirement for entity relationships and secondary indexing” in order to query information.

Since DocumentDB is a JSON-based storage mechanism, accessing and interacting with data can be accomplished through most standards-based interfaces, as well as robust toolsets and SDKs. Although native Universal Windows Platform support is not currently available, support for virtually any other development scenario is available. Deeper level features of are currently exposed via JavaScript, such as stored procedures, triggers and user defined functions (UDFs) making it easy for developers to write application logic that can be packaged and executed directly on database storage partitions.

Terminologies related to DocumentDb

Database

A database is a logical container of document storage partitioned across collections. It is also a user's container.

User

The logical namespace for scoping permissions.

Permission

An authorization token associated with a user for access to a specific resource.

Collection

A collection is a container of JSON documents and the associated JavaScript application logic.

Stored Procedure

Application logic written in JavaScript which is registered with a collection and transactionally executed within the database engine.

Trigger

Application logic written in JavaScript executed before or after either an insert, replace or delete operation.

UDF

Application logic written in JavaScript. UDFs enable you to model a custom query operator and thereby extend the core DocumentDB query language.

Document

Arbitrary user-defined JSON content. By default, no schema needs to be defined nor do secondary indices need to be provided for all the documents added to a collection.

Hands On Demo

We are trying to create a MVC application and showcase the simple CRUD operations with Cosmos DB.

• Go to Azure Portal and search for cosmos db.
  
  
  
  
• You will get four options: Gremlin, MongoDb, SQL (DocumentDB) and Table (keyValue Pair). As we are working with DocumentDb so we are going to select the documentdb option and supply the necessary information like the resource group and where do you want to host your db.
  
  
  

• Once the account is created, go to the quick start option in the properties menu and then click on Create Items Collection Button. This will create a Collection in the database and then download the sample application.
  
  Please note that you can either use the sample application or create your own application and add the documentDb client SDK via nugget. For this demo, we are going to continue with the sample application.
  
  
  

• Open your project in Visual Studio and go to web.config. You can see that the endpoint, the authKey, Database and Collections are prefilled with the information from your cosmosdb. If you’re developing your application from scratch then you need to pass on this information to your web.config.
  
  
  
  
• The Item Collection that we have created has a corresponding controller in our MVC application sample and it contains most of the common CRUD scenarios covered and its calling the documentdb repository in its actions Items.
  

  public class ItemController : Controller
      {
          [ActionName("Index")]
          public async Task<ActionResult> IndexAsync()
          {
              var items = await DocumentDBRepository<Item>.GetItemsAsync(d => !d.Completed);
              return View(items);
          }
  
  #pragma warning disable 1998
          [ActionName("Create")]
          public async Task<ActionResult> CreateAsync()
          {
              return View();
          }
  #pragma warning restore 1998
  
          [HttpPost]
          [ActionName("Create")]
          [ValidateAntiForgeryToken]
          public async Task<ActionResult> CreateAsync([Bind(Include = "Id,Name,Description,Completed")] Item item)
          {
              if (ModelState.IsValid)
              {
                  await DocumentDBRepository<Item>.CreateItemAsync(item);
                  return RedirectToAction("Index");
              }
  
              return View(item);
          }
  
          [HttpPost]
          [ActionName("Edit")]
          [ValidateAntiForgeryToken]
          public async Task<ActionResult> EditAsync([Bind(Include = "Id,Name,Description,Completed")] Item item)
          {
              if (ModelState.IsValid)
              {
                  await DocumentDBRepository<Item>.UpdateItemAsync(item.Id, item);
                  return RedirectToAction("Index");
              }
  
              return View(item);
          }
  
          [ActionName("Edit")]
          public async Task<ActionResult> EditAsync(string id)
          {
              if (id == null)
              {
                  return new HttpStatusCodeResult(HttpStatusCode.BadRequest);
              }
  
              Item item = await DocumentDBRepository<Item>.GetItemAsync(id);
              if (item == null)
              {
                  return HttpNotFound();
              }
  
              return View(item);
          }
  
          [ActionName("Delete")]
          public async Task<ActionResult> DeleteAsync(string id)
          {
              if (id == null)
              {
                  return new HttpStatusCodeResult(HttpStatusCode.BadRequest);
              }
  
              Item item = await DocumentDBRepository<Item>.GetItemAsync(id);
              if (item == null)
              {
                  return HttpNotFound();
              }
  
              return View(item);
          }
  
          [HttpPost]
          [ActionName("Delete")]
          [ValidateAntiForgeryToken]
          public async Task<ActionResult> DeleteConfirmedAsync([Bind(Include = "Id")] string id)
          {
              await DocumentDBRepository<Item>.DeleteItemAsync(id);
              return RedirectToAction("Index");
          }
  
          [ActionName("Details")]
          public async Task<ActionResult> DetailsAsync(string id)
          {
              Item item = await DocumentDBRepository<Item>.GetItemAsync(id);
              return View(item);
          }
      }

• Going to the DocumentDbRepository which acts as an interface between our application and the documentdb. It has all the definitions of CRUD operations in the database and it also takes care of creating a new db/collection if they don’t exist, by doing a sanity check.
  

  private static readonly string DatabaseId = ConfigurationManager.AppSettings["database"];
          private static readonly string CollectionId = ConfigurationManager.AppSettings["collection"];
          private static DocumentClient client;
  
          public static async Task<T> GetItemAsync(string id)
          {
              try
              {
                  Document document = await client.ReadDocumentAsync(UriFactory.CreateDocumentUri(DatabaseId, CollectionId, id));
                  return (T)(dynamic)document;
              }
              catch (DocumentClientException e)
              {
                  if (e.StatusCode == System.Net.HttpStatusCode.NotFound)
                  {
                      return null;
                  }
                  else
                  {
                      throw;
                  }
              }
          }
  
          public static async Task<IEnumerable<T>> GetItemsAsync(Expression<Func<T, bool>> predicate)
          {
              IDocumentQuery<T> query = client.CreateDocumentQuery<T>(
                  UriFactory.CreateDocumentCollectionUri(DatabaseId, CollectionId),
                  new FeedOptions { MaxItemCount = -1 })
                  .Where(predicate)
                  .AsDocumentQuery();
  
              List<T> results = new List<T>();
              while (query.HasMoreResults)
              {
                  results.AddRange(await query.ExecuteNextAsync<T>());
              }
  
              return results;
          }
  
          public static async Task<Document> CreateItemAsync(T item)
          {
              return await client.CreateDocumentAsync(UriFactory.CreateDocumentCollectionUri(DatabaseId, CollectionId), item);
          }
  
          public static async Task<Document> UpdateItemAsync(string id, T item)
          {
              return await client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(DatabaseId, CollectionId, id), item);
          }
  
          public static async Task DeleteItemAsync(string id)
          {
              await client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(DatabaseId, CollectionId, id));
          }
  
          public static void Initialize()
          {
              client = new DocumentClient(new Uri(ConfigurationManager.AppSettings["endpoint"]), ConfigurationManager.AppSettings["authKey"]);
              CreateDatabaseIfNotExistsAsync().Wait();
              CreateCollectionIfNotExistsAsync().Wait();
          }
  
          private static async Task CreateDatabaseIfNotExistsAsync()
          {
              try
              {
                  await client.ReadDatabaseAsync(UriFactory.CreateDatabaseUri(DatabaseId));
              }
              catch (DocumentClientException e)
              {
                  if (e.StatusCode == System.Net.HttpStatusCode.NotFound)
                  {
                      await client.CreateDatabaseAsync(new Database { Id = DatabaseId });
                  }
                  else
                  {
                      throw;
                  }
              }
          }
  
          private static async Task CreateCollectionIfNotExistsAsync()
          {
              try
              {
                  await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri(DatabaseId, CollectionId));
              }
              catch (DocumentClientException e)
              {
                  if (e.StatusCode == System.Net.HttpStatusCode.NotFound)
                  {
                      await client.CreateDocumentCollectionAsync(
                          UriFactory.CreateDatabaseUri(DatabaseId),
                          new DocumentCollection { Id = CollectionId },
                          new RequestOptions { OfferThroughput = 1000 });
                  }
                  else
                  {
                      throw;
                  }
              }
          }
      }

• I want to make you understand the few line of code here which is not plain C# but has to do with the understanding of the documentDb.
  

  UriFactory.CreateDatabaseUri(DatabaseId),
  new DocumentCollection { Id = CollectionId },
  new RequestOptions { OfferThroughput = 1000 });

  The above lines are creating a database and creating a collection inside it but here, it's also setting the throughput of the Database, which means how many requests a database can handle concurrently. Here we are mentioning the throughput as 1000.
  
  P.S - The billing cost of the database is directly proportional to the throughput of the database so please make sure that you’re handling it properly and the minimum throughput is 400 that’s set by Microsoft for the documentDb Database.

• Click on the Create New Button which will give you a UI to enter the information such as Name, Description and IsCompleted. Click on the save button and your record will be added to the database.
  
  
  

• You will be redirected to the details view and you can see that the data that we saved is reflected on the UI.
  
  
  

• Let’s go to the Data Explorer on the Azure portal and if you’re an existing customer of Document Db you might realize that by moving it under the CosmosDb hood, they have improved the data explorer.
  
  
  

• You can see that the document now exists in our database and the transaction was successful. If you look closely at the stored procedures, UDF and Triggers are all present at collection level and we are going to talk about them in another post.

Summary

Azure DocumentDB is a fully managed NoSQL document-based “database as a service” built for ultra-fast and predictable performance, high availability, elastic scaling, and global distribution, and is especially focused on ease of development.

The heireachy of the Azure DocumentDB is as follows - Account-> Database -> Collection -> Document -> Attachments.

We have gone through the demo where we tried to do the basic CRUD operations in DocumentDB.