We recently gave the repo a big update. Here’s what’s new.<\/p>\n
The core idea: patterns you can\u00a0see<\/em>, not just read about<\/h2>\nMost pattern catalogs are prose and diagrams. This repo takes a different stance:\u00a0every pattern ships as a runnable sample with an interactive web front end.<\/strong>\u00a0You don’t just read that a distributed lock uses fencing tokens \u2014 you start a few workers, watch them contend for the lock in real time, crash the holder, and see the lease auto\u2011release. The picture\u00a0is<\/em>\u00a0the lesson.<\/p>\nThree principles guide the whole collection:<\/p>\n
\n- Emulator\u2011first.<\/strong>\u00a0Every sample runs entirely on your machine against the Azure Cosmos DB Linux (vNext) emulator<\/a>. No Azure subscription, no account, no keys \u2014 just\u00a0
docker compose up -d<\/code>\u00a0and\u00a0dotnet run<\/code>. Zero setup is the default path.<\/li>\n- Interactive web UX for every pattern.<\/strong>\u00a0A small Blazor front end turns each abstract pattern into something you can click, break, and reason about \u2014 with “why it matters” talking points built right into the page.<\/li>\n
- Secure and optional cloud.<\/strong>\u00a0When you\u00a0do<\/em>\u00a0want to see it in Azure, each sample includes a one\u2011command Azure Developer CLI (
azd<\/code>) template that provisions a\u00a0keyless<\/strong>\u00a0(Microsoft Entra ID + managed identity) deployment \u2014 no secrets stored anywhere.<\/li>\n<\/ul>\nFive brand\u2011new patterns<\/h2>\n1. Vector Search<\/h3>\n
Semantic search over your operational data using Azure Cosmos DB’s\u00a0built\u2011in vector indexing<\/strong><\/a>\u00a0and the\u00a0VectorDistance()<\/code>\u00a0function \u2014 the storage\u2011and\u2011retrieval foundation of RAG. What makes this sample special: it embeds text with a\u00a0small local model<\/strong>, so there’s no API key and no external service. That quietly solves a real pain point \u2014 you can build and CI\/CD an app that uses embeddings\u00a0without pre\u2011deploying a foundation model or baking keys into GitHub secrets<\/strong>.<\/p>\n2. Loop\u2011Safe Change Feed<\/h3>\n
A classic trap: you use the change feed to\u00a0derive<\/em>\u00a0a value and write it back onto the\u00a0same<\/strong>\u00a0document \u2014 and your write re\u2011triggers the feed, which writes again\u2026 forever. This sample shows the standard fix: store a\u00a0hash of the source<\/strong>\u00a0and skip any change whose hash is unchanged (the echo of your own write). One real edit produces exactly\u00a0one enrichment and one skipped echo<\/strong>\u00a0\u2014 the loop is bounded instead of runaway.<\/p>\n![\"The](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/07\/loop-safe-change-feed-web.png\")
<\/a><\/p>\nEach document gets an identicon derived from its text. The\u00a0enrichment writes<\/strong>\u00a0and\u00a0skipped echoes<\/strong>\u00a0counters climb together \u2014 one of each per edit \u2014 which is the loop\u2011safety guarantee made visible.<\/em><\/p>\n3. Hierarchical Partition Key<\/h3>\n
When a single partition key isn’t enough,\u00a0hierarchical (sub)partitioning<\/strong><\/a>\u00a0lets you distribute data across multiple key levels while keeping related items co\u2011located. The sample models a realistic multi\u2011tenant shape and shows the cost and performance impact of getting your partition strategy right.<\/p>\n4. Transactional Outbox<\/h3>\n
Placing an order should both\u00a0change state<\/strong>\u00a0and\u00a0publish an event<\/strong>\u00a0other systems consume \u2014 reliably. Doing those as two separate writes is a\u00a0dual\u2011write<\/em>, and a crash in between loses the event. This sample writes the order\u00a0and<\/strong>\u00a0the event in a single atomic\u00a0TransactionalBatch<\/code>, then relays the event with the change feed \u2014 so it can never be lost, even if the app dies the instant after commit. There’s a crash\u2011toggle playground that lets you watch the naive version lose events while the outbox never does.<\/p>\n![\"transactional](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/07\/transactional-outbox-web.png\")
<\/a><\/p>\n5. Patch API (Partial Document Update)<\/h3>\n
Updating one field usually means a read\u2011modify\u2011write: read the whole document, change a field, write it all back. The\u00a0Patch API<\/strong><\/a>\u00a0sends only the operation instead \u2014 cheaper, lower latency, and no lost updates when different services update different fields. The sample makes the trade\u2011offs concrete with a three\u2011way concurrency race, measured on the emulator:<\/p>\n\n\n\nApproach<\/th>\n Result<\/th>\n Conflicts<\/th>\n RU<\/th>\n<\/tr>\n<\/thead>\n \n\nRead\u2011modify\u2011write, no ETag<\/td>\n \u274c an update is\u00a0lost<\/strong><\/td>\n0<\/td>\n 4<\/td>\n<\/tr>\n \nRead\u2011modify\u2011write\u00a0+ ETag<\/strong><\/td>\n\u2705 correct, after re\u2011read + retry<\/td>\n 1<\/td>\n 6<\/td>\n<\/tr>\n \nPatch<\/strong><\/td>\n\u2705 correct<\/td>\n 0<\/td>\n 2<\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nThe honest punchline: an ETag makes read\u2011modify\u2011write\u00a0correct<\/em>, but because it guards the whole document, two services touching\u00a0different<\/em>\u00a0fields still collide with a needless\u00a0412<\/code>\u00a0and pay to retry. Patch just\u2026 doesn’t.<\/p>\nA pattern in motion: the reworked Distributed Lock<\/h2>\n
Distributed Lock isn’t new to the repo, but it got a full rework and a live web playground this cycle \u2014 and it’s the best single illustration of the “see it work” philosophy. Every acquire, renewal, and release you see is a\u00a0real operation against Azure Cosmos DB<\/strong>.<\/p>\n
Three principles guide the whole collection:<\/p>\n
- \n
- Emulator\u2011first.<\/strong>\u00a0Every sample runs entirely on your machine against the Azure Cosmos DB Linux (vNext) emulator<\/a>. No Azure subscription, no account, no keys \u2014 just\u00a0
docker compose up -d<\/code>\u00a0and\u00a0dotnet run<\/code>. Zero setup is the default path.<\/li>\n- Interactive web UX for every pattern.<\/strong>\u00a0A small Blazor front end turns each abstract pattern into something you can click, break, and reason about \u2014 with “why it matters” talking points built right into the page.<\/li>\n
- Secure and optional cloud.<\/strong>\u00a0When you\u00a0do<\/em>\u00a0want to see it in Azure, each sample includes a one\u2011command Azure Developer CLI (
azd<\/code>) template that provisions a\u00a0keyless<\/strong>\u00a0(Microsoft Entra ID + managed identity) deployment \u2014 no secrets stored anywhere.<\/li>\n<\/ul>\nFive brand\u2011new patterns<\/h2>\n
1. Vector Search<\/h3>\n
Semantic search over your operational data using Azure Cosmos DB’s\u00a0built\u2011in vector indexing<\/strong><\/a>\u00a0and the\u00a0
VectorDistance()<\/code>\u00a0function \u2014 the storage\u2011and\u2011retrieval foundation of RAG. What makes this sample special: it embeds text with a\u00a0small local model<\/strong>, so there’s no API key and no external service. That quietly solves a real pain point \u2014 you can build and CI\/CD an app that uses embeddings\u00a0without pre\u2011deploying a foundation model or baking keys into GitHub secrets<\/strong>.<\/p>\n2. Loop\u2011Safe Change Feed<\/h3>\n
A classic trap: you use the change feed to\u00a0derive<\/em>\u00a0a value and write it back onto the\u00a0same<\/strong>\u00a0document \u2014 and your write re\u2011triggers the feed, which writes again\u2026 forever. This sample shows the standard fix: store a\u00a0hash of the source<\/strong>\u00a0and skip any change whose hash is unchanged (the echo of your own write). One real edit produces exactly\u00a0one enrichment and one skipped echo<\/strong>\u00a0\u2014 the loop is bounded instead of runaway.<\/p>\n
<\/a><\/p>\nEach document gets an identicon derived from its text. The\u00a0enrichment writes<\/strong>\u00a0and\u00a0skipped echoes<\/strong>\u00a0counters climb together \u2014 one of each per edit \u2014 which is the loop\u2011safety guarantee made visible.<\/em><\/p>\n
3. Hierarchical Partition Key<\/h3>\n
When a single partition key isn’t enough,\u00a0hierarchical (sub)partitioning<\/strong><\/a>\u00a0lets you distribute data across multiple key levels while keeping related items co\u2011located. The sample models a realistic multi\u2011tenant shape and shows the cost and performance impact of getting your partition strategy right.<\/p>\n
4. Transactional Outbox<\/h3>\n
Placing an order should both\u00a0change state<\/strong>\u00a0and\u00a0publish an event<\/strong>\u00a0other systems consume \u2014 reliably. Doing those as two separate writes is a\u00a0dual\u2011write<\/em>, and a crash in between loses the event. This sample writes the order\u00a0and<\/strong>\u00a0the event in a single atomic\u00a0
TransactionalBatch<\/code>, then relays the event with the change feed \u2014 so it can never be lost, even if the app dies the instant after commit. There’s a crash\u2011toggle playground that lets you watch the naive version lose events while the outbox never does.<\/p>\n<\/a><\/p>\n5. Patch API (Partial Document Update)<\/h3>\n
Updating one field usually means a read\u2011modify\u2011write: read the whole document, change a field, write it all back. The\u00a0Patch API<\/strong><\/a>\u00a0sends only the operation instead \u2014 cheaper, lower latency, and no lost updates when different services update different fields. The sample makes the trade\u2011offs concrete with a three\u2011way concurrency race, measured on the emulator:<\/p>\n
\n\n
\n \nApproach<\/th>\n Result<\/th>\n Conflicts<\/th>\n RU<\/th>\n<\/tr>\n<\/thead>\n \n Read\u2011modify\u2011write, no ETag<\/td>\n \u274c an update is\u00a0lost<\/strong><\/td>\n 0<\/td>\n 4<\/td>\n<\/tr>\n \n Read\u2011modify\u2011write\u00a0+ ETag<\/strong><\/td>\n \u2705 correct, after re\u2011read + retry<\/td>\n 1<\/td>\n 6<\/td>\n<\/tr>\n \n Patch<\/strong><\/td>\n \u2705 correct<\/td>\n 0<\/td>\n 2<\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n The honest punchline: an ETag makes read\u2011modify\u2011write\u00a0correct<\/em>, but because it guards the whole document, two services touching\u00a0different<\/em>\u00a0fields still collide with a needless\u00a0
412<\/code>\u00a0and pay to retry. Patch just\u2026 doesn’t.<\/p>\nA pattern in motion: the reworked Distributed Lock<\/h2>\n
Distributed Lock isn’t new to the repo, but it got a full rework and a live web playground this cycle \u2014 and it’s the best single illustration of the “see it work” philosophy. Every acquire, renewal, and release you see is a\u00a0real operation against Azure Cosmos DB<\/strong>.<\/p>\n
- Interactive web UX for every pattern.<\/strong>\u00a0A small Blazor front end turns each abstract pattern into something you can click, break, and reason about \u2014 with “why it matters” talking points built right into the page.<\/li>\n
![\"The](\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/07\/distributed-lock-web.png\")
<\/a><\/p>\n