Unit Catalog

Warning

Unit Catalog is a new feature:

  • The API specification is in beta.

  • The SDK implementation is in alpha.

Thus, breaking changes may occur without further notice, see Alpha and Beta Features for more information.

Units

List Units

UnitAPI.list() → UnitList

List all supported units

Returns

List of units

Return type

UnitList

Examples

List all supported unit in CDF:

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

Retrieve Unit

UnitAPI.retrieve(external_id: str, ignore_unknown_ids: bool = False) → None | Unit
UnitAPI.retrieve(external_id: MutableSequence[str], ignore_unknown_ids: bool = False) → UnitList

Retrieve one or more unit

Parameters

  • external_id (str | MutableSequence[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
>>> c = CogniteClient()
>>> res = c.units.retrieve('temperature:deg_c')

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

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

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
>>> c = CogniteClient()
>>> res = c.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: str | None = None, source_reference: str | None = 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 = False) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

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

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: Collection[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[Unit]

List of Units

class cognite.client.data_classes.units.UnitSystem(name: str, quantities: list[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 = False) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters

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

Returns

A dictionary representation of the instance.

Return type

dict[str, Any]

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

Bases: CogniteResourceList[UnitSystem]

List of Unit Systems