Assets

In Cognite Data Fusion, the asset resource type stores digital representations of objects or groups of objects from the physical world. Examples assets are water pumps, heart rate monitors, machine rooms, and a production lines.

In this article:

About assets

Assets connect related data from different sources, and are core to identifying all the data that is relevant to an entity (contextualization) in Cognite Data Fusion.

All other resource types, for example time series, events and files, should be connected to at least one asset, and each asset can be connected to many resources and resource types. A pump asset can for example be connected to a time series that measures the pressure within the pump, to events that record maintenance operations, and to a file with a diagram of the pump.

Assets themselves are organized into asset hierarchies. For example, one asset can represent a water pump that is part of a larger subsystem asset on an oil platform asset.

At the top of each asset hierarchy is a root asset (for example an oil platform). Each project can have multiple root assets, and all assets under the root asset must have a name and a parent asset. Assets that share the same parent, can not have the same name.

TIP

See the assets API documentation for more information about how to work with assets.

Structure an asset hierarchy

This example shows you how to structure the asset hierarchy for the fictional SYSTEM 11:

SYSTEM 11
└───Pump A
│   └───Heating cable
└───Pump B
1
2
3
4

Outlined in csv format, the system looks like this:

name description refId parentRefId
SYSTEM 11 Sea water system SYSTEM_11
Pump A Main pump for system 11 PUMP_A SYSTEM_11
Heating cable Heating cable for pump A HEATING_CABLE PUMP_A
Pump B Backup pump for system 11 PUMP_B SYSTEM_11

When you structure an asset hierarchy, you can post all assets in one request. You can also give every asset a referable ID (refId) that Cognite Data Fusion will create as hard links when the request is posted.

  1. Post the following request:

    POST /api/0.5/projects/<project>/assets
    Host: api.cognitedata.com
    
    1
    2

    With this request body:

    {
      "items": [
        {
          "name": "SYSTEM 11",
          "description": "Sea water system",
          "refId": "SYSTEM_11"
        },
        {
          "name": "Pump A",
          "description": "Main pump for system 11",
          "refId": "PUMP_A",
          "parentRefId": "SYSTEM_11" // this refers to the object with refId = SYSTEM_11 as its parent,
        },
        {
          "name": "Pump B",
          "description": "Backup pump for system 11",
          "parentRefId": "SYSTEM_11"
        },
        {
          "name": "Heating cable",
          "description": "Heating cable for pump A",
          "parentRefId": "PUMP_A"
        }
      ]
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25

    The response body will look similar to this:

    {
      "data": {
        "items": [
          {
            "id": 229468419218757,
            "path": [229468419218757],
            "depth": 0,
            "name": "SYSTEM 11",
            "description": "Sea water system",
            "createdTime": 1541161763250,
            "lastUpdatedTime": 1541161763250
          },
          {
            "id": 4652973256993338,
            "path": [229468419218757, 4652973256993338],
            "depth": 1,
            "name": "Pump A",
            "parentId": 229468419218757,
            "description": "Main pump for system 11",
            "createdTime": 1541161763250,
            "lastUpdatedTime": 1541161763250
          },
          {
            "id": 1184192428522618,
            "path": [229468419218757, 4652973256993338, 1184192428522618],
            "depth": 2,
            "name": "Heating cable",
            "parentId": 4652973256993338,
            "description": "Heating cable for pump A",
            "createdTime": 1541161763250,
            "lastUpdatedTime": 1541161763250
          },
          {
            "id": 8652613591094498,
            "path": [229468419218757, 8652613591094498],
            "depth": 1,
            "name": "Pump B",
            "parentId": 229468419218757,
            "description": "Backup pump for system 11",
            "createdTime": 1541161763250,
            "lastUpdatedTime": 1541161763250
          }
        ]
      }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45

All refId and parentRefId identifiers have been replaced with corresponding id and parentId fields and values, and all references are using the new and unique identifiers. Also, you have a new path field that gives you the full path to an asset, including the asset itself.

Explore an asset hierarchy with the depth query parameter

  1. To get all assets on the root level and their children, set the depth query parameter to depth=1:

    GET /api/0.5/projects/<project>/assets?depth=1
    Host: api.cognitedata.com
    
    1
    2

    The response will look similar to this:

    {
      "data": {
        "items": [
          {
            "id": 4652973256993338,
            "path": [229468419218757, 4652973256993338],
            "depth": 1,
            "name": "Pump A",
            "parentId": 229468419218757,
            "description": "Main pump for system 11",
            "createdTime": 1541161763250,
            "lastUpdatedTime": 1541161763250
          },
          {
            "id": 8652613591094498,
            "path": [229468419218757, 8652613591094498],
            "depth": 1,
            "name": "Pump B",
            "parentId": 229468419218757,
            "description": "Backup pump for system 11",
            "createdTime": 1541161763250,
            "lastUpdatedTime": 1541161763250
          },
          {
            "id": 229468419218757,
            "path": [229468419218757],
            "depth": 0,
            "name": "SYSTEM 11",
            "description": "Sea water system",
            "createdTime": 1541161763250,
            "lastUpdatedTime": 1541161763250
          }
        ]
      }
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
Last Updated: 4/12/2019, 10:53:12 AM