Run#

class nominal.core.Run(rid: str, name: str, description: str, properties: NominalProperties, labels: Sequence[str], links: Sequence[LinkDict], start: IntegralNanosecondsUTC, end: IntegralNanosecondsUTC | None, run_number: int, assets: Sequence[str], created_at: IntegralNanosecondsUTC, is_archived: bool)#

Bases: HasRid, RefreshableGrpcMixin[Run], _DatasetScopeIngestMixin

A view of asset and dataset data within a time interval.

rid: str#

name: str#

description: str#

properties: NominalProperties#

labels: Sequence[str]#

links: Sequence[LinkDict]#

start: IntegralNanosecondsUTC#

end: IntegralNanosecondsUTC | None#

run_number: int#

assets: Sequence[str]#

created_at: IntegralNanosecondsUTC#

is_archived: bool#

property nominal_url: str#: Returns a link to the page for this Run in the Nominal app

add_ardupilot_dataflash(data_scope_name: str, path: Path | str, tags: Mapping[str, str] | None = None) → DatasetFile#

Add a Dataflash file to the dataset selected by data_scope_name.

This method behaves like nominal.core.Dataset.add_ardupilot_dataflash, except that the data scope’s required tags are merged into tags before ingest (with user-provided tags taking precedence on key collisions).

For file expectations and return value details, see nominal.core.Dataset.add_ardupilot_dataflash.

Raises:: NominalNotFoundError – If no readable dataset has this data scope name.

add_attachments(attachments: Iterable[Attachment] | Iterable[str]) → None#

Add attachments that have already been uploaded to this run.

attachments can be Attachment instances, or attachment RIDs.

Raises:: NominalError – If adding the attachments fails.

add_avro_stream(data_scope_name: str, path: Path | str, *, timestamp_type: Epoch | Relative | Literal['epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'] | None = None, tags: Mapping[str, str] | None = None) → DatasetFile#

Upload an avro stream file to the dataset selected by data_scope_name.

This method behaves like nominal.core.Dataset.add_avro_stream, except that the data scope’s required tags are merged into tags before ingest (with user-provided tags taking precedence on key collisions). Tags in the avro records take precedence over both, so a scope tag whose key a record already sets is not applied to that record’s data.

For schema requirements, argument semantics, and return value details, see nominal.core.Dataset.add_avro_stream.

Raises:: NominalNotFoundError – If no readable dataset has this data scope name.

add_comment(content: str) → Comment#

Post a markdown comment to this run’s discussion.

Parameters:: content – Markdown content for the comment.
Returns:: The created Comment.
Raises:: NominalError – If the comments service request fails.

add_containerized(data_scope_name: str, extractor: str | ContainerizedExtractor, sources: Mapping[str, Path | str], *, arguments: Mapping[str, str] | None = None, tags: Mapping[str, str] | None = None, timestamp_column: str | None = None, timestamp_type: Iso8601 | Epoch | Relative | Custom | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'] | None = None) → IngestionJob#

Add data from proprietary formats using a pre-registered custom extractor.

This method behaves like nominal.core.Dataset.add_containerized, except that the data scope’s required tags are merged into tags before ingest (with user-provided tags taking precedence on key collisions).

Pass both timestamp_column and timestamp_type, or neither; this wrapper enforces that before delegating.

For extractor inputs, tagging semantics, timestamp metadata behavior, and return value details, see nominal.core.Dataset.add_containerized.

Raises:

NominalNotFoundError – If no readable dataset has this data scope name.
ValueError – If only one of timestamp_column and timestamp_type is given.

add_dataset(ref_name: str, dataset: Dataset | str, *, series_tags: Mapping[str, str] | None = None, offset: timedelta | int | None = None) → None#

Add a dataset to this run.

Datasets map “ref names” (their name within the run) to a Dataset (or dataset rid). The same type of datasets should use the same ref name across runs, since checklists and templates use ref names to reference datasets.

Parameters:

ref_name – Logical name for the data scope within the run
dataset – Dataset to add to the run
series_tags – Key-value tags to pre-filter the dataset with before adding to the run.
offset – Add the dataset to the run with a pre-baked offset

Raises:

NominalError – If adding the data source fails.

add_datasets(datasets: Mapping[str, Dataset | str], *, series_tags: Mapping[str, str] | None = None, offset: timedelta | int | None = None) → None#

Add multiple datasets to this run.

Parameters:

datasets – Mapping of logical names to datasets to add to the run
series_tags – Key-value tags to pre-filter the datasets with before adding to the run.
offset – Add the datasets to the run with a pre-baked offset

Raises:

NominalError – If adding the data sources fails.

add_from_io(data_scope_name: str, data_stream: BinaryIO, file_type: tuple[str, str] | FileType, *, timestamp_column: str, timestamp_type: Iso8601 | Epoch | Relative | Custom | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'], file_name: str | None = None, tag_columns: Mapping[str, str] | None = None, tags: Mapping[str, str] | None = None) → DatasetFile#

Append to the dataset selected by data_scope_name from a file-like object.

This method behaves like nominal.core.Dataset.add_from_io, except that the data scope’s required tags are merged into tags before ingest (with user-provided tags taking precedence on key collisions).

For stream requirements, supported file types, argument semantics, and return value details, see nominal.core.Dataset.add_from_io.

Raises:: NominalNotFoundError – If no readable dataset has this data scope name.

add_journal_json(data_scope_name: str, path: Path | str, *, channel: str | None = None, timestamp_column: str | None = None, timestamp_type: Epoch | Literal['epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'] | None = None) → DatasetFile#

Add a journald json file to the dataset selected by data_scope_name.

This method behaves like nominal.core.Dataset.add_journal_json, with one important difference: the journal json ingest request has no field for tags, so a scope’s required tags cannot be applied to the ingested logs. If the selected scope requires tags, this method raises RuntimeError rather than ingesting logs that would be missing them. The file can still be ingested on the dataset directly, if its own contents already carry what the scope needs.

Pass both timestamp_column and timestamp_type, or neither; this wrapper enforces that before delegating.

For file expectations, timestamp argument semantics, and return value details, see nominal.core.Dataset.add_journal_json.

Raises:

NominalNotFoundError – If no readable dataset has this data scope name.
RuntimeError – If the data scope requires series tags.
ValueError – If only one of timestamp_column and timestamp_type is given.

Add an MCAP file to the dataset selected by data_scope_name.

This method behaves like nominal.core.Dataset.add_mcap, except that the data scope’s required tags are merged into tags before ingest (with user-provided tags taking precedence on key collisions).

For topic-filtering semantics and return value details, see nominal.core.Dataset.add_mcap.

Raises:: NominalNotFoundError – If no readable dataset has this data scope name.

add_tabular_data(data_scope_name: str, path: Path | str, *, timestamp_column: str, timestamp_type: Iso8601 | Epoch | Relative | Custom | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'], tag_columns: Mapping[str, str] | None = None, tags: Mapping[str, str] | None = None) → DatasetFile#

Append tabular data on-disk to the dataset selected by data_scope_name.

This method behaves like nominal.core.Dataset.add_tabular_data, except that the data scope’s required tags are merged into tags before ingest (with user-provided tags taking precedence on key collisions).

For supported file types, argument semantics, and return value details, see nominal.core.Dataset.add_tabular_data.

Raises:: NominalNotFoundError – If no readable dataset has this data scope name.

add_video(ref_name: str, video: Video | str) → None#

Add a video to a run via video object or RID.

Raises:: NominalError – If adding the data source fails.

archive() → None#

Archive this run. Archived runs are not deleted, but are hidden from the UI.

Note

This does not update the instance in place; call refresh() to see the change reflected.

Raises:: NominalError – If the archive request fails.

Create an event associated with all associated assets of this run at a given point in time.

Parameters:

name – Name of the event
type – Verbosity level of the event.
start – Starting timestamp of the event
duration – Duration of the event, or 0 for an event without duration.
description – Optionally, a human readable description of the event to create
properties – String or numeric properties for the created event. Integers are stored as floats.
labels – Sequence of labels to use on the created event.

Returns:

The created event that is associated with all of the assets associated with this run..

Raises:

TypeError – If a property value is a boolean or is not a string, integer, or float.

get_dataset(ref_name: str) → Dataset#

Get a dataset for this run by its ref name.

Parameters:: ref_name – Name of the run datasource reference to resolve.
Returns:: Dataset associated with the ref name.
Raises:: NominalNotFoundError – If no readable dataset has this ref name.

get_video(ref_name: str) → Video#

Get a video for this run by its ref name.

Parameters:: ref_name – Name of the run datasource reference to resolve.
Returns:: Video associated with the ref name.
Raises:: NominalNotFoundError – If no readable video has this ref name.

list_assets() → Sequence['Asset']#: List assets associated with this run.

list_attachments() → Sequence[Attachment]#

List a sequence of Attachments associated with this Run.

Attachments that the caller cannot access are left out.

list_datasets() → Sequence[tuple[str, Dataset]]#

List the datasets associated with this run.

Returns:: (ref_name, dataset) pairs. Refs whose dataset is missing or not readable are left out.

list_videos() → Sequence[tuple[str, Video]]#

List the videos associated with this run.

Returns:: (ref_name, video) pairs. Refs whose video is missing or not readable are left out.

refresh() → Self#

remove_attachments(attachments: Iterable[Attachment] | Iterable[str]) → None#

Remove attachments from this run. Does not remove the attachments from Nominal.

attachments can be Attachment instances, or attachment RIDs.

Raises:: NominalError – If removing the attachments fails.

remove_data_sources(*, ref_names: Sequence[str] | None = None, data_sources: Sequence[Dataset | Video | str] | None = None) → None#

Remove data sources from this run.

The list data_sources can contain Dataset or Video instances, or rids as string. A spatial can be removed by passing its rid.

Raises:: NominalError – If retrieving or updating the run’s data sources fails.

Search for events associated with any of the assets of this run.

The run’s assets are matched as a union: an event is included if it is associated with at least one of the run’s assets. The remaining filters are ANDed together with that asset filter and with each other.

Parameters:

search_text – Searches for a string in the event’s metadata.
after – Filters to end times after this time, exclusive.
before – Filters to start times before this time, exclusive.
labels – A list of labels that must ALL be present on an event to be included.
properties – Property equalities that must ALL match. String values match string properties; numeric values match numeric properties, without coercing strings to numbers. Integer values are converted to floats.
created_by_rid – Rid of the author that must be present on an event to be included.
workbook_rid – Search for events on the given workbook.
data_review_rid – Search for events from the given data review.
assignee_rid – Search for events with the given assignee.
event_type – Search for events of the given type.
priority – Filter events by disposition priority. None leaves priority unrestricted.
origin_types – Search for events created by any of the given origin types.
archive_status – Filter by archive status. Defaults to NOT_ARCHIVED.

Returns:

Events associated with any of this run’s assets that match all of the provided filters. Returns an empty sequence if the run has no associated assets.

Raises:

TypeError – If a property value is a boolean or is not a string, integer, or float.

search_workbooks(*, exact_match: str | None = None, search_text: str | None = None, labels: Sequence[str] | None = None, properties: Mapping[str, str] | None = None, asset_rid: str | None = None, created_by_rid: str | None = None, include_drafts: bool = False, archive_status: ArchiveStatusFilter = ArchiveStatusFilter.NOT_ARCHIVED) → Sequence[Workbook]#: Search for workbooks associated with this Run. See nominal.core.NominalClient.search_workbooks for details

unarchive() → None#

Unarchive this run, allowing it to appear on the UI.

Note

This does not update the instance in place; call refresh() to see the change reflected.

Raises:: NominalError – If the unarchive request fails.

Replace run metadata. Updates the current instance, and returns it. Only the metadata passed in will be replaced, the rest will remain untouched.

Links can be URLs, tuples of (URL, name), or dicts of {url=URL, title=name}.

Parameters:

name – Replacement name.
start – Replacement start timestamp.
end – Replacement end timestamp.
description – Replacement description.
properties – String or numeric properties. Integers are stored as floats. None leaves properties unchanged; an empty mapping clears them.
labels – Replacement labels.
links – Replacement links.
assets – Replacement assets or asset RIDs.

Note

This replaces the metadata rather than appending it. To append to labels or properties, merge them before calling this method. E.g.:

new_labels = ["new-label-a", "new-label-b"]
for old_label in run.labels:
    new_labels.append(old_label)
run = run.update(labels=new_labels)

Note

When assets is provided it fully replaces the run’s asset list. To append an asset, merge with the existing list first:

run = run.update(assets=[*run.assets, new_asset])

Raises:

TypeError – If a property value is a boolean or is not a string, integer, or float.
NominalError – If the update request fails.