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.

Update and Upsert Mode Parameter

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. The ‘replace_ignore_null’ works similarly, to ‘patch’, but instead of updating it will replace the fields with new values. There is not difference between ‘patch’ and ‘replace_ignore_null’ for fields that only supports set. For example, name and description on TimeSeries. However, for fields that supports set and add/remove, like metadata, ‘patch` will add to the metadata, while ‘replace_ignore_null’ will replace the metadata with the new metadata. 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.

Example patch:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import TimeSeriesWrite
>>> from pprint import pprint
>>> client = CogniteClient()
>>>
>>> new_ts = client.time_series.create(
...     TimeSeriesWrite(
...         external_id="new_ts",
...         name="New TS",
...         metadata={"key": "value", "another": "one"}
...     )
... )
>>>
>>> updated = client.time_series.update(
...     TimeSeriesWrite(
...         external_id="new_ts",
...         description="Updated description",
...         metadata={"key": "new value", "brand": "new"}
...     ),
...     mode="patch"
... )
>>> pprint(updated.as_write().dump())
{'description': 'Updated description',
 'externalId': 'new_ts',
 'metadata': {'another': 'one', 'brand': 'new', 'key': 'new value'},
 'name': 'New TS'}

Example replace:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import TimeSeriesWrite
>>> from pprint import pprint
>>> client = CogniteClient()
>>>
>>> new_ts = client.time_series.create(
...     TimeSeriesWrite(
...         external_id="new_ts",
...         name="New TS",
...         metadata={"key": "value"}
...     )
... )
>>>
>>> updated = client.time_series.update(
...     TimeSeriesWrite(
...         external_id="new_ts",
...         description="Updated description",
...         metadata={"new": "entry"}
...     ),
...     mode="replace"
... )
>>> pprint(updated.as_write().dump())
{'description': 'Updated description',
 'externalId': 'new_ts',
 'metadata': {'new': 'entry'}}

Note that the name parameter was not specified in the update, and was therefore nulled out.

Example replace_ignore_null:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import TimeSeriesWrite
>>> from pprint import pprint
>>> client = CogniteClient()
>>>
>>> new_ts = client.time_series.create(
...     TimeSeriesWrite(
...         external_id="new_ts",
...         name="New TS",
...         metadata={"key": "value"}
...     )
... )
>>>
>>> updated = client.time_series.update(
...     TimeSeriesWrite(
...         external_id="new_ts",
...         description="Updated description",
...         metadata={"new": "entry"}
...     ),
...     mode="replace_ignore_null"
... )
>>> pprint(updated.as_write().dump())
{'description': 'Updated description',
 'externalId': 'new_ts',
 'metadata': {'new': 'entry'},
 'name': 'New TS'}

Note that the name parameter was not specified in the update, and was therefore not changed, same as in patch

Example replace_ignore_null without metadata:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import TimeSeriesWrite
>>> from pprint import pprint
>>> client = CogniteClient()
>>>
>>> new_ts = client.time_series.create(
...     TimeSeriesWrite(
...         external_id="new_ts",
...         name="New TS",
...         metadata={"key": "value"}
...     )
... )
>>>
>>> updated = client.time_series.update(
...     TimeSeriesWrite(
...         external_id="new_ts",
...         description="Updated description",
...     ),
...     mode="replace_ignore_null"
... )
>>> pprint(updated.as_write().dump())
{'description': 'Updated description',
 'externalId': 'new_ts',
 'metadata': {'key': 'value'},
 'name': 'New TS'}

Note Since metadata was not specified in the update, it was not changed.

Alpha and Beta Features

New Cognite Data Fusion API features may get support in the Python SDK before they are released for general availability (GA). These features are marked as alpha or beta in the documentation, and will also invoke a FeaturePreviewWarning when used.

Furthermore, we distinguish between maturity of the API specification and the SDK implementation. Typically, the API specification may be in beta, while the SDK implementation is in alpha.

alpha - The feature is not yet released for general availability. There may be breaking changes to the API specification and/or the SDK implementation without further notice.
beta - The feature is not yet released for general availability. The feature is considered stable and ‘settled’. Learnings during the Beta period may result in a requirement to make breaking changes to API spec/SDK implementation. In these situations, release processes must be coordinated to minimise Beta customer disruption (for example use of DeprecationWarning).