Datasets#

A dataset holds timestamped data as named channels, such as altitude or temperature. Files you upload and points you stream add to the same dataset over time.

Connect the client#

This guide assumes you have installed the client and setup your API keys.

from nominal.core import NominalClient

client = NominalClient.from_profile("default")

Create a dataset and upload a file#

Create a dataset with create_dataset(), or on an asset with get_or_create_dataset() (see Assets). Then upload a file to it.

The examples upload flight.csv. To run them as written, save this sample under that name:

time,altitude,temperature,tail_number
2026-09-10T14:38:19Z,100.0,20.0,N456QC
2026-09-10T14:38:20Z,101.5,20.2,N456QC
2026-09-10T14:38:21Z,103.0,20.4,N456QC

dataset = client.create_dataset("Flight telemetry")
file = dataset.add_tabular_data("flight.csv", timestamp_column="time", timestamp_type="iso_8601")
file.poll_until_ingestion_completed()  # raises NominalIngestError if ingestion fails
print(dataset.nominal_url)

Each column other than timestamp_column becomes a channel. timestamp_type describes the timestamp values, as in Timestamp formats.

Upload methods return a DatasetFile before ingestion finishes. Wait for it before you read the new channels or the file’s bounds.

Uploading another file adds to the dataset rather than replacing its data. Keep channel names, types and units the same across files.

File formats#

Format	Method	Guide
CSV, Parquet	`add_tabular_data()`	CSV
Journal JSON logs	`add_journal_json()`	Journal JSON
HDF5	convert, then `add_tabular_data()`	HDF5
PX4 ULog	convert, then `add_tabular_data()`	PX4
Avro streams	`add_avro_stream()`	Avro streams
MCAP	`add_mcap()`	MCAP video ingest
Video	`add_video()`	Video ingest
Other binary formats	`add_containerized()`	File extractors

To send values as they’re produced, stream them instead.

Inspect channels and files#

dataset.refresh()
print(dataset.bounds)  # start and end in epoch nanoseconds, or None

for channel in dataset.get_channels():
    print(channel.name, channel.data_type, channel.unit)

for f in dataset.list_files(successful_only=False):  # include failed and pending files
    print(f.name, f.ingest_status.name)

The dataset’s bounds span all its files. file.bounds covers one file.

To set channel types and units, see Channels and data types.

Retrieve a dataset#

Retrieve a dataset by the RID on its page in Nominal, or search by name and labels with search_datasets():

dataset = client.get_dataset("<DATASET_RID>")

This returns the dataset’s metadata, not its data. To download data, see Export data.

Update metadata#

update() replaces each field you pass and leaves the others unchanged. To add a property, merge it with the existing ones:

dataset.update(labels=["flight-test"], properties={**dataset.properties, "campaign": "2026-09"})

Labels and properties describe the whole dataset. To select part of its data, use tags.