Insert state datapoints into one or more time series

async AsyncCogniteClient.time_series.data.insert_states(

items: StateDatapointsInsert | Sequence[StateDatapointsInsert],

) → None

Insert datapoints into one or more state time series.

State time series are a specialized time series type designed for tracking discrete operational states of industrial equipment. Unlike numeric or string time series, they have a predefined set of valid states and support specialized aggregations optimized for analyzing state changes over time. Each state is a (numericValue, stringValue) pair, e.g. (1, "on") or (0, "off"), and the set of valid pairs for a given time series is defined by its associated state set.

Each datapoint may carry a numeric value, a string value, or both (they must be consistent with the time series’ state set). It may also carry only a status code/symbol, e.g. to mark a period as Bad.

Note

If you are ingesting datapoints directly from a retrieve call (Datapoints or DatapointsArray), you should always fetch with ignore_bad_datapoints=False and include_status=True. Otherwise, bad datapoints are either not retrieved at all (and thus not copied), or, when retrieved without status, a ValueError is likely to be raised before anything is inserted (as only datapoints with a Bad status can have the state omitted, and the exact code is unknown). Without status, any other datapoint, e.g. Uncertain, is inserted as Good.

Warning

State time series are in public preview.

Parameters:

items (StateDatapointsInsert | Sequence[StateDatapointsInsert]) – One StateDatapointsInsert per target state time series. Each carries the instance_id and the datapoints to write.

Examples

Insert state datapoints into a state time series, by using the numeric state values:

>>> from cognite.client import CogniteClient, AsyncCogniteClient
>>> from cognite.client.data_classes import (
...     StateDatapointsInsert,
...     StateDatapointWrite,
...     StatusCode,
... )
>>> from cognite.client.data_classes.data_modeling import NodeId
>>> from datetime import datetime
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>>
>>> to_insert = StateDatapointsInsert(
...     instance_id=NodeId("my-space", "first-state-ts"),
...     datapoints=[
...         StateDatapointWrite(1700000000000, -1),
...         StateDatapointWrite(1700000001000, 13),
...     ],
... )
>>> client.time_series.data.insert_states(to_insert)

To insert into multiple state time series, simply pass a list of StateDatapointsInsert objects:

>>> second_insert = StateDatapointsInsert(
...     instance_id=("my-space", "second-state-ts"),  # tuple form is accepted
...     datapoints=[
...         StateDatapointWrite(datetime(2018, 7, 2), 42),
...         StateDatapointWrite(datetime(2018, 7, 8), 0),
...     ],
... )
>>> client.time_series.data.insert_states([to_insert, second_insert])

The datapoints can also be given as Datapoints/DatapointsArray retrieved from a state time series, e.g. to easily copy data. Only the numeric states are used, and status codes are preserved: Use include_status=True to retrieve them, and ignore_bad_datapoints=False to also copy the bad datapoints. If the State Set differs between the source and target, the insert will fail.

>>> to_insert = client.time_series.data.retrieve_arrays(
...     instance_id=NodeId("state-space", "ts-read-from"),
...     include_status=True,
...     ignore_bad_datapoints=False,
... )
>>> client.time_series.data.insert_states(  
...     StateDatapointsInsert(
...         instance_id=NodeId("state-space", "ts-write-to"),
...         datapoints=to_insert,
...     )
... )

The datapoints to insert can also be given by the string state value (or a matching combination). Status codes can also be specified:

>>> datapoints = [
...     StateDatapointWrite(11, numeric_value=0),
...     StateDatapointWrite(12, string_value="OFF"),
...     StateDatapointWrite(13, numeric_value=0, string_value="OFF"),
...     StateDatapointWrite(14, 1, status_code=StatusCode.Good),
...     StateDatapointWrite(15, string_value="OFF", status_symbol=StatusCode.Uncertain),
...     # Datapoints marked bad can have no numeric/string value:
...     StateDatapointWrite(16, status_code=StatusCode.Bad),
... ]

Datapoints can also be given as dicts, matching the API’s JSON shape (both snake_case and camelCase accepted). Note that status codes/symbols must be given as a nested status sub-dict:

>>> client.time_series.data.insert_states(
...     [
...         StateDatapointsInsert(
...             instance_id=NodeId("my-space", "my-state-ts"),
...             datapoints=[
...                 {
...                     "timestamp": 1700000000000,
...                     "numeric_value": 0,
...                     "string_value": "off",
...                 },
...                 {
...                     "timestamp": 1700000001000,
...                     "numeric_value": 1,
...                     "string_value": "on",
...                 },
...                 {"timestamp": 1700000002000, "status": {"symbol": "Bad"}},
...             ],
...         )
...     ]
... )