This question relates to Microsoft.Azure.Cosmos v3.11.0.
The documentation of UpsertItemAsync doesn't specify the exact semantics for the "upsert" operation. In particular, is it an insert + replace, or insert + (partial) update? (I suspect the former, given that this issue is still open as of today.)
CreateItemAsync will create a new item but will fail if there already is an item with the same ID.
ReplaceItemAsync will replace an existing item with the same ID but will fail if that item doesn't exists.
UpsertItemAsync combines the above two operations so it will either create or replace any item with the specified ID. So it's not an "insert + replace". Instead it's an "insert or replace".
Furthermore PatchItemAsync is now available so Cosmos also supports "partial updates".
