In this blog post, I will provide an introduction to DocumentDB by showing
you how to create a collection (a collection is a container that stores your
data), and how to connect to your collection to add and fetch data. DocumentDB
is a newer no-sql data storage engine that is hosted in the Microsoft Azure
cloud exclusively. Because DocumentDB stores records as JSON objects, it is a
natural database engine for developers. Unlike other offerings however, it also
offers key features such as automatic indexing, server-side triggers, functions
and stored procedures (through Javascript).
Creating a DocumentDB Database
First, let’s create a new DocumentDB database so we can start exploring this
service; three things need to be created: an account, a database, and a
collection (where data is actually stored). An account can host multiple
databases, and each database can host multiple collections. From you Azure
portal (https://portal.azure.com) find
DocumentDB from the list of available services, and create a new DocumentDB
account. The Resource Group is a logical container allowing to group, view, and
manage related services. The screenshot below shows the information I have
provided.
Once the account has been created, the screen changes to show you a menu of
options from which you can create databases; of importance, DocumentDB allows
you to change the default consistency of your no-sql databases (no-sql database
consistency is an important concept as it can impact performance, availability
and consistency – see Consistency levels in DocumentDB); we will keep the default
setting. Also note an important configuration property: your keys. Locate the
Keys configuration menu to reveal your access keys. Note that DocumentDB allows
you to manage read-only keys as well.
Select Overview from the top of this menu, and click on Add Database and
enter a database identifier (which is the database name; my database is called
‘testdb’), and click OK.
Once the database has been created, you will need to create a collection.
Select the database to open up a new panel, and click on Add Collection. Enter
the necessary information and click OK (see the information I provided below; my
collection name is logdata; I also changed the Throughput to 400 to reduce the
cost since this is a test collection). At this point, we are ready to access
this collection and start adding records (in proper no-sql speak, we will be
adding documents).
Before jumping into the code, let’s make note of the following information
since this will be needed later to connect to DocumentDB.
| Configuration |
Value |
Comment |
| Database ID |
testdb |
The database “Id” is the name of the database we
created |
| Collection Id |
logdata |
The collection “Id” is the name of the collection we
created |
| Endpoint |
https://YOUR-ACCOUNT-NAME.documents.azure.com:443/
|
This is the URI of your DocumentDB service; use your
account name |
| Auth Key |
{Look under Keys in your DocumentDB database} |
This is the Primary Key or Secondary Key of your
DocumentDB account |
Create a VS2015 Project
Let’s create a simple project using Visual Studio 2015 to access the
DocumentDB collection. Note that the complete project and source code can be
found here: http://www.bluesyntaxconsulting.com/files/DocumentDBLogData.zip
We will create a Console Application to perform a few simple operations. Once
you have created the project, you will need to add the DocumentDB SDK. To
install the SDK, find the Microsoft Azure DocumentDB package, or use the
following command in the Package Manager Console (if you download the sample
code, the package will automatically be downloaded when you first compile):
Install-Package Microsoft.Azure.DocumentDB
Let’s create a class that holds a single log entry in our DocumentDB
collection. The class name is LogEntry. We need to have a unique identifier for
every document, and it must be called Id.
public class LogEntry
{
public string Id { get; set;
} // Guid of log
public DateTime DateAdded { get; set; }
public string Message { get; set; }
public string Category { get;
set; } // Info, Warning, Error
public int Severity { get; set; }
// Low, Medium, High
public string Source { get; set; } //
Application name
}
Then, we will create a simple Console application that does two things: it
can add a new document in our collection, and it can list all the documents from
the collection. The following is the complete code for the console application;
note the private variables on top that represent the configuration settings
identified previously.
using Microsoft.Azure.Documents;
using Microsoft.Azure.Documents.Client;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
namespace DocumentDBLogData
{
class Program
{
static string endpoint = "https://YOUR-ACCOUNT-NAME.documents.azure.com:443/";
static string authKey = "YOUR-PRIMARY-OR-SECONDARY-KEY";
static string databaseId = "testdb";
static string collectionId =
"logdata";
static void Main(string[] args)
{
Console.WriteLine("STARTING DocumentDB Demo... ");
while(true)
{
Console.Clear();
Console.WriteLine("1: Create new message");
Console.WriteLine("2: List all messages");
Console.WriteLine("");
switch(Console.ReadKey().KeyChar)
{
case '1':
Console.WriteLine("");
Console.WriteLine("Adding a record to DocumentDB...");
AddLogInfoEntry();
Console.WriteLine("New record added in DocumentDB.
Press ENTER to continue.");
Console.ReadLine();
break;
case '2':
Console.WriteLine("");
Console.WriteLine("Fetching DocumentDB records...");
DisplayLogInfoEntry();
Console.WriteLine("");
Console.WriteLine("Press ENTER to continue.");
Console.ReadLine();
break;
}
}
}
static void AddLogInfoEntry()
{
using
(DocumentClient client = new DocumentClient(new Uri(endpoint), authKey))
{
var collection =
UriFactory.CreateDocumentCollectionUri(databaseId, collectionId);
LogEntry le = new LogEntry()
{
Id = Guid.NewGuid().ToString(),
Category = "Info",
DateAdded = DateTime.UtcNow,
Message = "General message from Console App",
Severity = 1,
Source = "CONSOLE
APP"
};
Document newDoc = client.CreateDocumentAsync(collection,
le).GetAwaiter().GetResult();
}
}
static void DisplayLogInfoEntry()
{
using
(DocumentClient client = new DocumentClient(new Uri(endpoint), authKey))
{
var collection =
UriFactory.CreateDocumentCollectionUri(databaseId, collectionId);
var docs =
client.CreateDocumentQuery<LogEntry>(collection).AsEnumerable();
foreach(var doc in docs)
{
string output = "{0}\t{1}\t{2}\t{3}\t{4}";
output = string.Format(output, doc.Id, doc.DateAdded,
doc.Source, doc.Severity, doc.Message);
Console.WriteLine(output);
}
Console.WriteLine();
}
}
}
}
By pressing 1, the console application connects to DocumentDB and adds a
record to the LogData collection. By pressing 2, the console application
fetches all available documents and displays them on the screen. Note that if
you have a large number of records, you will need to add logic to page the
operation (let’s say 100 documents at a time for example), and handle retry
logic operations if the service is too busy.
Conclusion
This simple introduction to DocumentDB provides a quick overview of the
simplicity of this service, along with a sample project for creating and
accessing documents. Although DocumentDB is very easy to configure and use in
code, many advanced features (not covered in this introduction) are available
around performance, security and availability. For a deeper understanding of
DocumentDB, please refer to the online MSDN documentation, and the QuickStart
provided in the DocumentDB menu inside the Azure Portal.
About Herve Roggero
Herve Roggero, Microsoft Azure MVP, @hroggero, is the founder of Enzo Unified
(http://www.enzounified.com/). Herve's
experience includes software development, architecture, database administration
and senior management with both global corporations and startup companies. Herve
holds multiple certifications, including an MCDBA, MCSE, MCSD. He also holds a
Master's degree in Business Administration from Indiana University. Herve is the
co-author of "PRO SQL Azure" and “PRO SQL Server 2012 Practices” from Apress, a
PluralSight
author, and runs the Azure Florida
Association.v