NominalClient#

class nominal.core.NominalClient#

Bases: object

A client for uploading data and managing resources on the Nominal platform.

classmethod create(base_url, token, trust_store_path=None, connect_timeout=DEFAULT_CONNECT_TIMEOUT, *, workspace_rid=None, extra_headers=None)#

Create a connection to the Nominal platform.

Parameters:

base_url (str)

The URL of the Nominal API platform, e.g. “https://api.gov.nominal.io/api”.
token (str | None)

An API token to authenticate with. If None, the token will be looked up in ~/.nominal.yml.
trust_store_path (str | None)

Path to a PEM CA bundle used to verify TLS for both the HTTP and gRPC transports. Defaults to certifi’s bundle. On Windows and Linux, the host’s OS trust store (including enterprise/GPO/MDM-installed CAs) is automatically unioned in, so the client works on corporate networks with no extra configuration. On macOS, point this at your corporate CA PEM if you are behind a TLS-inspecting proxy.
connect_timeout (timedelta | float)

Timeout for any single request to the Nominal API.
workspace_rid (str | None)

Optional workspace RID to pin the client to for operations that require a single workspace. If not provided, those operations resolve a default workspace client-side when needed.
extra_headers (HeaderProvider | Mapping[str, str] | None)

Extra request headers, either as a mapping or HeaderProvider.

Raises:

NominalConfigError – If the base URL is malformed, contains user information, or uses HTTP without a literal loopback IP. This prevents client construction even for HTTP-only usage.

Return type:

Self

create_asset(name, description=None, *, properties=None, labels=())#

Create an asset.

Parameters:

name (str)

Name of the asset.
description (str | None)

Human readable description of the asset.
properties (Mapping[str, str | float] | None)

String or numeric properties for the created asset. Integers are stored as floats.
labels (Sequence[str])

Labels to apply to the asset.

Raises:

TypeError – If a property value is a boolean or is not a string, integer, or float.
NominalConfigError – If no default workspace can be resolved.
NominalError – If the creation request fails.

Return type:

Asset

create_attachment(attachment_file, *, description=None, properties=None, labels=())#

Return type:: Attachment

create_attachment_from_io(attachment, name, file_type=FileTypes.BINARY, description=None, *, properties=None, labels=())#

Upload an attachment. The attachment must be a file-like object in binary mode, e.g. open(path, “rb”) or io.BytesIO. If the file is not in binary-mode, the requests library blocks indefinitely.

Parameters:

attachment (BinaryIO)

Binary stream to upload; the caller retains ownership.
name (str)

Attachment title and upload filename. The title is kept as supplied. The upload filename preserves any existing extension; otherwise it uses the default from file_type.
file_type (tuple[str, str] | FileType)

Default extension and MIME type. The default binary type leaves the upload name unchanged.
description (str | None)

Optional description of the attachment.
properties (Mapping[str, str] | None)

Properties to apply to the attachment.
labels (Sequence[str])

Labels to apply to the attachment.

Raises:

ValueError – An applied default extension is malformed or the upload filename contains unsafe characters.
NominalError – If creating the attachment from the uploaded file fails.

Return type:

Attachment

create_containerized_extractor(name, *, description=None, labels=None, properties=None)#

Create a containerized extractor for parsing custom data formats using Nominal-hosted docker images.

A newly created extractor has no container image: register one with ContainerizedExtractor.register_image and activate it before ingesting.

Parameters:

name (str)

Name of the extractor.
description (str | None)

Human-readable description of the extractor.
labels (Sequence[str] | None)

Labels to set on the extractor.
properties (Mapping[str, str] | None)

Key-value properties to set on the extractor.

Returns:

The newly created extractor.

Return type:

ContainerizedExtractor

create_dataset(name, *, description=None, labels=(), properties=None, prefix_tree_delimiter=None, markings=None)#

Create an empty dataset.

Parameters:

name (str)

Name of the dataset to create in Nominal.
description (str | None)

Human readable description of the dataset.
labels (Sequence[str])

Text labels to apply to the created dataset
properties (Mapping[str, str | float] | None)

String or numeric properties for the created dataset. Integers are stored as floats.
prefix_tree_delimiter (str | None)

If present, the delimiter to represent tiers when viewing channels hierarchically.
markings (Sequence[Marking | str] | None)

If present, markings (or marking RIDs) applied to the dataset. Sent as part of the creation request rather than applied in a follow-up call.

Returns:

Reference to the created dataset in Nominal.

Raises:

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

Return type:

Dataset

create_empty_video(name, *, description=None, labels=(), properties=None, markings=None)#

Create an empty video to append video files to.

Parameters:

name (str)

Name of the video to create in Nominal
description (str | None)

Description of the video to create in nominal
labels (Sequence[str])

Labels to apply to the video in nominal
properties (Mapping[str, str] | None)

Properties to apply to the video in nominal
markings (Sequence[Marking | str] | None)

If present, markings (or marking RIDs) applied to the video. Sent as part of the creation request rather than applied in a follow-up call.

Returns:

Handle to the created video

Return type:

Video

create_event(name, type, start, duration=timedelta(), *, description=None, assets=(), properties=None, labels=())#

Create an event.

Parameters:

name (str)

Name of the event.
type (EventType)

Verbosity level of the event.
start (datetime | int)

Starting timestamp of the event.
duration (timedelta | int)

Duration of the event, or zero for an event without duration.
description (str | None)

Human readable description of the event.
assets (Iterable[Asset | str])

Assets or asset RIDs associated with the event.
properties (Mapping[str, str | float] | None)

String or numeric properties for the created event. Integers are stored as floats.
labels (Iterable[str])

Labels to apply to the event.

Raises:

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

Return type:

Event

create_marking(id, *, description=None, authorized_groups=(), symbol=None, color=None)#

Create a marking in the current organization.

Parameters:

id (str)

Human-readable identifier for the marking, unique within the organization. Must be lowercase alphanumeric characters optionally separated by hyphens, starting with a letter, e.g. export-controlled.
description (str | None)

Human readable description of the marking.
authorized_groups (Sequence[str])

RIDs of the groups authorized to access data sources carrying this marking.
symbol (Symbol | None)

Symbol identifying the marking in the Nominal app.
color (str | None)

Six-digit hex color identifying the marking in the Nominal app, e.g. #cc0000. Either case is accepted; the value is lowercased before being sent.

Returns:

Reference to the created marking.

Raises:

ValueError – If id is not a valid marking id, or color is not a valid hex color.
NominalError – If creation fails, including when the caller is not an organization admin or a marking with this id already exists.

Return type:

Marking

create_opsgenie_integration(name, api_key, region, *, description=None)#

Create an Opsgenie notification integration in the client’s default workspace.

Parameters:

name (str)

Display name of the integration.
api_key (str)

Opsgenie API key.
region (OpsgenieRegion)

Region hosting the Opsgenie integration.
description (str | None)

Optional description.

Returns:

The created integration.

Raises:

NominalConfigError – If no default workspace can be resolved.

Return type:

Integration

create_pagerduty_integration(name, routing_key, *, description=None)#

Create a PagerDuty notification integration in the client’s default workspace.

Parameters:

name (str)

Display name of the integration.
routing_key (str)

PagerDuty routing key.
description (str | None)

Optional description.

Returns:

The created integration.

Raises:

NominalConfigError – If no default workspace can be resolved.

Return type:

Integration

Create a run, which is is effectively a slice of time across a collection of assets and datasources.

Parameters:

name (str)

Name of the run to create
start (datetime | int)

Starting timestamp of the run to create
end (datetime | int | None)

Ending timestamp of the run to create, or None for an unbounded run.
description (str | None)

Optional description of the run to create
properties (Mapping[str, str | float] | None)

String or numeric properties for the created run. Integers are stored as floats.
labels (Sequence[str] | None)

Optional sequence of labels for the created run
links (Sequence[str | tuple[str, str] | LinkDict] | None)

Link metadata to add to the created run
attachments (Iterable[Attachment] | Iterable[str] | None)

Attachments to associate with the created run
assets (Sequence[Asset | str] | None)

Sequence of assets to associate with the run

Returns:

Reference to the created run object

Raises:

TypeError – If a property value is a boolean or is not a string, integer, or float.
NominalConfigError – If no default workspace can be resolved.
NominalError – If the run service request fails.

Return type:

Run

create_secret(name, decrypted_value, description=None, labels=(), properties=None)#

Create a secret for the current user

Parameters:

name (str)

Name of the secret
decrypted_value (str)

Plain text value of the secret
description (str | None)

Description of the secret
labels (Sequence[str])

Labels for the secret
properties (Mapping[str, str] | None)

Properties for the secret

Return type:

Secret

create_teams_integration(name, webhook_url, *, description=None)#

Create a Microsoft Teams notification integration in the client’s default workspace.

Parameters:

name (str)

Display name of the integration.
webhook_url (str)

Teams webhook URL for notifications.
description (str | None)

Optional description.

Returns:

The created integration.

Raises:

NominalConfigError – If no default workspace can be resolved.

Return type:

Integration

create_video(name, *, description=None, labels=(), properties=None, markings=None)#

Create an empty video to append video files to.

Parameters:

name (str)

Name of the video to create in Nominal
description (str | None)

Description of the video to create in nominal
labels (Sequence[str])

Labels to apply to the video in nominal
properties (Mapping[str, str] | None)

Properties to apply to the video in nominal
markings (Sequence[Marking | str] | None)

If present, markings (or marking RIDs) applied to the video. Sent as part of the creation request rather than applied in a follow-up call.

Returns:

Handle to the created video

Return type:

Video

create_webhook_integration(name, webhook_url, *, description=None)#

Create a generic webhook notification integration in the client’s default workspace.

Parameters:

name (str)

Display name of the integration.
webhook_url (str)

Destination URL for notifications.
description (str | None)

Optional description.

Returns:

The created integration.

Raises:

NominalConfigError – If no default workspace can be resolved.

Return type:

Integration

create_workbook_template(title, *, description=None, labels=None, properties=None, commit_message=None, is_published=False, workspace=WorkspaceSearchType.DEFAULT)#

Create an empty workbook template.

Parameters:

title (str)

Title of the workbook template
description (str | None)

Description of the workbook template
labels (list[str] | None)

Labels to attach to the workbook template
properties (Mapping[str, str] | None)

Properties to attach to the workbook template
commit_message (str | None)

An optional message to include with the creation of the template
is_published (bool)

Whether to publish the template so other users can view it. Defaults to False.
workspace (WorkspaceSearchType | Workspace | str | None)

Workspace to create the workbook template in. Pass WorkspaceSearchType.DEFAULT (or None) to resolve a single workspace by preferring the client’s configured workspace_rid and then falling back to a client-side default-workspace lookup.

Returns:

The created WorkbookTemplate

Return type:

WorkbookTemplate

data_review_builder()#

Return type:: DataReviewBuilder

classmethod from_profile(profile, *, trust_store_path=None, connect_timeout=DEFAULT_CONNECT_TIMEOUT, extra_headers=None)#

Create a connection to the Nominal platform from a named profile in the Nominal config.

Parameters:

profile (str)

profile name in the Nominal config.
trust_store_path (str | None)

Path to a PEM CA bundle used to verify TLS for both the HTTP and gRPC transports. Defaults to certifi’s bundle. On Windows and Linux, the host’s OS trust store (including enterprise/GPO/MDM-installed CAs) is automatically unioned in, so the client works on corporate networks with no extra configuration. On macOS, point this at your corporate CA PEM if you are behind a TLS-inspecting proxy.
connect_timeout (timedelta | float)

Request connection timeout.
extra_headers (HeaderProvider | Mapping[str, str] | None)

Extra request headers, either as a mapping or HeaderProvider.

Raises:

NominalConfigError – If the base URL is malformed, contains user information, or uses HTTP without a literal loopback IP. This prevents client construction even for HTTP-only usage.

Return type:

Self

classmethod from_token(token, base_url=DEFAULT_API_BASE_URL, *, workspace_rid=None, trust_store_path=None, connect_timeout=DEFAULT_CONNECT_TIMEOUT, extra_headers=None, _profile=None)#

Create a connection to the Nominal platform from a token.

Parameters:

token (str)

Authentication token to use for the connection.
base_url (str)

The URL of the Nominal API platform.
workspace_rid (str | None)

Optional workspace RID to pin the client to for operations that require a single workspace. If not provided, those operations lazily resolve a default workspace when required.
trust_store_path (str | None)

Path to a PEM CA bundle used to verify TLS for both the HTTP and gRPC transports. Defaults to certifi’s bundle. On Windows and Linux, the host’s OS trust store (including enterprise/GPO/MDM-installed CAs) is automatically unioned in, so the client works on corporate networks with no extra configuration. On macOS, point this at your corporate CA PEM if you are behind a TLS-inspecting proxy.
connect_timeout (timedelta | float)

Request connection timeout.
extra_headers (HeaderProvider | Mapping[str, str] | None)

Extra request headers, either as a mapping or HeaderProvider.

Raises:

NominalConfigError – If the base URL is malformed, contains user information, or uses HTTP without a literal loopback IP. This prevents client construction even for HTTP-only usage.

Return type:

Self

get_all_units()#

Retrieve list of metadata for all supported units within Nominal

Return type:: Sequence[Unit]

get_asset(rid)#

Retrieve an asset by its RID.

Raises:

NominalNotFoundError – If no asset has that rid.
ValueError – If the backend returns multiple assets for the RID.
NominalError – If the retrieval request fails.

Return type:

Asset

get_attachment(rid)#

Retrieve an attachment by its RID.

Raises:

NominalNotFoundError – If no attachment with that RID is accessible.
NominalError – If the retrieval request fails.

Return type:

Attachment

get_attachments(rids)#

Retrieve attachments by their RIDs.

Raises:

NominalNotFoundError – If any RID does not resolve to an accessible attachment.
NominalError – If a retrieval request fails.

Return type:

Sequence[Attachment]

get_checklist(rid)#

Return type:: Checklist

get_commensurable_units(unit_symbol)#

Get the list of units that are commensurable (convertible to/from) the given unit symbol.

Raises:: NominalError – If the units service request fails.
Return type:: Sequence[Unit]

get_container_image(rid)#

Get a container image by its RID.

Parameters:

rid (str)

RID of the container image to retrieve.

Returns:

The requested image, e.g. to poll its status after registration.

Return type:

ContainerImage

get_containerized_extractor(rid)#

Get a containerized extractor by its RID.

Parameters:

rid (str)

RID of the containerized extractor to retrieve.

Returns:

The requested extractor, including its active container image (if any).

Return type:

ContainerizedExtractor

get_data_review(rid)#

Retrieve a data review by its RID.

Raises:

NominalNotFoundError – If no data review has that rid.
NominalError – If the retrieval request fails.

Return type:

DataReview

get_dataset(rid)#

Retrieve a dataset by its RID.

Return type:: Dataset

get_datasets(rids)#

Retrieve datasets by their RIDs.

Return type:: Sequence[Dataset]

get_datasource(rid)#

Retrieve a dataset by its RID. Prefer get_dataset for dataset operations.

Return type:: Dataset

get_event(rid)#

Retrieve an event by its RID.

Raises:: NominalNotFoundError – If no event has that rid.
Return type:: Event

get_events(rids)#

Retrieve events by their RIDs.

Parameters:

rids (Sequence[str])

RIDs of the events to retrieve.

Returns:

The events that resolved, in the order the backend returned them. RIDs that do not resolve are omitted rather than raising, so the result may be shorter than rids. Use get_event for a single rid that must exist.

Return type:

Sequence[Event]

get_ingestion_job(rid)#

Retrieve an ingest job by its RID.

Return type:: IngestionJob

get_integration(rid)#

Retrieve a notification integration by RID.

Raises:: NominalNotFoundError – If the integration does not exist or is not accessible.
Return type:: Integration

get_marking(rid)#

Retrieve a marking by RID.

Raises:

NominalNotFoundError – If no marking with the given RID exists.
NominalPermissionDeniedError – If the caller cannot read it.

Return type:

Marking

get_marking_by_id(id)#

Retrieve a marking by its human-readable id, unique within the organization.

Raises:

ValueError – If id is not a valid marking id.
NominalNotFoundError – If no marking with the given id exists.
NominalPermissionDeniedError – If the caller cannot read it.

Return type:

Marking

get_or_create_asset_by_properties(properties, *, name, description=None, labels=())#

Searches for an asset using using properties. If no assets returned, create one.: If multiple assets returned, throw error.

Parameters:

properties (Mapping[str, str | float])

String or numeric properties used to search for or create the asset. Integer values are converted to floats.
name (str)

Name of asset to be used if creation is necessary.
description (str | None)

Description of asset to be used if creation is necessary.
labels (Sequence[str])

a sequence of labels to use when if creation is necessary.

Returns:

The existing or newly created asset.

Raises:

TypeError – If a property value is a boolean or is not a string, integer, or float.
ValueError – If multiple assets match the properties.
NominalConfigError – If no default workspace can be resolved.
NominalError – If searching for or creating the asset fails.

Return type:

Asset

get_run(rid)#

Retrieve a run by its RID.

Raises:

NominalNotFoundError – If no run has that RID.
NominalError – If the retrieval request fails.

Return type:

Run

get_secret(rid)#

Retrieve a secret by RID.

Raises:: NominalNotFoundError – If no secret with the given RID exists or it is not accessible to the user.
Return type:: Secret

get_unit(unit_symbol)#

Get details of the given unit symbol, or none if the symbol is not recognized by Nominal.

Parameters:

unit_symbol (str)

Symbol of the unit to get metadata for.

Note: This currently requires that units are formatted as laid out in the latest UCUM standards (see https://ucum.org/ucum).

Returns:

Resolved unit metadata if the symbol is valid and supported by Nominal, or None if no such unit symbol matches.

Raises:

NominalError – If the units service request fails for a reason other than an unrecognized symbol.

Return type:

Unit | None

get_user(user_rid=None)#

Retrieve the specified user.

Parameters:

user_rid (str | None)

Rid of the user to retrieve

Returns:

Details on the requested user, or the current user if no user rid is provided.

Raises:

NominalError – If the user request fails, including when the user does not exist or is not a member or guest of the caller’s organization.

Return type:

User

get_video(rid)#

Retrieve a video by its RID.

Return type:: Video

get_videos(rids)#

Retrieve videos by their RID.

Return type:: Sequence[Video]

get_workbook(rid)#

Gets the given workbook by rid.

Return type:: Workbook

get_workbook_template(rid)#

Gets the given workbook template by rid.

Return type:: WorkbookTemplate

get_workspace(workspace_rid=None)#

Get workspace via given RID, or the default workspace if no RID is provided.

Parameters:

workspace_rid (str | None)

If provided, the RID of the workspace to retrieve and validate. If None, resolves the client’s default workspace by first using the configured workspace_rid (for example from config.yml) and then falling back to a client-side default-workspace lookup.

Returns:

Returns details about the requested workspace.

Raises:

NominalConfigError – Raises a NominalConfigError if no workspace provided and no default workspace can be resolved.
NominalNotFoundError – The requested workspace does not exist or is not accessible to the user (the backend does not distinguish the two).

Return type:

Workspace

list_integrations(*, workspace=None)#

List available notification integrations across all result pages.

Parameters:

workspace (WorkspaceSearchType | Workspace | str | None)

Workspace to search. None uses the client’s default; WorkspaceSearchType.ALL searches all accessible workspaces.

Returns:

Integrations visible in the selected workspace scope.

Return type:

Sequence[Integration]

list_streaming_checklists(asset=None)#

List all Streaming Checklists.

Parameters:

asset (Asset | str | None)

if provided, only return checklists associated with the given asset.

Returns:

All streaming checklist RIDs that match the provided conditions

Return type:

Sequence[str]

list_workspaces()#

Return all workspaces visible to the current user.

Raises:: NominalError – If the workspace service request fails.
Return type:: Sequence[Workspace]

search_assets(search_text=None, *, labels=None, properties=None, exact_substring=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)#

Search for assets meeting the specified filters. Filters are ANDed together, e.g. (asset.label == label) AND (asset.search_text =~ field)

Parameters:

search_text (str | None)

Fuzzy match: tokenized across name, description, labels, and properties, with additional substring and similarity matching on name and description, so results need not contain the given text verbatim.
labels (Sequence[str] | None)

A sequence of labels that must ALL be present on a asset to be included.
properties (Mapping[str, str | float] | None)

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.
exact_substring (str | None)

Case-insensitive substring of the asset’s name, description, labels, or properties. Unlike search_text, results always contain the given text verbatim.
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.
archive_status (ArchiveStatusFilter)

Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:

Sequence[Asset]

Note

If WorkspaceSearchType.ALL is given for workspace, the workspace filter is omitted and the search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its configured workspace_rid (for example from config.yml) and otherwise falls back to a client-side default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace RID is given, that value is used directly.

Returns:

All assets which match all of the provided conditions

Raises:

TypeError – If a property value is a boolean or is not a string, integer, or float.
NominalConfigError – If the default workspace is requested but cannot be resolved.
NominalError – If a search request fails.

Return type:

Sequence[Asset]

search_checklists(search_text=None, labels=None, properties=None, author=None, assignee=None, workspace=WorkspaceSearchType.DEFAULT, *, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)#

Search for checklists meeting the specified filters. Filters are ANDed together, e.g. (checklist.label == label) AND (checklist.search_text =~ field)

Parameters:

search_text (str | None)

case-insensitive search for any of the keywords in all string fields
labels (Sequence[str] | None)

A sequence of labels that must ALL be present on a checklist to be included.
properties (Mapping[str, str] | None)

A mapping of key-value pairs that must ALL be present on a checklist to be included.
author (User | str | None)

Author of checklists to search for
assignee (User | str | None)

Assignee of checklists to search for
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.
archive_status (ArchiveStatusFilter)

Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:

Sequence[Checklist]

Note

Returns:: All checklists which match all of the provided conditions
Return type:: Sequence[Checklist]

search_container_images(*, tag=None, status=None, extractor=None, workspace=WorkspaceSearchType.DEFAULT)#

Search for container images meeting the specified filters.

Filters are ANDed together, e.g. (image.tag == tag) AND (image.status == status).

Parameters:

tag (str | None)

If provided, only include images registered with this tag.
status (ContainerImageStatus | None)

If provided, only include images with this status.
extractor (ContainerizedExtractor | str | None)

If provided, only include images filtered to this containerized extractor
workspace (WorkspaceSearchType | Workspace | str | None)

Workspace to search within (the client’s default workspace if not provided).

Returns:

All container images matching all of the provided filters.

Return type:

Sequence[ContainerImage]

search_containerized_extractors(*, include_archived=False, file_extension=None, labels=None, properties=None, workspace=WorkspaceSearchType.DEFAULT)#

Search for containerized extractors meeting the specified filters.

Parameters:

include_archived (bool)

If true, include archived extractors in the results.
file_extension (str | None)

If provided, only include extractors whose active image declares an input accepting files with this suffix (e.g. “csv” — no leading dot).
labels (Sequence[str] | None)

Only include extractors carrying every requested label.
properties (Mapping[str, str] | None)

Only include extractors carrying every requested name/value pair. Extractors may carry additional labels and properties.
workspace (WorkspaceSearchType | Workspace | str | None)

Workspace to search within (the client’s default workspace if not provided).

Returns:

All extractors matching all of the provided filters.

Return type:

Sequence[ContainerizedExtractor]

search_data_reviews(assets=None, runs=None, *, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)#

Search for data reviews meeting the specified filters. Filters are ANDed together, e.g. (data_review.asset == asset) AND (data_review.run == run)

Parameters:

assets (Sequence[Asset | str] | None)

List of assets that must be associated with a data review to be included.
runs (Sequence[Run | str] | None)

List of runs that must be associated with a data review to be included.
archive_status (ArchiveStatusFilter)

Filter by archive status. Defaults to NOT_ARCHIVED.

Returns:

All data reviews which match all of the provided conditions

Return type:

Sequence[DataReview]

search_dataset_files(dataset, *, start=None, end=None, file_tags=None)#

Search for dataset files within a specific dataset. Filters are ANDed together. Time range uses overlap semantics: a file is included if its time range overlaps with [start, end], i.e. file.end >= start AND file.start <= end.

Parameters:

dataset (Dataset | str)

The dataset (or its RID) to search for files within.
start (str | datetime | int | None)

Inclusive lower bound of the search window. Files whose time range ends at or after this timestamp are returned — including files that started before start but still overlap the window. Files ending entirely before start are excluded.

Note: Truncated to whole seconds — sub-second precision is dropped.
end (str | datetime | int | None)

Inclusive upper bound of the search window. Files whose time range starts at or before this timestamp are returned — including files that end after end but still overlap the window. Files starting entirely after end are excluded.

Note: Truncated to whole seconds — sub-second precision is dropped.
file_tags (Mapping[str, str] | None)

A mapping of key-value tag pairs that must ALL be present on a dataset file to be included.

Returns:

All dataset files within the given dataset which match all of the provided conditions

Return type:

Sequence[DatasetFile]

search_datasets(*, exact_match=None, search_text=None, labels=None, properties=None, before=None, after=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)#

Search for datasets meeting the specified filters. Filters are ANDed together, e.g. (dataset.label == label) AND (dataset.property == property)

Parameters:

exact_match (str | None)

Case-insensitive substring of the dataset’s name, description, labels, or properties.
search_text (str | None)

Fuzzy match: tokenized across name, description, labels, and properties, with additional substring and similarity matching on name and description, so results need not contain the given text verbatim.
labels (Sequence[str] | None)

A sequence of labels that must ALL be present on a dataset to be included.
properties (Mapping[str, str | float] | None)

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.
before (str | datetime | int | None)

Searches for datasets ingested before some time (inclusive).
after (str | datetime | int | None)

Searches for datasets ingested after some time (inclusive).
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.
archive_status (ArchiveStatusFilter)

Filter results to the given archive status.

Return type:

Sequence[Dataset]

Note

Returns:: All datasets which match all of the provided conditions
Raises:: TypeError – If a property value is a boolean or is not a string, integer, or float.
Return type:: Sequence[Dataset]

search_events(*, search_text=None, after=None, before=None, assets=None, labels=None, properties=None, created_by=None, workbook=None, data_review=None, assignee=None, event_type=None, priority=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)#

Search for events meeting the specified filters. Filters are ANDed together, e.g. (event.label == label) AND (event.start > before)

Parameters:

search_text (str | None)

Searches for a string in the event’s metadata.
after (datetime | int | None)

Filters to end times after this time, exclusive.
before (datetime | int | None)

Filters to start times before this time, exclusive.
assets (Iterable[Asset | str] | None)

List of assets that must ALL be present on an event to be included.
labels (Iterable[str] | None)

A list of labels that must ALL be present on an event to be included.
properties (Mapping[str, str | float] | None)

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 (User | str | None)

A User (or rid) of the author that must be present on an event to be included.
workbook (Workbook | str | None)

Workbook to search for events on
data_review (DataReview | str | None)

Search for events from the given data review
assignee (User | str | None)

Search for events with the given assignee
event_type (EventType | None)

Search for events based on level
priority (Priority | None)

Filter events by disposition priority. None leaves priority unrestricted.
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.
archive_status (ArchiveStatusFilter)

Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:

Sequence[Event]

Note

If WorkspaceSearchType.ALL is given for workspace (default), the workspace filter is omitted and the search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its configured workspace_rid (for example from config.yml) and otherwise falls back to a client-side default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace RID is given, that value is used directly.

Returns:: All events which match all of the provided conditions
Raises:: TypeError – If a property value is a boolean or is not a string, integer, or float.
Return type:: Sequence[Event]

search_ingestion_jobs(*, datasets=None, created_by=None, statuses=None, search_text=None, start_time_after=None, start_time_before=None, workspace=WorkspaceSearchType.DEFAULT)#

Search ingest jobs. Filters are ANDed together.

Results are limited to datasets the caller can read; jobs without a persisted dataset are never returned by search.

Parameters:

datasets (Sequence[Dataset | str] | None)

Only jobs targeting any of these datasets (or their RIDs).
created_by (Sequence[User | str] | None)

Only jobs created by any of these users or user RIDs.
statuses (Sequence[IngestionJobStatus] | None)

Only jobs in any of these statuses.
search_text (str | None)

Case-insensitive substring match against origin file paths.
start_time_after (str | datetime | int | None)

Only jobs that started at or after this time (inclusive).
start_time_before (str | datetime | int | None)

Only jobs that started before this time (exclusive).
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.

Return type:

Sequence[IngestionJob]

Note

Returns:: All ingest jobs matching all of the provided conditions, most recent first.
Return type:: Sequence[IngestionJob]

search_markings(id_substring=None)#

Search markings in the current organization, oldest first.

Parameters:

id_substring (str | None)

Substring that a marking’s id must contain to be included.

Returns:

All markings matching the given conditions.

Return type:

Sequence[Marking]

Note

Markings are scoped to an organization rather than a workspace, so this search takes no workspace filter. Archived markings are never returned; fetch them by RID with get_marking instead.

search_runs(start=None, end=None, name_substring=None, *, asset=None, run_prefix=None, labels=None, properties=None, exact_match=None, search_text=None, created_after=None, created_before=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)#

Search for runs meeting the specified filters. Filters are ANDed together, e.g. (run.label == label) AND (run.end <= end)

Parameters:

start (str | datetime | int | None)

Inclusive start time for filtering runs.
end (str | datetime | int | None)

Inclusive end time for filtering runs.
name_substring (str | None)

Alias for exact_match: despite the name, this matches a case-insensitive substring of the run’s name, description, labels, or properties. For name-only matching, filter the returned runs on their names.
asset (Asset | str | None)

Filter runs associated with this asset or asset RID.
run_prefix (str | None)

Filter by the stored run prefix, not a substring of the run name.
labels (Sequence[str] | None)

A sequence of labels that must ALL be present on a run to be included.
properties (Mapping[str, str | float] | None)

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.
exact_match (str | None)

Case-insensitive substring of the run’s name, description, labels, or properties.
search_text (str | None)

Fuzzy match: tokenized across name, description, labels, and properties, with additional substring and similarity matching on name and description, so results need not contain the given text verbatim.
created_after (str | datetime | int | None)

Filter runs created after this timestamp (exclusive).
created_before (str | datetime | int | None)

Filter runs created before this timestamp (exclusive).
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.
archive_status (ArchiveStatusFilter)

Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:

Sequence[Run]

Note

Returns:

All runs which match all of the provided conditions

Raises:

TypeError – If a property value is a boolean or is not a string, integer, or float.
NominalConfigError – If the default workspace is requested but cannot be resolved.
NominalError – If a search request fails.

Return type:

Sequence[Run]

search_secrets(search_text=None, labels=None, properties=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)#

Search for secrets meeting the specified filters. Filters are ANDed together, e.g. (secret.label == label) AND (secret.property == property)

Parameters:

search_text (str | None)

Fuzzy match: tokenized across name, description, labels, and properties, with additional substring and similarity matching on name and description, so results need not contain the given text verbatim.
labels (Sequence[str] | None)

A sequence of labels that must ALL be present on a secret to be included.
properties (Mapping[str, str] | None)

A mapping of key-value pairs that must ALL be present on a secret to be included.
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.
archive_status (ArchiveStatusFilter)

Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:

Sequence[Secret]

Note

Returns:: All secrets which match all of the provided conditions
Return type:: Sequence[Secret]

search_users(exact_match=None, search_text=None)#

Search for users meeting the specified filters. Filters are ANDed together, e.g., if exact_match and search_text are both provided, then both must match.

Parameters:

exact_match (str | None)

Searches for an exact (case-insensitive) substring of the user’s email
search_text (str | None)

Searches for a (case-insensitive) substring across display name and email

Returns:

All users which match all of the provided conditions

Raises:

NominalError – If the user search request fails.

Return type:

Sequence[User]

search_videos(search_text=None, labels=None, properties=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)#

Search for videos meeting the specified filters. Filters are ANDed together, e.g. (video.label == label) AND (video.property == property)

Parameters:

search_text (str | None)

Fuzzy match: tokenized across name, description, labels, and properties, with additional substring and similarity matching on name and description, so results need not contain the given text verbatim.
labels (Sequence[str] | None)

A sequence of labels that must ALL be present on a video to be included.
properties (Mapping[str, str] | None)

A mapping of key-value pairs that must ALL be present on a video to be included.
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.
archive_status (ArchiveStatusFilter)

Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:

Sequence[Video]

Note

Returns:: All videos which match all of the provided conditions
Return type:: Sequence[Video]

search_workbook_templates(*, exact_match=None, search_text=None, labels=None, properties=None, created_by=None, archive_status=ArchiveStatusFilter.NOT_ARCHIVED, published=None, workspace=WorkspaceSearchType.DEFAULT)#

Search for workbook templates meeting the specified filters. Filters are ANDed together, e.g. (workbook.label == label) AND (workbook.author_rid == "rid")

Parameters:

exact_match (str | None)

Case-insensitive substring of the template’s title.
search_text (str | None)

Fuzzy (similarity) match against the template’s title or description.
labels (Sequence[str] | None)

A list of labels that must ALL be present on an workbook to be included.
properties (Mapping[str, str] | None)

A mapping of key-value pairs that must ALL be present on an workbook to be included.
created_by (User | str | None)

Searches for workbook templates with the given creator’s rid
archive_status (ArchiveStatusFilter)

Filter results to the given archive status.
published (bool | None)

Searches for workbook templates that have been published if true
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.

Return type:

Sequence[WorkbookTemplate]

Note

Returns:: All workbook templates which match all of the provided conditions
Return type:: Sequence[WorkbookTemplate]

search_workbooks(*, exact_match=None, search_text=None, labels=None, properties=None, asset=None, exact_assets=None, created_by=None, run=None, workspace=WorkspaceSearchType.DEFAULT, include_drafts=False, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)#

Search for workbooks meeting the specified filters. Filters are ANDed together, e.g. (workbook.label == label) AND (workbook.created_by == "rid")

Parameters:

exact_match (str | None)

Case-insensitive substring of the workbook’s title.
search_text (str | None)

Case-insensitive substring of the workbook’s title or description.
labels (Sequence[str] | None)

A list of labels that must ALL be present on an workbook to be included.
properties (Mapping[str, str] | None)

A mapping of key-value pairs that must ALL be present on an workbook to be included.
asset (Asset | str | None)

Searches for workbooks that include the given asset
exact_assets (Sequence[Asset | str] | None)

Searches for workbooks that have the exact given assets
created_by (User | str | None)

Searches for workbooks with the given author
run (Run | str | None)

Searches for workbooks with the given run
workspace (WorkspaceSearchType | Workspace | str | None)

Filters search to given workspace.
include_drafts (bool)

If true, include workbooks in draft state in results.
archive_status (ArchiveStatusFilter)

Archive status to filter results to. Defaults to NOT_ARCHIVED.

Return type:

Sequence[Workbook]

Note

Returns:: All workbooks which match all of the provided conditions
Return type:: Sequence[Workbook]