Provisioning Cosmos DB for Table

1. Start Locally

Firstly, we need to launch Locally which we can do from a terminal by running:

Once Locally has started, the Locally Dashboard will open automatically:

2. Create a Resource Group

Next we can create the Resource Group to hold the account:

There's two things to note here:

1. The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with locally run.
2. Locally intentionally uses a different set of locations to Azure as a safety precaution, so that you can be confident you're deploying against Locally rather than regular Azure. You can also configure Locally to use the Azure locations too, but you'll want to be extra sure that you're prefixing commands with locally run when you do.

3. Create the Cosmos DB Account

The Table API is a capability we turn on when creating the account, with --capabilities EnableTable:

{
  "capabilities": [
    "EnableTable"
  ],
  "name": "sample-cosmos-table-1",
  "provisioningState": "Succeeded"
}

4. Create a table

Now we can create a table called orders:

{
  "name": "orders",
  "type": "Microsoft.DocumentDB/databaseAccounts/tables"
}

And check it's there:

Name
------
orders

5. Get the Table connection string

The account hands out connection strings for both its SQL and Table APIs:

Description                                  Type
-------------------------------------------  ------
Primary SQL Connection String                Sql
Secondary SQL Connection String              Sql
Primary Read-Only SQL Connection String      Sql
Secondary Read-Only SQL Connection String    Sql
Primary Table Connection String              Table
Secondary Table Connection String            Table
Primary Read-Only Table Connection String    Table
Secondary Read-Only Table Connection String  Table

The az storage entity commands want the Table one. Putting it in AZURE_STORAGE_CONNECTION_STRING means we don't have to pass it to each command:

Its TableEndpoint is https://sample-cosmos-table-1-tables.cosmonaut.locally:5665/, served by Locally's own DNS server and pointing at the Cosmos DB Emulator running on your machine.

6. Insert and query entities

Every entity needs a PartitionKey and a RowKey. We'll partition orders by customer, and mark Quantity as a number, since the Azure CLI sends everything else as a string:

Filtering on the partition key gets one customer's orders:

RowKey      Product    Quantity
----------  ---------  ----------
order-1001  Widget     3
order-1002  Gadget     1

And we can filter on any other property too, across every partition:

PartitionKey    RowKey      Quantity
--------------  ----------  ----------
customer-42     order-1001  3
customer-7      order-1003  5

7. Update and delete an entity

A merge updates the properties we pass and leaves the rest alone. Let's change the quantity on the first order:

{
  "Product": "Widget",
  "Quantity": 4
}

Then delete the second order:

PartitionKey    RowKey      Product    Quantity
--------------  ----------  ---------  ----------
customer-42     order-1001  Widget     4
customer-7      order-1003  Widget     5

8. Tidy up

Finally, we can tidy up. To remove just the table, and every entity in it:

Or to remove the Resource Group and everything within it:

Doing this with other tooling

Whilst this guide used the Azure CLI, the account and its tables work the same way through any of the tooling that Locally supports - Microsoft.DocumentDB/databaseAccounts and Microsoft.DocumentDB/databaseAccounts/tables resources in HashiCorp Terraform or OpenTofu, Pulumi, Bicep or an ARM Template all provision against Locally in the same way.

The same is true of the data plane: hand the Table connection string to the Azure Tables SDK for .NET, Go or Python and your application reads and writes entities against Locally.

Next steps

To store JSON documents and query them with SQL instead, see Cosmos DB. For the same Table API in a Storage Account, see Table Storage. The Cosmos DB Emulator covers what the data plane supports.

Should you encounter any issues, please take a look at the troubleshooting section.

Resource types this guide uses

These are the Azure resource types this guide creates in Locally:

• Microsoft.DocumentDB/databaseAccounts/tables
• Microsoft.DocumentDB/databaseAccounts