Labels - Cognite Docs

With labels you can create a predefined set of managed terms that you can use to annotate and group assets, files, and relationships. You can organize labels in a way that makes sense in your business and use them to make it easier to find what you want. For example, you can create a label called pump and apply it to all asset resources that represent pumps, and then filter assets to see only pumps. You can also use labels to define and manage the available types for relationship resources. 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.

Each asset/file can have up to ten labels connected to it. You can filter assets/files by their labels to find a group of assets/files.

Create a label

To create a label, give it an ID and a name. The label ID must be an externalId.

Example: create labels

POST /api/v1/projects/publicdata/labels
Content-Type: application/json

{
  "items": [
    {
      "externalId": "rotating-equipment",
      "name": "Rotating equipment",
      "description": "Pumps, compressors, turbines"
    },
    {
      "externalId": "PUMP",
      "name": "Pump",
      "description": "Pumps"
    }
  ]
}

Attach a label when creating a resource

To attach a label when you create a resource, reference the labels through the externalId of the label.

Example: create an asset with labels

POST /api/v1/projects/publicdata/assets
Content-Type: application/json

{
  "items": [
    {
      "externalId": "MY_PUMP_ASSET",
      "labels": [
        { "externalId": "PUMP" },
        { "externalId": "rotating-equipment" }
      ]
    }
  ]
}

You can attach a maximum of 10 labels to each resource.

Attach or remove labels on an existing resource

To attach or remove labels to an existing resource, reference the labels through the externalId of the label when you update the resource.

Example: attach and remove labels

POST /api/v1/projects/publicdata/assets/update
Content-Type: application/json

{
  "items": [
    {
      "update": {
        "labels": {
          "add": [ { "externalId": "PUMP" } ],
          "remove": [ { "externalId": "rotating-equipment" } ]
        }
      },
      "externalId": "MY_PUMP_ASSET"
    }
  ]
}

The API ignores the request if you try to attach a label that’s already attached to the resource.

Filter resources by labels

To filter assets by a label, reference the label through the externalId when you filter.

Example: filter assets by labels

To retrieve only assets that have the label rotating-equipment:

POST /api/v1/projects/publicdata/assets/list
Content-Type: application/json

{
  "filter": {
    "labels": {
      "containsAny": [{ "externalId": "rotating-equipment" }]
    }
  }
}

To retrieve only assets that have the label rotating-equipment or pump:

{
  "filter": {
    "labels": {
      "containsAny": [
        { "externalId": "rotating-equipment" },
        { "externalId": "PUMP" }
      ]
    }
  }
}

To retrieve only assets that have the labels rotating-equipment and pump:

{
  "filter": {
    "labels": {
      "containsAll": [
        { "externalId": "rotating-equipment" },
        { "externalId": "PUMP" }
      ]
    }
  }
}

Delete labels

To delete a label, specify the externalId of the label to delete.

Example: delete a label

POST /api/v1/projects/publicdata/labels/delete
Content-Type: application/json
{
  "items": [
    {
      "externalId": "rotating-equipment"
    }
  ]
}

​Create a label

​Attach a label when creating a resource

​Attach or remove labels on an existing resource

​Filter resources by labels

​Delete labels

Create a label

Attach a label when creating a resource

Attach or remove labels on an existing resource

Filter resources by labels

Delete labels