cosmos-entity

What problem does it solve?

Designing and maintaining Cosmos DB document entities that are consistent, queryable, and safe for concurrent updates is challenging without clear conventions for ids, partitioning, discriminators, and concurrency control. This Skill captures a repeatable pattern to ensure entities across a microservice or domain follow the same contract and partition strategy to avoid hot partitions, ambiguous queries, and update conflicts.

Core Features & Use Cases

• IContainerDocument contract: Standardizes required properties such as ContainerName, PartitionKeys, Discriminator, and ETag so different services and readers can rely on the same shape.
• Hierarchical partition keys: Recommends a three-level PartitionKeyBuilder strategy to distribute load and enable efficient scoped queries.
• Polymorphic containers: Uses a Discriminator string to allow multiple entity types to coexist in a single container while supporting polymorphic queries.
• Optimistic concurrency: Uses ETag for safe updates and recommends factory methods and Apply patterns for event-sourced creation and updates.
• Anti-pattern guidance: Calls out common mistakes like missing lowercase id, single partition keys, unbounded nested arrays, and public setters without factories.

Quick Start

Create a Cosmos DB entity for sales invoices using IContainerDocument with a three-level partition key, a Discriminator property, lowercase id, ETag support, and factory methods for event-based construction.