> ## 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.

# Relationships

> Create and manage relationships between resources in Cognite Data Fusion (CDF).

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](/api-reference/concepts/20230101/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.

<Note>
  These labels are informational only, and they're case-sensitive, for example, `flowsTo` and `FlowsTo` aren't the same.
</Note>

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](/api-reference/concepts/20230101/labels). 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](/api-reference/concepts/20230101/labels).

<AccordionGroup>
  <Accordion title="Example: create a relationship between assets">
    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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"
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Example: 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`.

    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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"
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Example: create a time-ranged relationship">
    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.

    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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"
            }
          ]
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## 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.

<AccordionGroup>
  <Accordion title="Example: list relationships for an asset">
    Where the asset is the source:

    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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:

    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    POST /api/v1/projects/publicdata/relationships/list
    Host: api.cognitedata.com
    Authorization: Bearer <token>
    Content-Type: application/json

    {
      "filter": {
        "targetTypes": ["asset"],
        "targetExternalIds": ["asset_1"]
      }
    }
    ```
  </Accordion>

  <Accordion title="Example: list relationships of a particular type">
    To retrieve all `flowsTo` relationships of `asset_1`:

    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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"}]}
      }
    }
    ```
  </Accordion>

  <Accordion title="Example: list relationships 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:

    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    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"}]}
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Delete a relationship

<AccordionGroup>
  <Accordion title="Example: delete a relationship">
    ```http wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    POST /api/v1/projects/publicdata/relationships/delete
    Host: api.cognitedata.com
    Authorization: Bearer <token>
    Content-Type: application/json

    {
      "items": [{"externalId": "relationship_1"}]
    }
    ```
  </Accordion>
</AccordionGroup>