Unit Catalog

Units

List Units

UnitAPI.list() → UnitList

List all supported units

Returns

List of units

Return type

UnitList

Examples

List all supported units in CDF:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.units.list()

Retrieve Unit

UnitAPI.retrieve(external_id: str, ignore_unknown_ids: bool = False) → None | cognite.client.data_classes.units.Unit
UnitAPI.retrieve(external_id: SequenceNotStr[str], ignore_unknown_ids: bool = False) → UnitList

Retrieve one or more unit

Parameters

  • external_id (str | SequenceNotStr[str]) – External ID or list of external IDs

  • ignore_unknown_ids (bool) – Ignore external IDs that are not found rather than throw an exception.

Returns

If a single external ID is specified: the requested unit, or None if it does not exist. If several external IDs are specified: the requested units.

Return type

Unit | UnitList | None

Examples

Retrive unit ‘temperature:deg_c’:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.units.retrieve('temperature:deg_c')

Retrive units ‘temperature:deg_c’ and ‘pressure:bar’:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.units.retrieve(['temperature:deg_c', 'pressure:bar'])

Look up Unit from alias

UnitAPI.from_alias(alias: str, quantity: str | None, return_ambiguous: Literal[False], return_closest_matches: Literal[False]) → Unit
UnitAPI.from_alias(alias: str, quantity: str | None, return_ambiguous: bool, return_closest_matches: bool) → cognite.client.data_classes.units.Unit | cognite.client.data_classes.units.UnitList

Look up a unit by alias, optionally for a given quantity. Aliases and quantities are case-sensitive.

Note

When just alias is given (i.e. quantity is not specified), some aliases are ambiguous as they are used by several quantities, e.g. ‘F’ which can be both Farad (Capacitance) and Fahrenheit (Temperature). These raise a ValueError by default unless also return_ambiguous=True is passed, in which case all matching units are returned.

Tip

You can use return_closest_matches=True to get the closest matching units if the lookup fails. Note that there may not be any close matches, in which case an empty UnitList is returned.

Parameters

  • alias (str) – Alias of the unit, like ‘cmol / L’ or ‘meter per second’.

  • quantity (str | None) – Quantity of the unit, like ‘Temperature’ or ‘Pressure’.

  • return_ambiguous (bool) – If False (default), when the alias is ambiguous (i.e. no quantity was given), raise a ValueError. If True, return the list of all matching units.

  • return_closest_matches (bool) – If False (default), when the lookup fails, raise a ValueError (default). If True, return the closest matching units (even if empty).

Returns

The unit if found, else a ValueError is raised. If one or both of return_ambiguous and return_closest_matches is passed as True, a UnitList may be returned.

Return type

Unit | UnitList

Examples

Look up a unit by alias only:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> unit = client.units.from_alias('cmol / L')

Look up ambiguous alias ‘F’ by passing quantity ‘Temperature’:

>>> unit = client.units.from_alias('F', 'Temperature')

Search for the closest matching unit of ‘kilo watt’ (should be ‘kilowatt’):

>>> unit_matches = client.units.from_alias("kilo watt", return_closest_matches=True)

Unit Systems

List Unit System

UnitSystemAPI.list() → UnitSystemList

List all supported unit systems

Returns

List of unit systems

Return type

UnitSystemList

Examples

List all supported unit systems in CDF:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.units.systems.list()

Unit data classes

class cognite.client.data_classes.units.Unit(external_id: str, name: str, long_name: str, symbol: str, alias_names: list[str], quantity: str, conversion: UnitConversion, source: Optional[str] = None, source_reference: Optional[str] = None)

Bases: CogniteResource

This class represents a Unit in CDF.

Parameters

  • external_id (str) – A unique identifier of the unit.

  • name (str) – The name of the unit, e.g. DEG_C for Celsius.

  • long_name (str) – A more descriptive name of the unit, e.g., degrees Celsius.

  • symbol (str) – The symbol of the unit, e.g., °C.

  • alias_names (list[str]) – List of alias names for the unit, e.g., Degree C, degC, °C, and so on.

  • quantity (str) – The quantity of the unit, e.g., temperature.

  • conversion (UnitConversion) – The conversion between the unit and its base unit. For example, the base unit for temperature is Kelvin, and the conversion from Celsius to Kelvin is multiplier = 1, offset = 273.15.

  • source (str | None) – The source of the unit, e.g., qudt.org

  • source_reference (str | None) – The reference to the source of the unit, e.g., http://qudt.org/vocab/unit/DEG_C

as_unit_id() → UnitID

Returns the UnitID of this unit.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.units.UnitConversion(multiplier: float, offset: float)

Bases: object

The conversion between a unit and its base unit.

Parameters

  • multiplier (float) – The multiplier to convert from the unit to the base unit.

  • offset (float) – The offset to convert from the unit to the base unit.

class cognite.client.data_classes.units.UnitID(unit_external_id: str, name: str)

Bases: CogniteResource

Unit Identifier

Parameters

  • unit_external_id (str) – External ID of the unit.

  • name (str) – Name of the unit.

class cognite.client.data_classes.units.UnitList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[Unit], ExternalIDTransformerMixin

List of Units

class cognite.client.data_classes.units.UnitSystem(name: str, quantities: list[cognite.client.data_classes.units.UnitID])

Bases: CogniteResource

This class represents a Unit System in CDF.

Parameters

  • name (str) – The name of the unit system, e.g., SI and Imperial.

  • quantities (list[UnitID]) – The quantities of the unit system, e.g., length, mass, and so on.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

camel_case (bool) – Use camelCase for attribute names. Defaults to True.

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

class cognite.client.data_classes.units.UnitSystemList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[UnitSystem], NameTransformerMixin

List of Unit Systems