CosmosDb – Updating a Document (Partially)

May 2021 Update: It's happening! Whilst it has not happened yet, this is now in private preview. If you want to enroll, check out this link !

May 2020 Update: This article is still valid. Microsoft are still 'working' on the six year old suggestion linked below and we don't have a release date yet.

Updating documents in the CosmosDb, or updating a column in a record on a table for you hard core SQL enthusiasts is a basic task for all developers. It’s a base function and the third concept you probably learnt in structuring  your API/application (CRUD – Create, Retrieve, Update and Delete functions) so it’s a very reasonable thing to expect to find in the high performance CosmosDb.

CosmosDb doesn’t support Update

Let me start bluntly – there is no such thing as a partial update in CosmosDb. 

This might surprise you (it certainly did me), but let me assure you it’s true. I say partial because that’s ultimately what we’re trying to achieve, it’s very uncommon you’d want to update every property on your document but for argument’s sake this would be fine as you’d be overwriting every property and won’t risk losing data. 

Microsoft has an open ‘suggestion‘ from 2014, that they acknowledged in 2016 and as of March 5th 2018 claim to be actively working on it. As of this blog though (Drafted December 2018), no such update has been released.

This means that for anyone currently working on a design for a CosmosDb application, you will have to rethink your design architecture to support the concept of ‘replace’ instead.

Whats Replace in DocumentDb?

To update a document in CosmosDb on the server isn’t possible, but you can do whatever you want in the memory of your own application. 

This means that in order to ‘update’ the document, you will need to retrieve the entire document from the CosmosDb, update the property/properties in your application and then call the ‘Replace’ method in the CosmosDb SDK to replace the document in question. Alternatively you could use ‘Upsert’ which checks if the document already exists and performs an ‘Insert’ if false or ‘Replace’ if true.

It’s important to make sure you have the latest version of the document before you commit an update like this, so make sure that you build into your application logic to return the original document in its entirety, before you make your changes and commit it back!


  1. 1. Is this still true, and
    2. “Alternatively you could use ‘Upsert’ which checks if the document already exists and performs an ‘Insert’ if true or ‘Replace’ if false.” I think might be backwards.


    1. Yes this is still true. I’ve put a note at the top of the page to reflect this. Fingers crossed they update this soon… Thanks for pointing out the true/false gaff! I’ve updated as well.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.