What is the Cosmos DB Patch API and how does it differ from Replace?

The Patch API (partial document update) was introduced in Cosmos DB in 2022 to address a common inefficiency in document updates. Before Patch, the only way to modify a field in a Cosmos DB item was to read the full document, change the field in memory, and replace the entire document. For large documents or high-frequency partial updates this was wasteful — full read + full write = ~6x the RU cost of a targeted patch.

The Patch API lets you specify a list of operations to apply directly on the server without reading the document first. Supported patch operations:

• add — Add a new property or array element at the specified path
• set — Set a property to a value (creates if absent, overwrites if present)
• replace — Replace an existing property (fails if the property does not exist)
• remove — Delete a property
• increment — Atomically increment a numeric property by a delta value
• move — Move a property from one path to another

// C# Patch API example: update price and increment stock count atomically
PatchOperation[] patches = new[]
{
    PatchOperation.Set("/price", 24.99),
    PatchOperation.Increment("/stockCount", -1),
    PatchOperation.Add("/lastModified", DateTime.UtcNow)
};

await container.PatchItemAsync<Product>("product-42",
    new PartitionKey("electronics"), patches);

The increment operation is particularly powerful for counters — it is atomic at the document level, so concurrent increments from multiple clients do not race (unlike read-modify-replace which is a classic read-modify-write race condition). Patch also supports a condition parameter (a SQL WHERE-like filter) that makes the patch conditional — apply only if the document matches the filter, otherwise return a 412.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.