Unit Catalog

Units

List Units

UnitAPI.list() → UnitList

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’:

>>> 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