Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cognite.com/llms.txt

Use this file to discover all available pages before exploring further.

The Relationships resource type represents connections between resource objects in CDF. Each relationship is between a source and a target object and is defined by a relationship type and the external IDs and resource types of the source and target objects. Optionally, a relationship can be time-constrained with a start and end time. The externalId field uniquely identifies each relationship. To define and manage the available relationship types, use the labels resource type. For example, you can define and use the following labels as relationship types:
  • flowsTo - to describe the flow between assets.
  • belongsTo - to describe that a file resource belongs to a particular asset resource.
  • isParentOf - to build a hierarchy of assets.
  • implements - to describe that a physical item implements a functional asset at a specific point in time.
These labels are informational only, and they’re case-sensitive, for example, flowsTo and FlowsTo aren’t the same.
Typically, asset resources originate from a maintenance system, and the hierarchical structure of the maintenance system often defines how the asset resources are organized in CDF. The relationships resource type lets you organize the assets in other structures in addition to the standard hierarchical asset structure. For example, you can organize assets by their physical location, where the grouping nodes in the hierarchy are buildings and floors rather than systems and functions. Another example is to build a graph structure that lets you navigate assets by mimicking their physical connections through wires or pipes. Before you create a relationship, make sure that the relationship type exists as a label. When you create a relationship, you must specify its type using the externalId of the relevant label. It’s good practice to add relationships to a data set for grouping and governance. It’s not a requirement that the source or target resource exist when you create a relationship. This lets you create relationships between objects that don’t yet exist in CDF.

​
Create a relationship between two assets

To create a relationship, give it an ID and a type and specify the source and target resource objects the relationship connects. The relationship ID must be an externalId. The relationship type must be the externalId of a label. 
POST /api/v1/projects/publicdata/relationships
Host: api.cognitedata.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "items": [
    {
      "externalId": "relationship_1",
      "dataSetId": 5514071318856557,
      "sourceExternalId": "asset_1",
      "sourceType": "asset",
      "targetExternalId": "asset_2",
      "targetType": "asset",
      "labels": [
        {
          "externalId": "flowsTo"
        }
      ]
    }
  ]
}
You can use relationships to create links between any resources by specifying the sourceType and targetType.
POST /api/v1/projects/publicdata/relationships
Host: api.cognitedata.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "items": [
    {
      "externalId": "relationship_2",
      "dataSetId": 5514071318856557,
      "sourceExternalId": "file_1",
      "sourceType": "file",
      "targetExternalId": "asset_1",
      "targetType": "asset",
      "labels": [
        {
          "externalId": "belongsTo"
        }
      ]
    }
  ]
}
When you have physical equipment as part of the asset resources, you can use relationships to capture how physical equipment serves at different functional locations over time. Specify the timespan a relationship is valid for by using the startTime and endTime properties.
POST /api/v1/projects/publicdata/relationships
Host: api.cognitedata.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "items": [
    {
      "externalId": "relationship_3",
      "dataSetId": 5514071318856557,
      "sourceExternalId": "asset_1",
      "sourceType": "asset",
      "targetExternalId": "asset_2",
      "targetType": "asset",
      "startTime": 1514768406,
      "endTime": 1577840406,
      "labels": [
        {
          "externalId": "flowsTo"
        }
      ]
    }
  ]
}

​
List relationships

Relationships are directional, so to find all relationships for a particular asset, you need to query where the asset is both the source and the target.
Where the asset is the source:
POST /api/v1/projects/publicdata/relationships/list
Host: api.cognitedata.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "filter": {
    "sourceTypes": ["asset"],
    "sourceExternalIds": ["asset_1"]
  }
}
Where the asset is the target:
POST /api/v1/projects/publicdata/relationships/list
Host: api.cognitedata.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "filter": {
    "targetTypes": ["asset"],
    "targetExternalIds": ["asset_1"]
  }
}
To retrieve all flowsTo relationships of asset_1:
POST /api/v1/projects/publicdata/relationships/list
Host: api.cognitedata.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "filter": {
    "sourceTypes": ["asset"],
    "sourceExternalIds": ["asset_1"],
    "labels": {"containsAll": [{"externalId": "flowsTo"}]}
  }
}
To list all time-ranged relationships of an asset with type implements and valid at a specific point in time:
POST /api/v1/projects/publicdata/relationships/list
Host: api.cognitedata.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "filter": {
    "sourceTypes": ["asset"],
    "sourceExternalIds": ["asset_1"],
    "activeAtTime": {
      "min": 1601284751,
      "max": 1601284751
    },
    "labels": {"containsAll": [{"externalId": "implements"}]}
  }
}

​
Delete a relationship

POST /api/v1/projects/publicdata/relationships/delete
Host: api.cognitedata.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "items": [{"externalId": "relationship_1"}]
}
Last modified on April 23, 2026