Look up Unit from alias

async AsyncCogniteClient.units.from_alias(
alias: str,
quantity: str | None = None,
*,
return_ambiguous: bool = False,
return_closest_matches: bool = False,
) → Unit | 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, AsyncCogniteClient
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> 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)