Work with units of measure

Units are shared reference data — celsius, bar, m/s, usd. Tagging a time-series with a unit makes its values self-describing: a chart can label its axis, and a consumer knows that 248.6 is bar, not psi. Browse the catalogue, then reference a unit by its external id when you create a series.

Browse the catalogue

Java

client.units().list().getItems().forEach(u ->
    System.out.println(u.getExternalId() + "  " + u.getName() + "  (" + u.getSymbol() + ")  —  " + u.getQuantity()));

Python

for u in client.units.list():
    print(u.external_id, u.name, u.symbol, "—", u.quantity)

Rust

for u in api.units.list().await?.get_items() {
    println!("{}  {}  ({})  —  {}", u.external_id, u.name, u.symbol, u.quantity);
}

Tag a series with a unit

The everyday use: pass a unit's external id when you create a time-series. The value type stays numeric; the unit just describes what the numbers mean.

Java

var series = Timeseries.of("wellhead_pressure_bar").name("Wellhead pressure");
series.setUnit("bar");
client.timeseries().create(series);

Python

import datahub_sdk

client.timeseries.create([datahub_sdk.TimeSeries(
    external_id="wellhead_pressure_bar",
    name="Wellhead pressure",
    unit="bar")])

Rust

use dataplatform_rust_sdk::timeseries::TimeSeries;

let mut ts = TimeSeries::new("wellhead_pressure_bar", "Wellhead pressure");
ts.unit = Some("bar".into());
api.time_series.create_one(&ts).await?;

Look up a specific unit

Resolve a unit you already know — by external id, or by numeric id.

Java

byIds takes UnitModels with their id set:

UnitModel lookup = new UnitModel();
lookup.setId(7L);
UnitModel unit = client.units().byIds(List.of(lookup)).getItems().iterator().next();

Python

import datahub_sdk

celsius = client.units.by_external_ids("temperature_deg_c")
by_id = client.units.by_ids([datahub_sdk.IdCollection(id=7)])

Rust

use dataplatform_rust_sdk::generic::{DataWrapper, IdAndExtId};

let celsius = api.units.by_external_id("temperature_deg_c").await?;
let by_id = api.units.by_ids(&DataWrapper::from(vec![IdAndExtId::from_id(7)])).await?;

Unit external ids are snake_case

The seeded unit catalogue uses snake_case throughout — m_s for metres per second, deg_c for degrees Celsius — so reference them that way and browse the catalogue to find the exact id. That is a property of the catalogue, not a rule about external ids in general: the ones you create are stored exactly as you send them.

See the Units reference for the full method list.