In our previous blogs we introduced you to what is Azure Cosmos DB and Azure Cosmos DB APIs like Azure Cosmos DB for PostgreSQL, Azure Cosmos DB for Apache Gremlin, Azure Cosmos DB for MongoDB. In this blog we are going to introduce you Azure Cosmos DB Emulator which will help to run Azure Cosmos DB offline and do local development with ease. 

Benefits of Azure Cosmos DB Emulator 

Local Development Environment: The emulator provides a local environment that closely emulates the Azure Cosmos DB service. You can use it to develop and test your applications without needing an active Azure subscription or incurring any service costs. 
Cost-Free Testing: By using the emulator, you can write and test code that interacts with Azure Cosmos DB APIs even when you have no network connection. This allows you to avoid any costs associated with using the actual cloud service 
Automation Workflow Support: Incorporating the emulator into your automation workflows enables consistent testing across local development machines and remote continuous integration jobs. 

Prerequisites 

.NET 6 or later, Node.js LTS, or Python 3.7 or later 

Ensure that all required executables are available in your PATH. 

Windows emulator 

64-bit Windows Server 2016, 2019, Windows 10, or Windows 11. 
Minimum hardware requirements: 

2-GB RAM 
10-GB available hard disk space 

What will be covered 

Installation process of Azure Cosmos DB Emulator 
Using Explorer in Azure Cosmos DB Emulator 
Connecting Azure Cosmos DB Emulator with Azure Data Studio 
Consuming Azure Cosmos DB using Azure Cosmos DB client library for JavaScript/TypeScript 

Installation process of Azure Cosmos DB Emulator   

Visit this page  
Under choose an API, select your preferred API, I will go with NoSQL. 
You can run the emulator in docker(both linux & windows) or windows via local installation which we are going to do. 
Download the Azure Cosmos DB emulator. 
Run the installer on your local machine with administrative privileges. 
The emulator automatically installs the appropriate developer certificates and configures firewall rules on your local machine. 

Start the emulator 

Start the emulator by selecting the application in the Windows Start menu. 
Alternatively, you can start the emulator’s executable (Microsoft.Azure.Cosmos.Emulator.exe) at the %ProgramFiles%Azure Cosmos DB Emulator path. 
Also, you can start the emulator from the command-line. Use these parameters to configure the emulator ie you can specify the port to use for the API for NoSQL endpoint. More about emulator cli commands  

Microsoft.Azure.Cosmos.Emulator.exe /Port=65000

The emulator automatically opens the data explorer using the URL https://localhost:8081/_explorer/index.html 
If you’re using docker you must configure emulator’s TLS/SSL certificate but Windows local installation of the emulator automatically imports the TLS/SSL certificates. No further action is necessary. 
You should be welcomed by this familiar screen. 

Using Explorer in Azure Cosmos DB Emulator 

Create a database, container, select database throughput, database max RU/s and partition key. Then press okey 

 You can confirm that you have created the database and container by 

Let’s create an item in our container. Click on items then new item and paste below json object and save. 

{

“eventId”: “unique_event_id”,

“eventName”: “Marathon”,

“eventDate”: “2024-05-20”,

“participants”: [

{

“participantId”: “participant1”,

“name”: “Alice”,

“score”: 1200

},

{

“participantId”: “participant2”,
“name”: “Bob”,
“score”: 1100

}
]

}

 Run query to select all items in our container. Click on run query, write your query and execute the query. 

You can access the Query Stats like RUs usage. You can also export the stats. 

Connecting Azure Cosmos DB Emulator with Azure Data Studio 

Download Azure data studio here and install it in your machine. 

Go to Azure Cosmos DB Emulator quickstart page and copy the Primary Connection String 

Open Azure data studio. Under extensions search Azure Cosmos DB and install the extension. 

Click on connections, create new connection, then select Azure Cosmos DB for NoSQL, select connection string, the paste the Primary Connection String we copied in the emulator. Press connect. 

The connection is successful, and you can easily use Azure Data Studio if its your preferred tool and create databases, containers make queries etc. 

U can take advantage of the import sample data button to get sample data to get started. A new container will be created with data. 

Consuming Azure Cosmos DB using Azure Cosmos DB client library for JavaScript/TypeScript 

We are going to use Azure Cosmos DB client library for JavaScript/TypeScript which is an SDK intended for JavaScript/TypeScript applications to interact with Azure Cosmos DB APIs. With it we can  

Create Cosmos DB databases and modify their settings.
Create and modify containers to store collections of JSON documents.
Create, read, update, and delete the items (JSON documents) in your containers.
Query the documents in your database using SQL-like syntax 

You can read more about this SDK here. 
I have prepared a small workshop here, to help you interact with Azure Cosmos DB Emulator with a simple API starter code which you can hook up with hono or express or your favorite JavaScript / Typescript backend. 

In client.config.ts, we have just initialized our cosmosClient and passed in endpoint and key stored in .env file. NB: I have added agent property to allow us to use the “https:” from our emulator smoothly in our local development. 
I have imported client.config.ts into db.config.ts to help us create our database and container programtically. Lastly I’m using data.ts to store sample objects we can use to save in our container. 

In my index.ts, I have included several functions to help interact with our emulator. If you run pnpm run dev

 or npm run dev you will get [ ]  meaning our container is empty but it have been created together with the database. 

If you uncomment createFamilyMember(familyMember) and alsorun you code. You should get one family member create 

You can confirm this on the Emulators explorer. 

Read more 

Optimize development and testing cost in Azure Cosmos DB 
Understand your Azure Cosmos DB bill 
Optimize request cost in Azure Cosmos DB 
Estimate RU/s using the Azure Cosmos DB capacity planner – Azure Cosmos DB for NoSQL 

​Microsoft Tech Community – Latest Blogs –Read More