Azure CosmosDB

Azure CosmosDB installation

Develop locally using the Azure Cosmos DB emulator provides an introduction into working with Cosmos DB

Start the emulator

"C:\Program Files\Azure Cosmos DB Emulator\Microsoft.Azure.Cosmos.Emulator.exe"

Confirming network connectivity

It takes considerable time to startup but you can check it is running by looking for the port activation

netstat -na | findstr 8081
  TCP    127.0.0.1:8081         0.0.0.0:0              LISTENING

At this point you can open a browser on the URl https://127.0.0.1:8081/_explorer/index.html and it will display a configuration page

Confirming the task is running

tasklist | findstr Azure

Microsoft.Azure.Cosmos.Em    14728 Console                   14     22,652 K
Microsoft.Azure.Cosmos.Ma     6612 Console                   14     25,476 K
Microsoft.Azure.Cosmos.Se     8860 Console                   14     25,428 K
Microsoft.Azure.Cosmos.St    16004 Console                   14     48,500 K

Stopping the emulator

"C:\Program Files\Azure Cosmos DB Emulator\Microsoft.Azure.Cosmos.Emulator.exe" /shutdown

Extracting the connections details

On this web page you will see

URI
https://localhost:8081

Primary Key
C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

on Azure CLI commands these

URI maps to --url-connection options
Primary Key maps to --key options

These can also be stored in environmental variables

set COSMOSDB_ENDPOINT=https://localhost:8081
set COSMOSDB_KEY=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Azure Cosmos DB Databases

A Cosmos DB SQL database is responsible for one ore more Cosmos DB containers (collections) which are schema-agnostic container of JSON documents. A containers is the unit of scalability (replication etc), with queries generally excuted against containers and not databases.

Create an CosmosDB Database and Container

az cosmosdb database create  --db-name TestDB --key %COSMOSDB_KEY% --url-connection %COSMOSDB_ENDPOINT%

az cosmosdb collection create --collection-name TestContainer --db-name TestDB --partition-key-path "/id" --throughput 400 --url-connection %COSMOSDB_ENDPOINT% --key %COSMOSDB_KEY%

You can show these configurations by doing

az cosmosdb database list --url-connection %COSMOSDB_ENDPOINT% --key %COSMOSDB_KEY%
az cosmosdb collection list --db-name TestDB --url-connection %COSMOSDB_ENDPOINT% --key %COSMOSDB_KEY%

You can also see these via the Azure Cosmos DB Emulator explorer tab.

CosmosDB NOSQL record mandated keys

These values are metadata fields in a CosmosDB NoSQL document:

"_rid": Resource ID, a unique identifier for the document within the database.
"_self": A self-link, representing the full path to the document resource.
"_etag": Entity Tag, used for optimistic concurrency control. It changes whenever the document is updated.
"_attachments": A link to the attachments associated with this document, if any.
"_ts": Timestamp of the last update to the document, represented as Unix epoch time in seconds.

it's possible to use the _rid (Resource ID) values to uniquely identify documents in a Cosmos DB NoSQL database and container, but it's not typically recommended as the primary identifier. Here's why:

System-generated: The _rid is automatically generated by Cosmos DB and not meant to be set or modified by users.
Opaque: The format of _rid is internal to Cosmos DB and may change without notice.
Performance: Queries using _rid are not as efficient as those using the user-defined id field.

Instead, it's generally recommended to construct a built-in "id" property as the primary identifier.

thoughtful-solutions/Azure_CosmosDB_Emulator.md