Tuesday, 7 October 2014

Creating and Querying Microsoft Azure DocumentDB

DocumentDB is the latest storage option added to Microsoft Azure.
It is a no-sql storage service that stores JSON documents natively and provides indexing capabilities along with other interesting features.

This article is available available on the Microsoft Technet Wiki.
This article was highlighted in the Top Contributor awards on the 12th of October 2014.
This article was highlighted in the TNWiki Article Spotlight.
This article was highlighted in the The Microsoft TechNet Guru Awards! (October 2014).



DocumentDB  is the latest storage option added to Microsoft Azure.
It is a no-sql storage service that stores JSON documents natively and provides indexing capabilities along with other interesting features.
This wiki shall introduce you to this new service.

Setting up a Microsoft Azure DocumentDB

Go to the new Microsoft Azure Portal. https://portal.azure.com/  

 

 Click on New > DocumentDB


Enter A Database ID and hit Create!



Please wait while the database is being created. 



After the database is created, Keys button to get the Database URI and its required keys. 


We may now start building our App. 

Using Microsoft Azure DocumentDB in your Application

Create project

Create a new project and add the nuget package Microsoft Azure DocumentDB Client Library. 

Go to Tools > Package Manager > Package Manager Console.

Key in Install-Package Microsoft.Azure.Documents.Client -Pre and hit enter. 



Define the Model

In this example, we shall define a class Team, each having an array of players. 

public class Team
{
    [JsonProperty(PropertyName = "id")]
    public string Id { getset; }
    public string TeamName { getset; }
    public Player[] Players { getset; }
}
 
public class Player
{
    public string PlayerName { getset; }
    public int PlayerAge { getset; }
}

Add the endpoint url and the authorization key.


These values are same values identified above.

private static string endpointUrl = "";
private static string authorizationKey = "";

Create a new instance of the DocumentClient

The DocumentClient class provides a client-side logical representation of the Azure DocumentDB service.
It is used to configure and execute requests against the service.
client = new DocumentClient(new Uri(endpointUrl), authorizationKey);

Create Database


This will return an instance of a database, first creating it if it doesn't already exist.

public async Task<Database> CreateOrGet(string DatabaseID)
{
    
    var Databases = client.CreateDatabaseQuery().Where(db => db.Id == DatabaseID).ToArray();
 
    if (Databases.Any())
        return Databases.First();
 
    return await client.CreateDatabaseAsync(new Database { Id = DatabaseID });
}

Create a document collection


This method returns a document collection, creating it if it doesn't already exist. 
A document collection is a named logical container for documents. 
The method CreateDocumentCollectionQuery creates and returns a query for document collections.

public async Task<DocumentCollection> CreateOrGetCollection(string CollectionID)
{
    var collections = client.CreateDocumentCollectionQuery(database.CollectionsLink)
                        .Where(col => col.Id == CollectionID).ToArray();
    if (collections.Any())
        return collections.First();
 
    return await client.CreateDocumentCollectionAsync(database.CollectionsLink,
        new DocumentCollection
        {
            Id = CollectionID
        });
}


Create Documents

Create normal c# objects that represent documents.

//Create Team Documents
Team team1 = new Team
{
     Id="t001",
      TeamName="Football team 1",
      Players= new Player[]{
        new Player{ PlayerName="Chervine", PlayerAge=21},
        new Player { PlayerName="Kevin", PlayerAge=21}
      }
};
 
Team team2 = new Team
{
    Id = "t002",
    TeamName = "Football team 2",
    Players = new Player[]{
        new Player{ PlayerName="Cherv", PlayerAge=21},
        new Player { PlayerName="Kev", PlayerAge=21}
      }
};

Save the documents

To save documents, the method CreateDocumentAsync is used which creates a document as an asynchronous operation.

await client.CreateDocumentAsync(documentCollection.DocumentsLink, team1);
await client.CreateDocumentAsync(documentCollection.DocumentsLink, team2);

The document is now saved. 
You may now browse it from the Azure portal. From the dashboard, select your DocumentDB, scroll down to Document Explorer, and select the collections you wish to view. 


Read data from the Application

You can use both SQL and LINQ to retrieve data in DocummentDB.

Using SQL

Retrieving one team
team2 = client.CreateDocumentQuery<Team>(documentCollection.DocumentsLink, "SELECT * FROM Teams t WHERE t.TeamName = \"Football team 2\"").AsEnumerable().FirstOrDefault();

Retrieving all teams: 
foreach (var team in client.CreateDocumentQuery(documentCollection.DocumentsLink,
"SELECT * FROM Teams"))
{
    Console.WriteLine("\tRead {0} from SQL", team);
}


Using LINQ

Retrieving one team: 
team1 = client.CreateDocumentQuery<Team>(documentCollection.DocumentsLink).Where(d => d.TeamName == "Football team 1").AsEnumerable().FirstOrDefault();

Retrieving all teams:
foreach (var team in (
from t in client.CreateDocumentQuery(documentCollection.DocumentsLink)
select t))
{
    Console.WriteLine("\tRead {0} from LINQ", team);
}

Updating a document

You first need to get the document to update, make the changes and replace the document. 

dynamic Team2Doc = client.CreateDocumentQuery<Document>(documentCollection.DocumentsLink).Where(d => d.Id =="t002").AsEnumerable().FirstOrDefault();
Team2Doc.TeamName = "UPDATED_TEAM_2";
await client.ReplaceDocumentAsync(Team2Doc);

Delete a document

Document Team3Doc = client.CreateDocumentQuery<Document>(documentCollection.DocumentsLink).Where(d => d.Id =="t003").AsEnumerable().FirstOrDefault();
await client.DeleteDocumentAsync(Team3Doc.SelfLink)

 Conclusion

Microsoft Azure DocumentDB is really easy to use and allows for rapid application development.
Being able to store heterogeneous JSON documents within DocumentDB and query it using SQL like syntax and LINQ is really great which means that the developer do not have to learn anything new.
This service is still in preview mode and will get even more interesting with time.
Also, since it is still in preview mode, the materials presented in this wiki may change in the future. 

No comments:

Post a Comment