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.

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 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"}},
...             ],
...         )
...     ]
... )