21

I'm trying to understand this part of the API so I can update documents in the most efficient way possible.

Given the following:

  • "Replace" requires that a document already exists
  • "Upsert" doesn't require that a document exists, but needs the document ID if it's going to do an update.
  • Neither command can do partial document updates, which means I can't think of any scenario where I wouldn't have to query the document first, then make the change to the affected property, then replace/upsert the entire document.

If I always have to query the document first anyway so as to avoid wiping out any property values that aren't passed back to the upsert/replace, and I can't do a partial updates, what's the point of having both upsert and replace?

Am I missing the intended use cases for these two commands?

Simon Ordo
  • 1,517
  • 2
  • 14
  • 23
  • 1
    I have a scenario where upsert is needed: I am adding a "file" and always want to be sure the "folder" exists, so instead of checking whether it already exists, I just upsert a new folder every time. – Niels Brinch Sep 03 '18 at 19:14
  • On May 25, 2021 Microsoft announced partial update support for documents in CosmosDB available for private preview. See their announcement here: https://azure.microsoft.com/en-us/updates/partial-document-update-for-azure-cosmos-db-in-private-preview/ – Manfred Oct 09 '21 at 23:45

1 Answers1

27

You've already described the key differences between the two. Upsert will create a document if it doesn't already exist otherwise overwrite it. Replace requires that a document already exist and then overwrites it. Which to use is a concern of your application. There are certain circumstances where you would want to use replace because if the document didn't already exist it would constitute an error in your business logic. Otherwise they are very similar.

I understand that the lack of being able to do a partial update can appear frustrating. However, Cosmos has a powerful server side programming model in the form of Stored Procedures which you write in Javascript. You could easily create a SPROC that receives a partial document and updates or adds only those properties that are new or changed which would give you the functionality you're ultimately looking for.

Jesse Carter
  • 20,062
  • 7
  • 64
  • 101
  • Oh! Do you by chance know of any samples that show this technique or discuss involved algorithm? are you thinking of a "patch" type solution? – Simon Ordo Jul 26 '17 at 22:24
  • 2
    That's outside the scope of this question. If you upvote and accept this one and then ask a different question in regards to writing a stored procedure to allow for partial updates of a document I can attempt to help you there – Jesse Carter Jul 26 '17 at 23:18
  • 3
    I think it is important to limit the amount of "business" logic in the database. That code tends to be very specific to the database engine in question (CosmosDB in this case). In a decent sized system, when you want to change where you want to run your business logic, being tied to the db engine can be a severely limiting factor. As of Oct 2021, I'm working with a client who is struggling to get 700,000 lines of code out of their database engine to run it elsewhere. It's a multi-year effort in their case. Adding partial update support may be one of the rare exceptions, though. – Manfred Oct 09 '21 at 23:40