Understanding data modeling syncers

When you use the Cognite Core data model, CogniteFile and CogniteTimeSeries are two special concepts that represent files and time series. A syncer automatically keeps a corresponding asset-centric resource in sync whenever you create or update a node in either of these views.

How syncers work

A concept in a data model is implemented as a view in CDF. A view contains properties that are either connections to other views or mappings to containers — the physical storage of data. See the data modeling documentation for more information about views and containers. CogniteTimeSeries maps to CogniteDescribable (name, description, and similar properties), CogniteSourceable (source, sourceId, and similar properties), and CogniteTimeSeries (time series-specific properties such as type and step). CogniteFile maps to the same CogniteDescribable and CogniteSourceable containers, plus a CogniteFile container that holds file-specific properties. When you create a node that has properties in either the CogniteFile or CogniteTimeSeries containers, a syncer automatically creates a corresponding file or time series resource in the asset-centric CDF API. This supports blob data storage for files and high-performance time series data storage.

Example: Create and sync a time series

The following example uses the Python SDK. Files work in the same way. First, create a CogniteTimeSeries node in data modeling:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.data_modeling.cdm.v1 import CogniteTimeSeriesApply
>>> client = CogniteClient()
>>> my_cognite_timeseries = CogniteTimeSeriesApply(
...    space="demo_space",
...    external_id="my_cognite_timeseries",
...    is_step=False,
...    time_series_type="numeric",
...    name="My Cognite Time Series",
... )
>>> created_cognite_timeseries = client.data_modeling.instances.apply(my_cognite_timeseries).nodes[0]
>>> created_cognite_timeseries.dump()
{'space': 'demo_space',
 'instanceType': 'node',
 'externalId': 'my_cognite_timeseries',
 'version': 1,
 'wasModified': False,
 'lastUpdatedTime': 1762934508337,
 'createdTime': 1762934508337}

The syncer automatically creates a corresponding asset-centric time series resource in CDF:

>>> retrieve_asset_centric_timeseries = client.time_series.retrieve(instance_id=my_cognite_timeseries.as_id())
>>> retrieve_asset_centric_timeseries.dump()
{'instanceId': {'space': 'demo_space', 'externalId': 'my_cognite_timeseries'},
 'name': 'My Cognite Time Series',
 'isString': False,
 'metadata': {},
 'isStep': False,
 'securityCategories': [],
 'id': 4615119519582224,
 'createdTime': 1762934686780,
 'lastUpdatedTime': 1762934686780}

The following diagram illustrates how the syncer links the node to the asset-centric resource and its datapoints store:

Working with synced resources

Inserting and retrieving datapoints

Insert datapoints using the CogniteTimeSeries instance ID:

>>> client.time_series.data.insert(
...    datapoints=[
...        {"timestamp": 1577833200000, "value": 1.0},
...        {"timestamp": 1577919600000, "value": 2.0},
...        {"timestamp": 1578006000000, "value": 3.0},
...    ],
...    instance_id=my_cognite_timeseries.as_id(),
... )

Retrieve datapoints using the instance ID:

>>> last_datapoint_instance_id = client.time_series.data.retrieve_latest(instance_id=my_cognite_timeseries.as_id())
>>> last_datapoint_instance_id.dump()
{'id': 4615119519582224,
 'isString': False,
 'isStep': False,
 'instanceId': {'space': 'demo_space', 'externalId': 'my_cognite_timeseries'},
 'datapoints': [{'timestamp': 1578006000000, 'value': 3.0}]}

Alternatively, use the internal id from the asset-centric time series the syncer created:

>>> last_datapoint_id = client.time_series.data.retrieve_latest(id=retrieve_asset_centric_timeseries.id)
>>> last_datapoint_id.dump()
{'id': 4615119519582224,
 'isString': False,
 'isStep': False,
 'instanceId': {'space': 'demo_space', 'externalId': 'my_cognite_timeseries'},
 'datapoints': [{'timestamp': 1578006000000, 'value': 3.0}]}

Deletion and modification restrictions

The asset-centric time series is linked to the CogniteTimeSeries node and cannot be deleted or modified outside of data modeling. Attempting to delete through the asset-centric API returns an error:

>>> from cognite.client.exceptions import CogniteAPIError
>>> try:
...     client.time_series.delete(retrieve_asset_centric_timeseries.id)
... except CogniteAPIError as e:
...     print(e.message)
Time series with instance ids must be deleted through data modeling

Attempting to modify a DM-controlled property also returns an error:

>>> from cognite.client.data_classes import TimeSeriesUpdate
>>> try:
...     client.time_series.update(TimeSeriesUpdate(id=retrieve_asset_centric_timeseries.id).name.set("New name"))
... except CogniteAPIError as e:
...     print(e.message)
Field 'name' on a time series with instance id can only be updated through the models/instances endpoint

The following properties have no representation in data modeling and can still be modified through the asset-centric API:

externalId
metadata
assetId
dataSetId

Updating properties through data modeling

To update a DM-controlled property such as name, use the data modeling instances endpoint:

>>> from cognite.client.data_classes.data_modeling import NodeApply, NodeOrEdgeData, ViewId
>>> update = NodeApply(
...     space=my_cognite_timeseries.space,
...     external_id=my_cognite_timeseries.external_id,
...     sources=[
...         NodeOrEdgeData(
...             source=ViewId("cdf_cdm", "CogniteTimeSeries", "v1"),
...             properties={"name": "New CogniteTimeSeriesName"}
...         )
...     ]
... )
>>> updated_node = client.data_modeling.instances.apply(update).nodes[0]
>>> updated_node.dump()
{'space': 'demo_space',
 'instanceType': 'node',
 'externalId': 'my_cognite_timeseries',
 'version': 2,
 'wasModified': True,
 'lastUpdatedTime': 1762936334576,
 'createdTime': 1762934508337}

When you retrieve the asset-centric time series again, the name reflects the update:

>>> updated_asset_centric_timeseries = client.time_series.retrieve(id=retrieve_asset_centric_timeseries.id)
>>> updated_asset_centric_timeseries.dump()
{'instanceId': {'space': 'demo_space', 'externalId': 'my_cognite_timeseries'},
 'name': 'New CogniteTimeSeriesName',
 'isString': False,
 'metadata': {},
 'isStep': False,
 'securityCategories': [],
 'id': 4615119519582224,
 'createdTime': 1762934686780,
 'lastUpdatedTime': 1762936334821}

Deploy

Understanding data modeling syncers

How syncers work

Example: Create and sync a time series

Working with synced resources

Inserting and retrieving datapoints

Deletion and modification restrictions

Updating properties through data modeling

Further reading

​How syncers work

​Example: Create and sync a time series

​Working with synced resources

​Inserting and retrieving datapoints

​Deletion and modification restrictions

​Updating properties through data modeling

​Further reading

How syncers work

Example: Create and sync a time series

Working with synced resources

Inserting and retrieving datapoints

Deletion and modification restrictions

Updating properties through data modeling

Further reading