Cognite
The Cognite connection connects to a Cognite Data Fusion (CDF) project. It reads assets and time series from CDF data models, and writes Intelligence Hub models and instances to CDF as time series, views, and assets.
Connection Settings
The connection authenticates with the OAuth 2.0 client credentials flow.
| Setting | Description |
|---|---|
| Base URL | The base URL of the CDF cluster (ex. https://api.cognitedata.com or https://westeurope-1.cognitedata.com). |
| Project | The CDF project to connect to. |
| Token URL | The OAuth 2.0 token endpoint of the identity provider used to authenticate with CDF. For Microsoft Entra ID this is https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token. The token is requested with the scope <Base URL>/.default (ex. https://api.cognitedata.com/.default). |
| Client ID | The OAuth 2.0 client ID of the application registered with the identity provider. |
| Client Secret | The OAuth 2.0 client secret of the application registered with the identity provider. |
Inputs
Inputs read time series or assets. Both input types read back the latest value, and can optionally include metadata
Read Type: Time Series
Reads the latest value of one or more time series. The result is an object keyed by the time series external ID.
| Setting | Description |
|---|---|
| Instance Space | The space that holds the time series. |
| Time Series | The external IDs of the time series to read. |
| Include Metadata | When enabled, each time series is returned as an object with its value under value and its metadata under _metadata. |
{
"Pump_1_pressure": 41.7,
"Pump_1_motor_speed": 1785
}
A time series that does not exist in the space is returned with bad quality. A time series that exists but has no datapoints is returned as good with no data.
When Include Metadata is enabled, each time series is returned with the properties of its CogniteTimeSeries node (ex. name, description, unit, type) under _metadata. Time series created by the Intelligence Hub also include their extractedData.
{
"Pump_1_pressure": {
"value": 41.7,
"_metadata": {
"name": "Pump_1_pressure",
"description": "Discharge pressure",
"type": "numeric",
"isStep": false,
"extractedData": {
"location": "Line 1"
}
}
}
}
Read Type: Assets
Reads assets through a view. The result contains the properties of the view. Properties that are relations to time series are replaced with the latest value of the time series, and all other properties are returned as is.
| Setting | Description |
|---|---|
| Instance Space | The space that holds the assets. |
| External ID | The external ID of the asset to read. Leave blank to read every asset in the space that has data in the view, up to 1000. A single asset is returned as an object, and multiple assets as an array of objects. If the asset is not found or has no data in the view, the read fails. |
| View | The external ID of the view to read the assets through. |
| View Space | The space that holds the view. Defaults to the Instance Space when left blank. |
| View Version | The version of the view. Defaults to the latest version when left blank. |
| Include Metadata | When enabled, each asset is returned as an object with its value under value and its metadata under _metadata. |
Below is an example read of an asset written by the Asset output.
{
"_name": "Pump_1",
"_model": "Pump",
"pressure": 41.7,
"motor_speed": 1785
}
When Include Metadata is enabled, the asset’s space and external ID are returned under _metadata, along with its parent’s space and external ID when it has a parent.
{
"value": {
"_name": "Pump_1",
"_model": "Pump",
"pressure": 41.7,
"motor_speed": 1785
},
"_metadata": {
"space": "plant_instances",
"externalId": "Pump_1",
"parentSpace": "plant_instances",
"parentExternalId": "Line_1"
}
}
Outputs
Outputs write to time series, write metadata to existing time series, or write models and instances as views and assets linked to their time series. Time series, views, and assets can optionally be created when they don’t exist.
Write Type
Specifies the type of write. The different types are described below.
| Write Type | Description |
|---|---|
| Time Series | Writes each attribute of the payload to a time series, and optionally creates the time series. |
| Asset | Writes each attribute of the payload to a time series, and optionally creates the view for the model and an asset for each instance, linked to its time series. |
| Time Series Metadata | Writes metadata (ex. description, unit) to existing time series. |
Write Type: Time Series
Time Series writes flatten the payload and write each attribute to a time series. The time series external ID is the instance name (_name) followed by the attribute path, joined by the Delimiter. If the payload has no _name, the external ID is only the attribute path. No views or assets are created.
| Setting | Description |
|---|---|
| Create Option | When set to Off, datapoints are written to existing time series by external ID and nothing is created. When set to Create, the instance space and any missing time series are created. Existing time series are never changed. |
| Instance Space | The space that holds the time series. |
| Delimiter | The delimiter used to join the instance name and attribute names into time series external IDs. Defaults to an underscore (_). |
As an example, the following payload writes to the time series Pump_1_pressure and Pump_1_motor_speed.
{
"_name": "Pump_1",
"_model": "Pump",
"pressure": 41.7,
"motor": {
"speed": 1785
}
}
Write Type: Time Series Metadata
Writes metadata to existing time series. Metadata can only be written to time series that already exist in the space. If one of the time series is not found, the write fails.
| Setting | Description |
|---|---|
| Instance Space | The space that holds the time series. |
The payload must be an object keyed by time series external ID, where each value is an object of the metadata to write. Keys that match a CogniteTimeSeries property set that property. These include name, description, isStep, unit, sourceUnit, sourceId, tags, and aliases. The unit is the external ID of a unit in the CDF unit catalog (ex. pressure:bar). All other keys are written to the time series’ extractedData, replacing what it had. Only the properties in the payload are changed.
{
"Pump_1_pressure": {
"description": "Discharge pressure",
"unit": "pressure:bar",
"location": "Line 1"
},
"Pump_1_motor_speed": {
"description": "Motor speed",
"sourceUnit": "rpm"
}
}
In the example above, location is written to extractedData.
Write Type: Asset
Asset writes first write each attribute to a time series, the same as Time Series writes, and then convert Intelligence Hub models and instances into CDF views and assets. The model becomes a view with a time series relation per attribute, and each instance becomes an asset whose relations point to its time series. See How Asset Writes Work below for details.
| Setting | Description |
|---|---|
| Create Option | When set to Off, datapoints are written to existing time series by external ID and nothing is created. When set to Create, missing spaces, the container and view, assets, and time series are created, and new model attributes are added to the container, view, and existing assets. |
| Schema Space | The space that holds the container and view generated for each model. Only used when Create Option is set to Create. |
| Instance Space | The space that holds the time series and assets. This can be the same as the Schema Space. |
| Asset Name | The name of the asset. Used as the asset external ID, and as the prefix of its time series external IDs. When left blank the instance name (_name) in the payload is used. The write fails if neither is set. |
| View Version | The version of the view created for the model. Defaults to 1 when left blank. Only used when Create Option is set to Create. |
| Parent Space | The space of the parent asset. Defaults to the Instance Space when left blank. Only used when Create Option is set to Create. |
| Parent ID | The external ID of the parent asset. When set, it prefixes the external IDs of the written assets and their time series (ex. Line_1_Pump_1). The parent is only set when the asset is created. Leave blank to write assets without a parent. |
| Delimiter | The delimiter used to join the parent ID, asset name, and attribute names into asset and time series external IDs. Defaults to an underscore (_). |
Below is an example Asset write. This payload could come from a raw input or be generated by the models and instances configured in the Intelligence Hub.
{
"_name": "Pump_1",
"_model": "Pump",
"pressure": 41.7,
"motor": {
"speed": 1785
}
}
With Create Option set to Create, Schema Space set to plant_schema, Instance Space set to plant_instances, Parent ID set to Line_1, and the default Delimiter, the following happens.
- The datapoints are written to the time series
Line_1_Pump_1_pressureandLine_1_Pump_1_motor_speedinplant_instances. The spaces and any missing time series are created first. - The container and view
Pump(version1) are looked up inplant_schema. If they don’t exist they are created, with a time series relation for each attribute,pressureandmotor_speed. If they exist but are missing attributes, the new attributes are added. Container and view property names always use an underscore, regardless of the Delimiter, because of CDF’s property naming rules. - The asset
Line_1_Pump_1is looked up inplant_instances. If it doesn’t exist it’s created with the namePump_1, the parentLine_1, and relations to its time series. Each time series is also linked back to the asset, so it appears on the asset in CDF. If the asset exists but is missing attributes, the new relations are added.
With Create Option set to Off, only step 1 is performed, and the write fails if the time series do not exist.
The model name (_model) of the first instance in the payload is used as the container and view external ID. The write fails if the payload has no model name and Create Option is set to Create.
All changes to containers, views, and assets are additive. Existing properties are never removed, renamed, or retyped.
Data Types and Timestamps
The Asset and Time Series writes support the following data types.
| Data Type | Written As |
|---|---|
| Numbers | Numeric time series. Values are written as doubles. |
| Boolean | Numeric step time series. Values are written as 1 (true) or 0 (false). |
| String | String time series. |
Arrays, date times, files, and null values are skipped. The time series type is set from the first value written when the time series is created, and Boolean and string time series are created as step time series. Created time series are named after their external ID.
The timestamp of each datapoint is the timestamp of the value. When the value has no timestamp, the time of the write is used. Arrays of objects are supported, and each object in the array is written as its own set of datapoints.