# Relationships beta

The Relationships resource type represents connections between resource objects in Cognite Data Fusion (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 labels like these and use them 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.

In this article:

# About relationships

Typically, asset resources originate from a maintenance system, and the hierarchical structure from the maintenance system often defines how the asset resources are organized in Cognite Data Fusion (CDF).

The relationships resource type allows you to organize the assets in other structures in addition to the standard hierarchical asset structure.

For example, you can choose to organize the 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 allows you to navigate assets by mimicking their physical connections through wires or pipes. See the Modeling asset structures with relationships for examples.

Before you create a 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.

When you create relationship, it is good practise to add them to a data set for grouping and governance.

It is not a requirement that the source or target resource exist when you create a relationship. This allow you to create relationships between objects that does not yet exist in CDF.

TIP

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

# Create a relationship between two assets

To create a relationship, you need to 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.

Relationships should be created within a data set for logical grouping and governance.

This example request creates a relationship:

POST /api/v1/projects/publicdata/relationships
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "items": [
    {
      "externalId": "relationship_1",
      "dataSetId": 5514071318856557,
      "sourceExternalId": "asset_1",
      "sourceType": "asset",
      "targetExternalId": "asset_2",
      "labels": [
        {
          "externalId": "flowsTo"
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# Create a relationship between a file and an asset

You can use relationships to create links between any resources by specifying the sourceType and targetType.

This example shows how to create a relationship of type belongsTo between a file and an asset resource.

POST /api/v1/projects/publicdata/relationships
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "items": [
    {
      "externalId": "relationship_2",
      "dataSetId": 5514071318856557,
      "sourceExternalId": "file_1",
      "sourceType": "file",
      "targetExternalId": "asset_1",
      "targetType": "asset",
      "labels": [
        {
          "externalId": "belongsTo"
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Create a time-ranged relationship between two assets

When you have physical equipment as part of the asset resources, you can use relationships to capture how a physical equipment serves at different functional locations over time. You can specify the timespan a relationships is valid for by specifying the startTime and endTime properties.

This example shows how to create a relationship between two assets with a time-range.

POST /api/v1/projects/publicdata/relationships
Host: api.cognitedata.com
api-key: <key>
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"
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# List relationships

To list existing relationships, use:

POST /api/v1/projects/publicdata/relationships/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{}
1
2
3
4
5
6

# List relationships for a particular asset

Relationships are directional. Therefore, we split this into two calls (one where the asset is the source, and one where the asset is the target).

POST /api/v1/projects/publicdata/relationships/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "filter": {
    "sourceTypes": ["asset"],
    "sourceExternalIds": ["asset_1"]
  }
}
1
2
3
4
5
6
7
8
9
10
11
POST /api/v1/projects/publicdata/relationships/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "filter": {
    "targetTypes": ["asset"],
    "targetExternalIds": ["asset_1"]
  }
}
1
2
3
4
5
6
7
8
9
10
11

# List relationships of a particular type for a particular asset

To retrieve all flowsTo relationships of asset_1.

POST /api/v1/projects/publicdata/relationships/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "filter": {
    "sourceTypes": ["asset"],
    "sourceExternalIds": ["asset_1"],
    "labels": {"containsAll": [{"externalId": "flowsTo"}]}
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

# List relationship for an asset at a specific point in time

To list all time-ranged relationships of an asset, with type implements, and valid at a specific point in time, use:

POST /api/v1/projects/publicdata/relationships/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "filter": {
    "sourceTypes": ["asset"],
    "sourceExternalIds": ["asset_1"],
    "activeAtTime": {
      "min": 1601284751,
      "max": 1601284751
    },
    "labels": {"containsAll": [{"externalId": "implements"}]}
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Delete a relationship

To delete a relationship, use:

POST /api/v1/projects/publicdata/relationships/delete
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "items": [{"externalId": "relationship_1"}]
}
1
2
3
4
5
6
7
8
Last Updated: 10/1/2020, 7:27:28 AM