Hopp til hovedinnhold

Time series in data modeling

Cognite's core data model has a built-in CogniteTimeSeries concept to ingest and retrieve time series. CogniteTimeSeries integrates with the time series API. To ingest and retrieve data points, you must use the same API.

This article describes how time series are handled differently in data modeling and in asset-centric data models.

Create time series​

In data modeling, each time series is a node in the property graph. You can create, update, and delete time series using the same API as other instances. The instanceType is node, and the combination of space and externalId identifies the time series and links it to the data points.

Time series must be of a specific type: numeric or string. You set the type when creating the time series. The type affects how the data points are stored, and to prevent potential data loss, you can't change it later. The isStep property determines how to interpolate between data points, and you can change the property later. Data modeling doesn't support all the time series properties of the asset-centric data model.

Create time series with the API​

To create time series in data modeling, use the create or update nodes/edges endpoint. The node must have data in the cdf_cdm:CogniteTimeSeries/v1 system view to be recognized as a time series. The type is the only mandatory property.

Example request​

{
  "items": [
    {
      "space": "test",
      "externalId": "minimal_example",
      "instanceType": "node",
      "sources": [
        {
          "source": {
            "type": "view",
            "space": "cdf_cdm",
            "externalId": "CogniteTimeSeries",
            "version": "v1"
          },
          "properties": {
            "name": "Time series A",
            "type": "numeric"
          }
        }
      ]
    }
  ]
}
Example request with all properties
{
  "items": [
    {
      "space": "test",
      "externalId": "hello",
      "instanceType": "node",
      "sources": [
        {
          "source": {
            "type": "view",
            "space": "cdf_cdm",
            "externalId": "CogniteTimeSeries",
            "version": "v1"
          },
          "properties": {
            "type": "numeric",
            "isStep": true,
            "unit": {
              "space": "cdf_cdm_units",
              "externalId": "temperature:deg_c"
            },
            "sourceUnit": "C",

            "name": "Hello, world!",
            "description": "My new description",
            "tags": ["TagA", "TagB"],
            "aliases": ["hello_world"],

            "assets": [],
            "equipment": [],

            "sourceId": "examples",
            "sourceContext": "documentation",
            "sourceCreatedTime": "2024-08-28T13:16:25.228Z",
            "sourceUpdatedTime": "2024-08-28T13:20:25.228Z",
            "sourceCreatedUser": "John Doe",
            "sourceUpdatedUser": "Jane Doe"
          }
        }
      ]
    }
  ]
}

Create time series with the Python SDK​

from cognite.client import CogniteClient
from cognite.client.data_classes.data_modeling import DirectRelationReference, NodeId
from cognite.client.data_classes.data_modeling.cdm.v1 import CogniteTimeSeriesApply

# Instantiate Cognite SDK client:
client = CogniteClient()

# Insert a new CogniteTimeSeries
client.data_modeling.instances.apply(
    CogniteTimeSeriesApply(
        space="test",
        external_id="hello",
        name="Hello, world!",
        is_step=True,
        time_series_type="numeric",
        unit=DirectRelationReference("cdf_cdm_units", "temperature:deg_c"),
    )
)

# Insert data points
client.time_series.data.insert(
    instance_id=NodeId("test", "hello"),
    datapoints=[
        (1724845953621, 0.0),
        (1724845970101, 1.0),
    ],
)

# Retrieve data points
client.time_series.data.retrieve(
    instance_id=NodeId("test", "hello"),
    start=0,
)

For more examples using the Python SDK, please see the cognite-sdk documentation.

Access control​

Data modeling uses spaces for governance and access control, not data sets like asset-centric data models. You need the dataModels:read capability to the cdf_cdm space to access time series. Also, you need dataModelInstances access to the space with the time series. You have the same access to data points that you have to time series. If you have read/write access to a time series, you can also read/write its data points.

CogniteTimeSeries replicates to the asset-centric data model where they can be accessed and modified, but not deleted. The properties you set through data modeling are protected, and must be updated through data modeling.

If you modify dataSetId or assetId through the asset-centric data model, the time series and data points may become accessible to users without data modeling access. Users with access to all time series will also have access to time series in data modeling.

Time series with a write-protected data set denies write access to data points, unless the user has datasets:owner access to the data set. Properties set by data modeling aren't write-protected.

merk

Data modeling doesn't support security categories.

Migrating time series from asset-centric data models to data modeling​

Migrating time series from asset-centric data models to data modeling requires careful planning. If you currently rely on data sets or security categories to control access to time series, you must set up equivalent access control in data modeling.

Ensure you don't grant users unintended access, including access to delete time series and data points. Users with access to a space in data modeling get access to all time series and data points in the space. They can modify and delete time series and data points if they have write access.

Consistency​

Except for the limitations below, time series and data points are immediately consistent. As soon as they're ingested, they're available to query.

Data points in recently updated time series​

When you update a time series, the data points API doesn't immediately reflect the change. The change usually shows up in a few seconds, but in exceptional cases, like when you update thousands of time series at once, it can take longer.

forsiktig

If you delete a time series, data points may continue to be ingested until the deletion has been reflected in the data points API. These data points will later be lost because the time series has been deleted.

Also, if you later recreate the time series with the same space and externalId, and the change has still not been reflected in the data points API, the data points may be ingested into the old time series, not the new one.

If a property like isStep isn't reflected in the data points API, wait a few seconds and try again.

Search consistency​

Data model time series replicate to the asset-centric data model time series API. If the search index isn't updated, the search, filter, aggregate, and list metadata endpoints may return outdated results. If this happens, wait a short time and try again.

Sist oppdatert