NominalClient#

class nominal.core.NominalClient(_profile: str | None = None)#

Bases: object

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

Create a connection to the Nominal platform.

Parameters:

base_url – The URL of the Nominal API platform, e.g. “https://api.gov.nominal.io/api”.
token – An API token to authenticate with. If None, the token will be looked up in ~/.nominal.yml.
trust_store_path – 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 – Timeout for any single request to the Nominal API.
workspace_rid – 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 – 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.

create_asset(name: str, description: str | None = None, *, properties: Mapping[str, str | float] | None = None, labels: Sequence[str] = ()) → Asset#

Create an asset.

Parameters:

name – Name of the asset.
description – Human readable description of the asset.
properties – String or numeric properties for the created asset. Integers are stored as floats.
labels – 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.

create_attachment(attachment_file: Path | str, *, description: str | None = None, properties: Mapping[str, str] | None = None, labels: Sequence[str] = ()) → Attachment#

create_attachment_from_io(attachment: BinaryIO, name: str, file_type: tuple[str, str] | FileType = FileTypes.BINARY, description: str | None = None, *, properties: Mapping[str, str] | None = None, labels: Sequence[str] = ()) → Attachment#

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 – Binary stream to upload; the caller retains ownership.
name – 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 – Default extension and MIME type. The default binary type leaves the upload name unchanged.
description – Optional description of the attachment.
properties – Properties to apply to the attachment.
labels – 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.

create_containerized_extractor(name: str, *, description: str | None = None, labels: Sequence[str] | None = None, properties: Mapping[str, str] | None = None) → ContainerizedExtractor#

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 – Name of the extractor.
description – Human-readable description of the extractor.
labels – Labels to set on the extractor.
properties – Key-value properties to set on the extractor.

Returns:

The newly created extractor.

Create an empty dataset.

Parameters:

name – Name of the dataset to create in Nominal.
description – Human readable description of the dataset.
labels – Text labels to apply to the created dataset
properties – String or numeric properties for the created dataset. Integers are stored as floats.
prefix_tree_delimiter – If present, the delimiter to represent tiers when viewing channels hierarchically.
markings – 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.

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

Create an empty video to append video files to.

Parameters:

name – Name of the video to create in Nominal
description – Description of the video to create in nominal
labels – Labels to apply to the video in nominal
properties – Properties to apply to the video in nominal
markings – 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

Create an event.

Parameters:

name – Name of the event.
type – Verbosity level of the event.
start – Starting timestamp of the event.
duration – Duration of the event, or zero for an event without duration.
description – Human readable description of the event.
assets – Assets or asset RIDs associated with the event.
properties – String or numeric properties for the created event. Integers are stored as floats.
labels – Labels to apply to the event.

Raises:

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

create_marking(id: str, *, description: str | None = None, authorized_groups: Sequence[str] = (), symbol: Symbol | None = None, color: str | None = None) → Marking#

Create a marking in the current organization.

Parameters:

id – 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 – Human readable description of the marking.
authorized_groups – RIDs of the groups authorized to access data sources carrying this marking.
symbol – Symbol identifying the marking in the Nominal app.
color – 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.

create_opsgenie_integration(name: str, api_key: str, region: OpsgenieRegion, *, description: str | None = None) → Integration#

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

Parameters:

name – Display name of the integration.
api_key – Opsgenie API key.
region – Region hosting the Opsgenie integration.
description – Optional description.

Returns:

The created integration.

Raises:

NominalConfigError – If no default workspace can be resolved.

create_pagerduty_integration(name: str, routing_key: str, *, description: str | None = None) → Integration#

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

Parameters:

name – Display name of the integration.
routing_key – PagerDuty routing key.
description – Optional description.

Returns:

The created integration.

Raises:

NominalConfigError – If no default workspace can be resolved.

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

Parameters:

name – Name of the run to create
start – Starting timestamp of the run to create
end – Ending timestamp of the run to create, or None for an unbounded run.
description – Optional description of the run to create
properties – String or numeric properties for the created run. Integers are stored as floats.
labels – Optional sequence of labels for the created run
links – Link metadata to add to the created run
attachments – Attachments to associate with the created run
assets – 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.

create_secret(name: str, decrypted_value: str, description: str | None = None, labels: Sequence[str] = (), properties: Mapping[str, str] | None = None) → Secret#

Create a secret for the current user

Parameters:

name – Name of the secret
decrypted_value – Plain text value of the secret
description – Description of the secret
labels – Labels for the secret
properties – Properties for the secret

create_teams_integration(name: str, webhook_url: str, *, description: str | None = None) → Integration#

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

Parameters:

name – Display name of the integration.
webhook_url – Teams webhook URL for notifications.
description – Optional description.

Returns:

The created integration.

Raises:

NominalConfigError – If no default workspace can be resolved.

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

Create an empty video to append video files to.

Parameters:

name – Name of the video to create in Nominal
description – Description of the video to create in nominal
labels – Labels to apply to the video in nominal
properties – Properties to apply to the video in nominal
markings – 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

create_webhook_integration(name: str, webhook_url: str, *, description: str | None = None) → Integration#

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

Parameters:

name – Display name of the integration.
webhook_url – Destination URL for notifications.
description – Optional description.

Returns:

The created integration.

Raises:

NominalConfigError – If no default workspace can be resolved.

Create an empty workbook template.

Parameters:

title – Title of the workbook template
description – Description of the workbook template
labels – Labels to attach to the workbook template
properties – Properties to attach to the workbook template
commit_message – An optional message to include with the creation of the template
is_published – Whether to publish the template so other users can view it. Defaults to False.
workspace – 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

data_review_builder() → DataReviewBuilder#

classmethod from_profile(profile: str, *, trust_store_path: str | None = None, connect_timeout: timedelta | float = DEFAULT_CONNECT_TIMEOUT, extra_headers: HeaderProvider | Mapping[str, str] | None = None) → Self#

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

Parameters:

profile – profile name in the Nominal config.
trust_store_path – 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 – Request connection timeout.
extra_headers – 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.

classmethod from_token(token: str, base_url: str = DEFAULT_API_BASE_URL, *, workspace_rid: str | None = None, trust_store_path: str | None = None, connect_timeout: timedelta | float = DEFAULT_CONNECT_TIMEOUT, extra_headers: HeaderProvider | Mapping[str, str] | None = None, _profile: str | None = None) → Self#

Create a connection to the Nominal platform from a token.

Parameters:

token – Authentication token to use for the connection.
base_url – The URL of the Nominal API platform.
workspace_rid – 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 – 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 – Request connection timeout.
extra_headers – 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.

get_all_units() → Sequence[Unit]#: Retrieve list of metadata for all supported units within Nominal

get_asset(rid: str) → Asset#

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.

get_attachment(rid: str) → Attachment#

Retrieve an attachment by its RID.

Raises:

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

get_attachments(rids: Iterable[str]) → Sequence[Attachment]#

Retrieve attachments by their RIDs.

Raises:

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

get_checklist(rid: str) → Checklist#

get_commensurable_units(unit_symbol: str) → Sequence[Unit]#

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

Raises:: NominalError – If the units service request fails.

get_container_image(rid: str) → ContainerImage#

Get a container image by its RID.

Parameters:: rid – RID of the container image to retrieve.
Returns:: The requested image, e.g. to poll its status after registration.

get_containerized_extractor(rid: str) → ContainerizedExtractor#

Get a containerized extractor by its RID.

Parameters:: rid – RID of the containerized extractor to retrieve.
Returns:: The requested extractor, including its active container image (if any).

get_data_review(rid: str) → DataReview#

Retrieve a data review by its RID.

Raises:

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

get_dataset(rid: str) → Dataset#: Retrieve a dataset by its RID.

get_datasets(rids: Iterable[str]) → Sequence[Dataset]#: Retrieve datasets by their RIDs.

get_datasource(rid: str) → Dataset#: Retrieve a dataset by its RID. Prefer get_dataset for dataset operations.

get_event(rid: str) → Event#

Retrieve an event by its RID.

Raises:: NominalNotFoundError – If no event has that rid.

get_events(rids: Sequence[str]) → Sequence[Event]#

Retrieve events by their RIDs.

Parameters:: rids – 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.

get_ingestion_job(rid: str) → IngestionJob#: Retrieve an ingest job by its RID.

get_integration(rid: str) → Integration#

Retrieve a notification integration by RID.

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

get_marking(rid: str) → Marking#

Retrieve a marking by RID.

Raises:

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

get_marking_by_id(id: str) → Marking#

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.

get_or_create_asset_by_properties(properties: Mapping[str, str | float], *, name: str, description: str | None = None, labels: Sequence[str] = ()) → Asset#

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

Parameters:

properties – String or numeric properties used to search for or create the asset. Integer values are converted to floats.
name – Name of asset to be used if creation is necessary.
description – Description of asset to be used if creation is necessary.
labels – 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.

get_run(rid: str) → Run#

Retrieve a run by its RID.

Raises:

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

get_secret(rid: str) → Secret#

Retrieve a secret by RID.

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

get_unit(unit_symbol: str) → Unit | None#

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

Parameters:

unit_symbol – 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.

get_user(user_rid: str | None = None) → User#

Retrieve the specified user.

Parameters:: user_rid – 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.

get_video(rid: str) → Video#: Retrieve a video by its RID.

get_videos(rids: Iterable[str]) → Sequence[Video]#: Retrieve videos by their RID.

get_workbook(rid: str) → Workbook#: Gets the given workbook by rid.

get_workbook_template(rid: str) → WorkbookTemplate#: Gets the given workbook template by rid.

get_workspace(workspace_rid: str | None = None) → Workspace#

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

Parameters:

workspace_rid – 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).

list_integrations(*, workspace: WorkspaceSearchType | Workspace | str | None = None) → Sequence[Integration]#

List available notification integrations across all result pages.

Parameters:: workspace – Workspace to search. None uses the client’s default; WorkspaceSearchType.ALL searches all accessible workspaces.
Returns:: Integrations visible in the selected workspace scope.

list_streaming_checklists(asset: Asset | str | None = None) → Sequence[str]#

List all Streaming Checklists.

Parameters:: asset – if provided, only return checklists associated with the given asset.
Returns:: All streaming checklist RIDs that match the provided conditions

list_workspaces() → Sequence[Workspace]#

Return all workspaces visible to the current user.

Raises:: NominalError – If the workspace service request fails.

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

Parameters:

search_text – 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 – A sequence of labels that must ALL be present on a asset 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.
exact_substring – Case-insensitive substring of the asset’s name, description, labels, or properties. Unlike search_text, results always contain the given text verbatim.
workspace – Filters search to given workspace.
archive_status – Filter by archive status. Defaults to NOT_ARCHIVED.

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.

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

Parameters:

search_text – case-insensitive search for any of the keywords in all string fields
labels – A sequence of labels that must ALL be present on a checklist to be included.
properties – A mapping of key-value pairs that must ALL be present on a checklist to be included.
author – Author of checklists to search for
assignee – Assignee of checklists to search for
workspace – Filters search to given workspace.
archive_status – Filter by archive status. Defaults to NOT_ARCHIVED.

Note

Returns:: All checklists which match all of the provided conditions

Search for container images meeting the specified filters.

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

Parameters:

tag – If provided, only include images registered with this tag.
status – If provided, only include images with this status.
extractor – If provided, only include images filtered to this containerized extractor
workspace – Workspace to search within (the client’s default workspace if not provided).

Returns:

All container images matching all of the provided filters.

search_containerized_extractors(*, include_archived: bool = False, file_extension: str | None = None, labels: Sequence[str] | None = None, properties: Mapping[str, str] | None = None, workspace: WorkspaceSearchType | Workspace | str | None = WorkspaceSearchType.DEFAULT) → Sequence[ContainerizedExtractor]#

Search for containerized extractors meeting the specified filters.

Parameters:

include_archived – If true, include archived extractors in the results.
file_extension – If provided, only include extractors whose active image declares an input accepting files with this suffix (e.g. “csv” — no leading dot).
labels – Only include extractors carrying every requested label.
properties – Only include extractors carrying every requested name/value pair. Extractors may carry additional labels and properties.
workspace – Workspace to search within (the client’s default workspace if not provided).

Returns:

All extractors matching all of the provided filters.

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

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 – List of assets that must be associated with a data review to be included.
runs – List of runs that must be associated with a data review to be included.
archive_status – Filter by archive status. Defaults to NOT_ARCHIVED.

Returns:

All data reviews which match all of the provided conditions

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 – The dataset (or its RID) to search for files within.
start – 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 – 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 – 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

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

Parameters:

exact_match – Case-insensitive substring of the dataset’s name, description, labels, or properties.
search_text – 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 – A sequence of labels that must ALL be present on a dataset 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.
before – Searches for datasets ingested before some time (inclusive).
after – Searches for datasets ingested after some time (inclusive).
workspace – Filters search to given workspace.
archive_status – Filter results to the given archive status.

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.

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

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.
assets – List of assets that must ALL be present on an event to be included.
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 – A User (or rid) of the author that must be present on an event to be included.
workbook – Workbook to search for events on
data_review – Search for events from the given data review
assignee – Search for events with the given assignee
event_type – Search for events based on level
priority – Filter events by disposition priority. None leaves priority unrestricted.
workspace – Filters search to given workspace.
archive_status – Filter by archive status. Defaults to NOT_ARCHIVED.

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.

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 – Only jobs targeting any of these datasets (or their RIDs).
created_by – Only jobs created by any of these users or user RIDs.
statuses – Only jobs in any of these statuses.
search_text – Case-insensitive substring match against origin file paths.
start_time_after – Only jobs that started at or after this time (inclusive).
start_time_before – Only jobs that started before this time (exclusive).
workspace – Filters search to given workspace.

Note

Returns:: All ingest jobs matching all of the provided conditions, most recent first.

search_markings(id_substring: str | None = None) → Sequence[Marking]#

Search markings in the current organization, oldest first.

Parameters:: id_substring – Substring that a marking’s id must contain to be included.
Returns:: All markings matching the given conditions.

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 for runs meeting the specified filters. Filters are ANDed together, e.g. (run.label == label) AND (run.end <= end)

Parameters:

start – Inclusive start time for filtering runs.
end – Inclusive end time for filtering runs.
name_substring – 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 – Filter runs associated with this asset or asset RID.
run_prefix – Filter by the stored run prefix, not a substring of the run name.
labels – A sequence of labels that must ALL be present on a run 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.
exact_match – Case-insensitive substring of the run’s name, description, labels, or properties.
search_text – 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 – Filter runs created after this timestamp (exclusive).
created_before – Filter runs created before this timestamp (exclusive).
workspace – Filters search to given workspace.
archive_status – Filter by archive status. Defaults to NOT_ARCHIVED.

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.

search_secrets(search_text: str | None = None, labels: Sequence[str] | None = None, properties: Mapping[str, str] | None = None, workspace: WorkspaceSearchType | Workspace | str | None = WorkspaceSearchType.DEFAULT, archive_status: ArchiveStatusFilter = ArchiveStatusFilter.NOT_ARCHIVED) → Sequence[Secret]#

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

Parameters:

search_text – 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 – A sequence of labels that must ALL be present on a secret to be included.
properties – A mapping of key-value pairs that must ALL be present on a secret to be included.
workspace – Filters search to given workspace.
archive_status – Filter by archive status. Defaults to NOT_ARCHIVED.

Note

Returns:: All secrets which match all of the provided conditions

search_users(exact_match: str | None = None, search_text: str | None = None) → Sequence[User]#

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 – Searches for an exact (case-insensitive) substring of the user’s email
search_text – 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.

search_videos(search_text: str | None = None, labels: Sequence[str] | None = None, properties: Mapping[str, str] | None = None, workspace: WorkspaceSearchType | Workspace | str | None = WorkspaceSearchType.DEFAULT, archive_status: ArchiveStatusFilter = ArchiveStatusFilter.NOT_ARCHIVED) → Sequence[Video]#

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

Parameters:

search_text – 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 – A sequence of labels that must ALL be present on a video to be included.
properties – A mapping of key-value pairs that must ALL be present on a video to be included.
workspace – Filters search to given workspace.
archive_status – Filter by archive status. Defaults to NOT_ARCHIVED.

Note

Returns:: All videos which match all of the provided conditions

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 – Case-insensitive substring of the template’s title.
search_text – Fuzzy (similarity) match against the template’s title or description.
labels – A list of labels that must ALL be present on an workbook to be included.
properties – A mapping of key-value pairs that must ALL be present on an workbook to be included.
created_by – Searches for workbook templates with the given creator’s rid
archive_status – Filter results to the given archive status.
published – Searches for workbook templates that have been published if true
workspace – Filters search to given workspace.

Note

Returns:: All workbook templates which match all of the provided conditions

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

Parameters:

exact_match – Case-insensitive substring of the workbook’s title.
search_text – Case-insensitive substring of the workbook’s title or description.
labels – A list of labels that must ALL be present on an workbook to be included.
properties – A mapping of key-value pairs that must ALL be present on an workbook to be included.
asset – Searches for workbooks that include the given asset
exact_assets – Searches for workbooks that have the exact given assets
created_by – Searches for workbooks with the given author
run – Searches for workbooks with the given run
workspace – Filters search to given workspace.
include_drafts – If true, include workbooks in draft state in results.
archive_status – Archive status to filter results to. Defaults to NOT_ARCHIVED.

Note

Returns:: All workbooks which match all of the provided conditions