Assets - Cognite Docs

Legacy data modeling

Deprecated: Asset-centric APIs and workflows are deprecated. Upgrade your data and applications to data modeling with the migration plugin.See Deprecated and retired features for dates, and Data modeling status for CDF projects for how DATA_MODELING_ONLY and HYBRID projects behave.

This resource is part of the asset-centric data model (legacy).

New projects: Model assets using the data modeling service—with the CogniteAsset concept, asset hierarchies, and greater flexibility.

Assets represent digital representations of objects or groups of objects from the physical world, such as water pumps, motors, machine rooms, or entire plants. Assets connect related data from different sources and are core to identifying all the data relevant to an entity (contextualization) in CDF. You can connect each asset to many resources and resource types. For example, you can connect a pump asset to time series that measure pressure, to events that record maintenance operations, and to files with pump diagrams. Assets are organized in hierarchies. For example, a Pump asset can be part of a System asset, which is part of a Plant asset. An asset can have a parent asset and multiple child assets, but an asset can only have one parent. At the top of each hierarchy is a root asset. Each project can have several root assets, and all assets under the root asset must have a parent asset.

Structure an asset hierarchy

This example shows you how to structure the asset hierarchy for the fictional SYSTEM 11:

SYSTEM 11
└───Pump
│   └───Heating cable
└───Pump

Outlined in CSV format, the system looks like this:

name	description	externalId	parentExternalId
SYSTEM 11	Sea water system	SYSTEM_11
Pump	Main pump for system 11	PUMP_A	SYSTEM_11
Heating cable	Heating cable for pump A	HEATING_CABLE	PUMP_A
Pump	Backup pump for system 11	PUMP_B	SYSTEM_11

You can post all assets in one request when you structure an asset hierarchy.

Example: create an asset hierarchy

POST /api/v1/projects/<project>/assets
Host: api.cognitedata.com

Request body:

{
  "items": [
    {
      "name": "SYSTEM 11",
      "description": "Sea water system",
      "externalId": "SYSTEM_11"
    },
    {
      "name": "Pump",
      "description": "Main pump for system 11",
      "externalId": "PUMP_A",
      "parentExternalId": "SYSTEM_11"
    },
    {
      "name": "Pump",
      "externalId": "Pump_B",
      "description": "Backup pump for system 11",
      "parentExternalId": "SYSTEM_11"
    },
    {
      "name": "Heating cable",
      "externalId": "HEATING_CABLE",
      "description": "Heating cable for pump A",
      "parentExternalId": "PUMP_A"
    }
  ]
}

The response body will look similar to this:

{
  "items": [
    {
      "externalId": "SYSTEM_11",
      "name": "SYSTEM 11",
      "description": "Sea water system",
      "metadata": {},
      "id": 4181031623333192,
      "createdTime": 1562764416913,
      "lastUpdatedTime": 1562764416913,
      "rootId": 4181031623333192
    },
    {
      "externalId": "PUMP_A",
      "name": "Pump",
      "parentId": 4181031623333192,
      "description": "Main pump for system 11",
      "metadata": {},
      "id": 2975365566518130,
      "createdTime": 1562764416913,
      "lastUpdatedTime": 1562764416913,
      "rootId": 4181031623333192
    },
    {
      "externalId": "Pump_B",
      "name": "Pump",
      "parentId": 4181031623333192,
      "description": "Backup pump for system 11",
      "metadata": {},
      "id": 1366019363753734,
      "createdTime": 1562764416913,
      "lastUpdatedTime": 1562764416913,
      "rootId": 4181031623333192
    },
    {
      "externalId": "HEATING_CABLE",
      "name": "Heating cable",
      "parentId": 2975365566518130,
      "description": "Heating cable for pump A",
      "metadata": {},
      "id": 3816457134628307,
      "createdTime": 1562764416913,
      "lastUpdatedTime": 1562764416913,
      "rootId": 4181031623333192
    }
  ]
}

In addition to externalId, you get a unique id field and value. References within CDF use that id, so parentExternalId is translated into that new unique identifier. The rootId field gives you the id of the root asset.

Advanced filtering

advancedFilter combines leaf operations such as equals, prefix, and exists with and, or, and not. It applies to built-in fields and to metadata. The filter language is documented in Filter language. List, search, and aggregate endpoints that use this filter are for exploration. See Request throttling.

Filter limits

An asset advancedFilter query has these limits:

Maximum depth is 10, and the maximum number of clauses is 100.
and and or need at least one element.
Each property array has 1 or 2 elements. Each element is at most 128 characters and must name an existing property or metadata key.
containsAll, containsAny, and in accept 1 to 100 primitive values.
A range filter needs at least one bound. gt and gte cannot be used together, and neither can lt and lte.
A query can contain at most 2 search leaf filters. Each search value is 1 to 128 characters.
Maximum string lengths: externalId 255, name 128 for search and 255 otherwise, description 128 for search and 255 otherwise, a label 255, source 128, and a metadata key 128.

Sorting

When nulls is auto or omitted, missing values sort after every other value in ascending order and before every other value in descending order. Set nulls to first or last to place missing values independently of the sort direction. Empty strings are not nulls. Sort on _score_ to rank assets by how many filter clauses they match. An asset that matches both an equals filter and a prefix filter ranks above an asset that matches only the prefix.

Aggregates

Aggregate computes counts and grouped values over assets. filter and advancedFilter select the assets to aggregate, using the same rules as list. Text values are grouped without regard to case. aggregateFilter filters the aggregate buckets, not the assets. For an aggregation on source, it can only filter the source values.

Delete assets

By default, recursive is false and the delete fails when another asset uses the target as its parent. Set recursive to true to delete the asset and its descendants. Descendants do not count toward the request limit.

Rate and concurrency limits

For Assets rate and concurrency limits, see API rate limits.

​Structure an asset hierarchy

​Advanced filtering

​Filter limits

​Sorting

​Aggregates

​Delete assets

​Rate and concurrency limits

Structure an asset hierarchy

Advanced filtering

Filter limits

Sorting

Aggregates

Delete assets

Rate and concurrency limits