Labels

With labels you can create a predefined set of managed terms that you can use to annotate and group assets.

You can organize the labels in a way that makes sense in your business and use the labels 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.

In this article:

About labels

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

Typical use cases for labels include:

  • Categorize assets into equipment types.
  • Locate assets by equipment type.

TIP

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

Create a label

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

This example request creates a label:

POST /api/v1/projects/publicdata/labels
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "items": [
    {
      "externalId": "rotating-equipment",
      "name": "Rotating equipment",
      "description": "Pumps, compressors, turbines"
    },
    {
      "externalId": "PUMP",
      "name": "Pump",
      "description": "Pumps"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

List labels

To list existing labels, use:

POST /api/v1/projects/publicdata/labels/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "filter": {
    "name": "string",
    "externalIdPrefix": "string"
  },
  "limit": 10,
  "cursor": "ABC"
}
1
2
3
4
5
6
7
8
9
10
11
12
13

Attach a label when you create a resource

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

For example, to create a new asset resource and attach the labels pump and rotating-equipment, use this request:

POST /api/v1/projects/publicdata/assets
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "items": [
    {
      "externalId": "MY_PUMP_ASSET",
      "labels": [
        { "externalId": "PUMP" },
        { "externalId": "rotating-equipment" }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

Attach labels to an existing resource

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

For example, to attach the labels pump and rotating-equipment to an existing asset, use the request:

POST /api/v1/projects/publicdata/assets/update
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "items": [
    {
      "externalId": "MY_PUMP_ASSET",
      "labels": [
        { "externalId": "PUMP" },
        { "externalId": "rotating-equipment" }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Note: The API silently ignores the request if you try to attach a label that is already attached to the resource.

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

Remove labels from a resource

To remove labels from a resource, you reference the labels through the externalId of the label when you update the resource.

For example, to remove the label rotating-equipment from an asset, use the request:

POST /api/v1/projects/publicdata/assets/update
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
content-length: 999
{
  "items": [
    {
      "externalId": "MY_PUMP_ASSET",
      "update": {
        "labels": {
          "remove": [
            { "externalId": "rotating-equipment" }
          ]
        }
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

Note: The API silently ignores the request if you try to remove a label that is not attached to the resource.

Filter resources by labels

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

For example, to retrieve only assets that have the label rotating-equipment, use the request:

POST /api/v1/projects/publicdata/assets/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
 {
  "filter": {
    "labels": {
      "containsAny": [{ "externalId": "rotating-equipment" }]
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

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

POST /api/v1/projects/publicdata/assets/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
  "filter": {
    "labels": {
      "containsAny" : [
        { "externalId": "rotating-equipment" },
        { "externalId": "PUMP" }
      ]
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

POST /api/v1/projects/publicdata/assets/list
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
  "filter": {
    "labels": {
      "containsAll" : [
        { "externalId": "rotating-equipment" },
        { "externalId": "PUMP" }
      ]
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Delete labels

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

This example request deletes a rotating-equipment label:

POST /api/v1/projects/publicdata/labels/delete
Host: api.cognitedata.com
api-key: <key>
Content-Type: application/json
{
  "items": [
    {
      "externalId": "rotating-equipment"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
Last Updated: 6/29/2020, 3:55:18 PM