Cosmos DB doesn’t behave like a relational database, so why do so many apps treat it like one? The pattern usually starts innocently with a repository interface and a couple of helper methods to hide the database, then a year later you’re debugging cross-partition queries you didn’t mean to write and write paths that overwrite changes because concurrency was never part of the contract.

In this session we’ll design a reusable .NET data access library that abstracts Cosmos DB access while still leveraging its strengths and keeping the sharp edges visible. We’ll cover how to encapsulate queries without hiding performance costs, how to handle cross-partition queries intentionally, how to manage connections and client reuse, and how to map documents to domain models without losing control of serialization. We’ll also walk through the behaviors you hit in production including consistency choices, ETag-based concurrency, working with nested resources, and robust error handling.

This is aimed at teams building long-lived systems that need a maintainable, evolvable Cosmos DB data access layer, one that makes it easier to do the right thing by default, and harder to do the expensive thing accidentally.