Skip to main content

Units

Units are a set of standardized units that can be assigned to Time Series and Data Models to identify the units of measure associated with the values stored in these resources. It facilitates consistency and comprehensiveness in data handling and helps to ensure data uniformity and interoperability when consuming data stored in Cognite Data Fusion.

Concepts in Unit Management

With the addition of units in Cognite Data Fusion, we're rolling out some new concepts:

  1. Quantity: A specific, measurable property or characteristic of a physical system or substance. Examples include:
    • Temperature
    • Pressure
    • Mass
    • Length
  2. Unit: A standard amount or value of a particular quantity by which other amounts of the same quantity can be measured or expressed. Examples include:
    • Temperature: degrees Celsius, degrees Fahrenheit
    • Pressure: bar, psi
  3. Unit System: A collection of default units for given quantities. Examples include:
    • SI: Temperature in Kelvin, Pressure in Pa
    • Imperial: Temperature in degrees Fahrenheit, Pressure in psi

About units

Cognite curates a list standard industry relevant units that is made available on every Cognite Data Fusion project. In the future it will be possible to extend the units per project with custom units.

Each unit in contains the following attributes:

  • externalId: A unique identifier structured as {quantity}:{unit} (e.g., temperature:deg_c), following the snake_case convention.
  • name: The primary name of the unit, such as DEG_C.
  • longName: A descriptive name for the unit, like degree Celsius.
  • symbol: The symbol representing the unit, for example, °C.
  • aliasNames: An array of alternative names or aliases for the unit.
  • quantity: The physical quantity measured by the unit (e.g., Temperature).
  • conversion: An object containing conversion factors (multiplier and offset) for unit conversion.
  • source: The primary source of the unit's definition, typically a standard organization like qudt.org.
  • sourceReference: A URL reference to the external source for the unit's definition.
tip

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

Unit management in Time Series

Time Series contain a free text unit field that has been used to store a reference to the unit as specified in the source system where the data has been read from. With the addition of the unit catalog in Cognite Data Fusion, a new field has been added to Time Series called unitExternalId.

The unitExternalId field can be assigned to any unit available in the unit catalog. The assignment can be done on Time Series creation or update. See below an example for the creation of Time Series with the new unitExternalId field in the Python SDK:

client.time_series.create(
time_series = [
TimeSeries(
external_id="test_unit_ts_1",
name="Temperature Sensor 1",
unit="deg C",
unit_external_id="temperature:deg_c",
description="Temperature measured in degrees Celsius"
),
TimeSeries(
external_id="test_unit_ts_2",
name="Temperature Sensor 2",
unit="F",
unit_external_id="temperature:deg_f",
description="Temperature measured in degrees Fahrenheit"
)
]
)

Once time series are created (or updated) with units from the catalog, it’s possible to filter both on unitExternalId but also on unitQuantity. See below some examples of valid Time Series queries in the Python SDK:

# list time series that are assigned to degrees Fahrenheit
client.time_series.list(
unit_external_id="temperature:deg_f"
)

# list time series that are assigned to units of quantity Temperature
client.time_series.list(
unit_quantity="Temperature"
)

The aggregate endpoints also support unitExternalId and unitQuantity, so it’s easy to get counts of the Time Series according to units and quantities. See below some examples of valid Time Series aggregations in the Python SDK:

# get the number of unique unitExternalIds associated with TimeSeries
client.time_series.aggregate_cardinality_values(
property="unitExternalId"
)

# get the number of unique unitQuantities associated with TimeSeries
client.time_series.aggregate_cardinality_values(
property="unitQuantity"
)

# get the count per unitExternalIds associated with TimeSeries
client.time_series.aggregate_unique_values(
property="unitExternalId"
)

# get the count per unitQuantities associated with TimeSeries
client.time_series.aggregate_unique_values(
property="unitQuantity"
)

For time series that have associated units from the catalog, it’s possible to query data points in a compatible unit (units from the same quantity). See below an example of data points queries with unit conversion in the Python SDK:

client.time_series.data.retrieve(
external_id=[
{
"external_id": "test_unit_ts_1",
"target_unit": "temperature:deg_c"
},
{
"external_id": "test_unit_ts_3",
"target_unit": "length:m"
}
],
start="2w-ago",
end="now"
)

It’s also possible to specify a target unit system instead of specific units. In this case the API will target the default unit specified for the given unit system. See below an example of data points queries with unit conversion to a unit system in the Python SDK:

client.time_series.data.retrieve(
external_id=["test_unit_ts_1", "test_unit_ts_3"],
target_unit_system="SI",
start="2w-ago",
end="now"
)