From e7fe1556b1f8ee144be12bcc821a09c1515db3e7 Mon Sep 17 00:00:00 2001
From: anders-albert <anders0albert@gmail.com>
Date: Wed, 19 Jul 2023 16:39:54 +0200
Subject: [PATCH] docs: upsert in appendix
---
docs/source/appendix.rst | 22 ++++++++++++++++++++++
docs/source/index.rst | 1 +
2 files changed, 23 insertions(+)
create mode 100644 docs/source/appendix.rst
diff --git a/docs/source/appendix.rst b/docs/source/appendix.rst
new file mode 100644
index 0000000000..99585098ea
--- /dev/null
+++ b/docs/source/appendix.rst
@@ -0,0 +1,22 @@
+Appendix
+---------
+
+.. _appendix-upsert:
+
+Upsert
+^^^^^^^^^^^^^^^^^^^^
+
+Upsert methods `cognite_client.api.upsert()` for example `cognite_client.assets.upsert()` the following caveats and
+notes apply:
+
+.. warning::
+ Upsert is not an atomic operation. It performs multiple calls to the update and create endpoints, depending
+ on whether the items exist from before or not. This means that if one of the calls fail, it is possible
+ that some of the items have been updated/created while others have not been created/updated.
+
+.. note::
+ The mode parameter controls how the update is performed. If you set 'patch', the call will only update
+ the fields in the Item object that are not None. This means that if the items exists from before, the
+ fields that are not specified will not be changed. If you set 'replace', all the fields that are not
+ specified, i.e., set to None and support being set to null, will be nulled out. See the API
+ documentation for the update endpoint for more information.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index fd0916d73f..98e46ba9c1 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -52,3 +52,4 @@ Contents
exceptions
utils
testing
+ appendix