Getting Started with the Table API in Azure Cosmos DB
Tags: azure, dotnet, tutorial, database
Published: 2020-04-03 08:42:39

---
title: Getting Started with the Table API in Azure Cosmos DB
published: true
date: 2020-04-03 08:33:01 UTC
tags: azure,dotnet,tutorial,database
canonical_url: 
---

#### We can work with structured NoSQL data using the Table API in Azure Cosmos DB

![](https://cdn-images-1.medium.com/max/560/0*YSXGKyMqJOMGbnJk.png)

If you have an application that uses [Azure Table Storage](https://docs.microsoft.com/en-us/azure/cosmos-db/table-storage-overview) and you need to scale your application globally, you could benefit from using the [Table API in Azure Cosmos DB](https://docs.microsoft.com/en-us/azure/cosmos-db/table-introduction).

You can migrate your application with no changes required to your code and take advantage of capabilities such as global distribution, high availability etc that comes with Azure Cosmos DB.

In this article, I’m going to outline in what scenarios you should Cosmos DB’s Table API instead of normal Azure Table Storage, I’ll show you how you can create a Table API account in Azure and I’ll also walk you through a basic C# application that interacts with our Cosmos DB Table API account.

**OK, so when would I use Azure Cosmos DB instead of normal Table Storage?**

Normal Table Storage is quick, but has no upper bound defined on latency. Azure Cosmos DB has single-digit millisecond latency for reads and writes along with strong SLA’s (99.999% read availability, 99.99% write for single region, 99.999% for multi-region accounts).

You can make significantly more operations per second on Cosmos DB (over 10 million per second per table) than you could in normal Table Storage (limit to 20,000 per second).

If we need to failover our table storage, we can do this in Cosmos. We can assign any Azure Region that we want to failover to and we can do this automatically or manually. We can’t do this in normal Table Storage.

Indexing is far more extensive in Cosmos DB. We can index on every property in Cosmos DB and we can do this without managing it ourselves. This is fantastic for performing fast queries. In normal Table storage, we only have primary indexing on **PartitionKey** and **RowKey**. There is no secondary indexes in Table Storage.

We can also take advantage of multiple consistency levels in Cosmos DB. There are 5 well-defined consistency levels in Cosmos DB that we can take advantage of depending on the needs of our application.

Let’s create a Azure Cosmos DB account that uses the Table API. I’m going to assume that you have a basic familiarity with the Azure portal.

Click on ‘ **Create New** ’ to create a new resource and use the search text box to search for ‘ **Azure Cosmos DB’**. Click on the Azure Cosmos DB icon to start configuring your new account.

![](https://cdn-images-1.medium.com/max/587/1*UlnF_z-VeFCOGhq2GkGKMA.png)

Give your Azure Cosmos DB account a name and assign it to a resource group. The important thing here is that we select Azure Table as our API option. Cosmos DB comes with 5 different API’s (Table, Core, Gremlin, Cassandra or MongoDB). At the time of writing, we can only assign one API when we create our Cosmos DB account.

Since this is a tutorial about the Table API, we need to choose that as our API option.

If this is your first Cosmos DB account in your subscription and you just want to play around without paying any money, I’d highly recommend that you apply the Free Tier discount as I have. This is a new feature that’s fantastic for trying out Cosmos DB without spending any money. You can read more about the Free Tier [here.](https://docs.microsoft.com/en-us/azure/cosmos-db/optimize-dev-test#azure-cosmos-db-free-tier)

Provision the account in a region that’s close to you. You don’t need Multi-Region writes or do anything else for this tutorial. Check out the screenshot below to see how I set up my account. Click on ‘ **Review + Create** ’ to provision your Cosmos DB account.

![](https://cdn-images-1.medium.com/max/964/1*Fkr-QcPu4xvaon_5-AlpIQ.png)

After a few minutes, our Cosmos DB account will be provisioned. Let’s create a new Table within our account. To do this, head to your Cosmos DB accounts’ “ **Data Explorer”** and click on the “ **New Table”**  button.

![](https://cdn-images-1.medium.com/max/608/1*HTkQVpSgr_Gt6LGZViTrPw.png)

In the Add Table panel, give your table a name and set the throughput level that you want to provision. Unlike the Core (SQL) API, when you create a table in the Table API, you always provision throughput for that Table and a Database will automatically be created for that table. If you provision more tables within that account, they will sit underneath the same database.

![](https://cdn-images-1.medium.com/max/439/1*gAG035Xc4gupHaAiWv_KjQ.png)

Click “ **OK ”** and you should see your new table ready to go. Let’s build a simple application to put some data in there!

![](https://cdn-images-1.medium.com/max/1024/1*_mkk212sx7mhUYDTpgmqJA.png)

For this tutorial, I’m going to develop a simple .NET Core application that deals with Superheros from both the DC and Marvel Universe(DC comic, Marvel films 😊).

To work with the Table API in our C# application, I’ll need to use the Microsoft.Azure.Cosmos.Table NuGet package. This package allows us to develop applications that target .NET standard. We’ll also need to download some Configuration packages to hide our secrets.

Below are the packages we want to download from NuGet. If you’re unsure how to do this, right click your project in Visual Studio and click ‘ **Manage NuGet Packages** ’. Just search for these packages and just click install. You can use the latest versions if you want, but for the Table Storage SDK, I used version 1.0.6.

```
Microsoft.Azure.Cosmos.Table
Microsoft.Extensions.Configuration
Microsoft.Extensions.Configuration.Binder
Microsoft.Extensions.Configuration.Json
```

We’ll store our Primary connection string to our Table API account in a “ **Settings.Json** ” file. We’ll then use a ConfigurationBuilder to load the connection string when we run our program.

Do to this, create a new JSON file and add the following code to it.

```
{  
    "ConnectionString": "<YOUR\_TABLE\_STORAGE\_PRIMARY\_KEY>"
}
```

You can get your connection string by going into your Table account and clicking on ‘ **Connection String** ’ under ‘ **Settings** ’. Copy your primary key to the clipboard and paste it in your “ **Settings.json** ” file.

![](https://cdn-images-1.medium.com/max/1024/1*4m_GYh-uKBp0tUn5E2U25Q.png)

Now that we’ve set up our JSON file, I’ve created a class that loads the settings our application will need to connect to our table account.

{% gist https://gist.github.com/willvelida/37610c1e4f9ad37ffe2da2ed26e4eac0 %}

With this set up, I’ll create a separate class that connects to our Table account, then connects to a specified table within our Table account. If you’ve worked with Table Storage in C# before, you’ll notice that the code is identical. This makes it real easy to migrate from normal table storage to Azure Cosmos DB 😍.

{% gist https://gist.github.com/willvelida/87f7124b36f6cd05b901f27f8d3f9187 %}

Now that we can connect to our account, let’s define an entity that we can insert into our table. For the Table API, we need to inherit our entities from the TableEntity class.

The Partition Key and Entity Key uniquely identify data within our Table account. Here, I have defined public properties that I want my Hero entities to store. I’ve assigned my Partition Key to have the **heroName** property and I’ve set my **alterEgo** property as the Entity Key.

Here is our **HeroEntity** class below.

{% gist https://gist.github.com/willvelida/9f220b5021ea81590d76e92457428706 %}

So now that I’ve got my HeroEntity all set up, let’s take a look at my **Program.cs** file. I’ll go through each operation one-by-one and I’ll put a link to the whole GitHub repo in the conclusion for your benefit.

{% gist https://gist.github.com/willvelida/411dccccadc1928ffabd12aefa55083d %}

But for now, let’s try to insert data into our Cosmos DB Table API account, check out the following method below:

{% gist https://gist.github.com/willvelida/dbef5c4ad2bc3629bb5e5f1292f0bddb %}

In my Program.cs file, I’ve got a list of seed data that I want to insert into my table account. In my _InsertOrMergeHero()_ method, I’m passing through the name of the table that I want to insert my hero into and the **HeroEntity** that I’m attempting to persist.

I’m instantiating a **TableOperation** variable called **insertOrMerge** and then passing my entity to the _InsertOrMerge()_ method. This method will either create a new entity if it doesn’t exist or update it if it does. We then instantiate a **TableResult** variable that will represent the result of the operation. We then return the result of that operation.

After inserting all the entities within our List, we should now see them all stored within our Table.

![](https://cdn-images-1.medium.com/max/883/1*0KFV34vHMXQ1BjV-HnLEjA.png)

Reading a specific hero is pretty straight forward. Let’s say I want to retrieve my Superman entity, here, I call the _Retrieve()_ method on my **TableOperation** and pass through my Partition Key and Row Key values.

{% gist https://gist.github.com/willvelida/d18360b0d84ba4735bed2e458469bf33 %}

We should see our retrieved entity appear in our Console app.

![](https://cdn-images-1.medium.com/max/1024/1*uT_eN1TsPytddiSDoDce9A.png)

Something doesn’t look right though. Technically, Superman’s hometown on Krypton was Kryptonopolis, so let’s update our call our _GetHero()_ method to retrieve our Superman **HeroEntity** , then set the Hometown property as ‘ **Kryptonopolis** ’ and then call the _InsertOrMerge()_ method to update our Superman entity.

```
Console.WriteLine("Let's see if we can find Superman! Performing a read."); 

var superman = await OperationsHelper.GetHero(cloudTable, "Superman", "Clark Kent");

Console.WriteLine("Wait, his hometown isn't right! Let's update it.");

superman.Hometown = "Kryptonopolis";

await OperationsHelper.InsertOrMergeHero(cloudTable, superman);
```

When we query our Superman entity in the data explorer, we should now see the Hometown property for Superman updated.

![](https://cdn-images-1.medium.com/max/879/1*rPLLxwCkkDk3kOpxUPjruA.png)

Let’s delete a hero from our Table. Since Tony Stark snapped his fingers to save the universe at the cost of his own life, let’s delete him from our table.

Here, we just call the _.Delete()_ method on **TableOperation** and pass through our Entity as a parameter. In my **Program.cs** file, I first call my _.GetHero()_ method to retrieve Tony from my table and set that as our **HeroEntity** , then I pass through the entity to my ._DeleteHero()_ method.

{% gist https://gist.github.com/willvelida/0310c4be89cb939ddcc0f2c5d6b97b18 %}

Now if we query him to try and find him in our table, he’ll be gone.

(Love you 3000 😥).

![](https://cdn-images-1.medium.com/max/878/1*OUpafuovq1T34bTizU7mqg.png)

After reading this article, I hope you’ve grasped the very basics of working with the Azure Cosmos DB Table API. If you’ve worked with Table Storage before, you’ll notice that it’s all very familiar and if you’re considering migrating your Table Storage data to Cosmos DB, there’s very little changes required to make it work.

If you want to see the full demo app, check out my GitHub repo for it [here](https://github.com/willvelida/comic-heroes-sample).

Hopefully you’ve enjoyed reading this article! If you have any questions or comments, let me know and I’ll do my best to answer them. 😊