Asset#

class nominal.core.Asset(rid: str, name: str, description: str | None, properties: NominalProperties, labels: Sequence[str], created_at: IntegralNanosecondsUTC, is_archived: bool)#

Bases: _DatasetScopeIngestMixin, HasRid, RefreshableGrpcMixin[Asset]

A logical grouping of datasets, runs, events, and attachments.

Often a digital twin of a physical asset; it can also represent a shared concept.

rid: str#
name: str#
description: str | None#
properties: NominalProperties#
labels: Sequence[str]#
created_at: IntegralNanosecondsUTC#
is_archived: bool#
property nominal_url: str#

Returns a link to the page for this Asset 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 asset.

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_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(data_scope_name: str, dataset: Dataset | str, *, series_tags: Mapping[str, str] | None = None) → None#

Add a dataset to this asset.

Assets map “data_scope_name” (their name within the asset) to a Dataset (or dataset rid). The same type of datasets should use the same data scope name across assets, since checklists and templates use data scope names to reference datasets.

Parameters:

  • data_scope_name – logical name for the data scope within the asset

  • dataset – dataset to add to the asset

  • series_tags – Key-value tags to pre-filter the dataset with before adding to the asset.

Raises:

NominalError – If adding the data scope 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:
add_mcap(data_scope_name: str, path: Path | str, *, include_topics: Iterable[str] | None = None, exclude_topics: Iterable[str] | None = None, tags: Mapping[str, str] | None = None, ignore_invalid_topics: bool | None = None) → DatasetFile#

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(data_scope_name: str, video: Video | str) → None#

Add a video to this asset.

Assets map “data_scope_name” (name within the asset for the data) to a Video (or a video rid). The same type of videos (e.g., files from a given camera) should use the same data scope name across assets, since checklists and templates use data scope names to reference videos.

Raises:

NominalError – If adding the data scope fails.

archive() → None#

Archive this asset. Archived assets 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_event(name: str, type: EventType, start: datetime | int, duration: timedelta | int = 0, *, description: str | None = None, properties: Mapping[str, str | float] | None = None, labels: Sequence[str] | None = None) → Event#

Create an event associated with this Asset 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 the asset.

Raises:

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

create_run(name: str, start: datetime | int, end: datetime | int | None, *, description: str | None = None, properties: Mapping[str, str | float] | None = None, labels: Sequence[str] = (), links: Sequence[str | tuple[str, str] | LinkDict] = (), attachments: Iterable[Attachment] | Iterable[str] = ()) → Run#

Create a run associated with this Asset for a given span of time.

Parameters:

  • name – Name of the run.

  • start – Starting timestamp of the run.

  • end – Ending timestamp of the run, or None for an unbounded run.

  • description – Optionally, a human readable description of the run to create.

  • properties – String or numeric properties for the created run. Integers are stored as floats.

  • labels – Sequence of labels to use on the created run.

  • links – Link metadata to add to the created run.

  • attachments – Attachments to associate with the created run.

Returns:

Returns the created run

Raises:

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

get_data_scope(data_scope_name: str) → Dataset | Video#

Retrieve the dataset or video behind a data scope name.

Raises:

NominalNotFoundError – If no readable data scope has this name.

get_dataset(data_scope_name: str) → Dataset#

Retrieve a dataset by data scope name.

Parameters:

data_scope_name – Name of the asset data scope to resolve.

Returns:

Dataset associated with the data scope name.

Raises:

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

get_or_create_dataset(data_scope_name: str, *, name: str | None = None, description: str | None = None, labels: Sequence[str] = (), properties: Mapping[str, str | float] | None = None, prefix_tree_delimiter: str | None = None, series_tags: Mapping[str, str] | None = None) → Dataset#

Retrieve a dataset by data scope name, or create a new one if it does not exist.

Parameters:

  • data_scope_name – Datascope name to use when looking up or adding a dataset to an asset.

  • name – Name of the dataset to create, if one is not found.

  • description – Human readable description of the dataset to create, if one is not found.

  • labels – Labels of the dataset to create, if one is not found.

  • properties – String or numeric properties for a newly created dataset. Integers are stored as floats.

  • prefix_tree_delimiter – The prefix tree delimiter to use with the created dataset, if one is not found.

  • series_tags – Tags to filter the created dataset by in the datascope, if one is not found.

Returns:

The retrieved or created dataset.

Raises:

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

  • NominalNotFoundError – If a dataset data scope with this name exists but its dataset is not readable.

  • ValueError – If a dataset data scope with this name exists with different series tags, or a data scope of another type has this name.

get_or_create_video(data_scope_name: str, *, name: str | None = None, description: str | None = None, labels: Sequence[str] = (), properties: Mapping[str, str] | None = None) → Video#

Retrieve a video by data scope name, or create a new one if it does not exist.

Raises:

  • NominalNotFoundError – If a video data scope with this name exists but its video is not readable.

  • ValueError – If a data scope of another type has this name.

get_video(data_scope_name: str) → Video#

Retrieve a video by data scope name.

Parameters:

data_scope_name – Name of the asset data scope to resolve.

Returns:

Video associated with the data scope name.

Raises:

NominalNotFoundError – If no readable video has this data scope name.

list_attachments() → Sequence[Attachment]#

List the attachments associated with this asset.

Attachments that the caller cannot access are left out.

list_data_scopes() → Sequence[tuple[str, Dataset | Video]]#

List scopes associated with this asset.

Returns:

(data_scope_name, scope) pairs, where scope can be a dataset or video. Data scopes whose resource is missing or not readable are left out.

Spatials are not included: they live in nominal.experimental.spatial, whose list_spatials_in_asset lists them.

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

List the datasets associated with this asset.

Returns:

(data_scope_name, dataset) pairs. Data scopes whose dataset is missing or not readable are left out.

list_runs() → Sequence[Run]#

List all runs associated with this Asset.

Raises:

NominalError – If a run search request fails.

list_streaming_checklists() → Sequence[str]#

List all Streaming Checklists associated with this Asset. See nominal.core.client.list_streaming_checklists for details.

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

List the videos associated with this asset.

Returns:

(data_scope_name, video) pairs. Data scopes whose video is missing or not readable are left out.

promote() → Self#

Promote this asset to be a standard, searchable, and displayable asset.

This method is only useful for assets that were created implicitly from creating a run directly on a dataset. Nothing will happen from calling this method (aside from a logged warning) if called on a non-staged asset (e.g. an asset created by create_asset, or an asset that’s already been promoted).

Raises:

NominalError – If retrieving or promoting the asset fails.

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

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

attachments can be Attachment instances, or attachment RIDs.

Raises:

NominalError – If removing the attachments fails.

remove_data_scopes(*, names: Sequence[str] | None = None, scopes: Sequence[Dataset | Video | str] | None = None) → None#

Remove data scopes from this asset.

Parameters:

  • names – Names of datascopes to remove

  • scopes – Rids or instances of scope types (dataset, video) to remove. A spatial can be removed by passing its rid.

Raises:

NominalError – If retrieving or updating the asset’s data scopes fails.

search_data_reviews(runs: Sequence[Run | str] | None = None, *, archive_status: ArchiveStatusFilter = ArchiveStatusFilter.NOT_ARCHIVED) → Sequence[DataReview]#

Search for data reviews associated with this Asset. See nominal.core.client.search_data_reviews for details.

search_events(*, search_text: str | None = None, after: str | datetime | int | None = None, before: str | datetime | int | None = None, labels: Iterable[str] | None = None, properties: Mapping[str, str | float] | None = None, created_by_rid: str | None = None, workbook_rid: str | None = None, data_review_rid: str | None = None, assignee_rid: str | None = None, event_type: EventType | None = None, priority: Priority | None = None, origin_types: Iterable[SearchEventOriginType] | None = None, archive_status: ArchiveStatusFilter = ArchiveStatusFilter.NOT_ARCHIVED) → Sequence[Event]#

Search for events associated with this Asset. See nominal.core.event._search_events for details.

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 – Labels that must all be present on an event.

  • properties – Property equalities that must all match. Strings and numbers match their respective types. Integer values are converted to floats.

  • created_by_rid – Search for events created by this author.

  • workbook_rid – Search for events on this workbook.

  • data_review_rid – Search for events from this data review.

  • assignee_rid – Search for events assigned to this user.

  • event_type – Search for events of this verbosity level.

  • priority – Filter events by disposition priority. None leaves priority unrestricted.

  • origin_types – Search for events created by these origin types.

  • archive_status – Filter by archive status. Defaults to NOT_ARCHIVED.

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, created_by_rid: str | None = None, run_rid: str | None = None, include_drafts: bool = False, archive_status: ArchiveStatusFilter = ArchiveStatusFilter.NOT_ARCHIVED) → Sequence[Workbook]#

Search for workbooks associated with this Asset.

See nominal.core.NominalClient.search_workbooks for details.

unarchive() → None#

Unarchive this asset, allowing it to be viewed in 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.

update(*, name: str | None = None, description: str | None = None, properties: Mapping[str, str | float] | None = None, labels: Sequence[str] | None = None, links: Sequence[str] | Sequence[tuple[str, str]] | None = None) → Self#

Replace asset 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 or tuples of (URL, name).

Parameters:

  • name – Replacement name.

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

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 asset.labels:
    new_labels.append(old_label)
asset = asset.update(labels=new_labels)
Raises:

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

  • NominalError – If the update request fails.