Upsert time series

async AsyncCogniteClient.time_series.upsert( item: TimeSeries | TimeSeriesWrite | Sequence[TimeSeries | TimeSeriesWrite], mode: Literal['patch', 'replace'] = 'patch', ) → TimeSeries | TimeSeriesList

Upsert time series, i.e., update if it exists, and create if it does not exist.

Deprecated since version 8.23.0: The (asset-centric) Time Series API is deprecated and is scheduled for removal on 2027-12-31. Create and query time series as CogniteTimeSeries instances in the core data model (data point operations remain available via instance_id). See https://docs.cognite.com/cdf/deprecated for details and migration guidance.

Note this is a convenience method that handles the upserting for you by first calling update on all items, and if any of them fail because they do not exist, it will create them instead.

For more details, see Upsert.

Parameters:

item (TimeSeries | TimeSeriesWrite | Sequence[TimeSeries | TimeSeriesWrite]) – TimeSeries or list of TimeSeries to upsert.
mode (Literal['patch', 'replace']) – Whether to patch or replace in the case the time series are existing. If you set ‘patch’, the call will only update fields with non-null values (default). Setting ‘replace’ will unset any fields that are not specified.

Returns:

The upserted time series(s).

Return type:

TimeSeries | TimeSeriesList

Examples

Upsert for TimeSeries:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import TimeSeriesWrite
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> existing_time_series = client.time_series.retrieve(id=1)
>>> existing_time_series.description = "New description"
>>> new_time_series = TimeSeriesWrite(
...     external_id="new_timeSeries", description="New timeSeries"
... )
>>> res = client.time_series.upsert(
...     [existing_time_series, new_time_series], mode="replace"
... )