ContainerizedExtractor#

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

Bases: HasRid, RefreshableGrpcMixin[ContainerizedExtractor]

A v2 (Nominal-hosted) containerized extractor (nominal.ingest.v2).

rid: str#
name: str#
description: str | None#
is_archived: bool#
active_image: ContainerImage | None#
created_at: IntegralNanosecondsUTC#
labels: Sequence[str]#
properties: Mapping[str, str]#
archive() → None#

Archive this extractor.

Archived extractors are hidden from search by default and reject new ingests.

refresh() → Self#
register_image(tarball: Path | str, *, tag: str, inputs: Sequence[FileExtractionInput], default_timestamp_column: str, default_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'], output_format: FileOutputFormat = FileOutputFormat.PARQUET, parameters: Sequence[FileExtractionParameter] = (), exit_code_mappings: Sequence[ExitCodeMapping] = (), resources: ContainerResources | None = None) → ContainerImage#

Upload a docker save tarball and register it as a container image for this extractor.

Registering attaches the image to this extractor in Nominal’s registry, but does not change which image the extractor runs: the new image must be activated with set_active_image. This extractor instance is unmodified. Tags are immutable — registering an already-registered tag raises NominalAlreadyExistsError.

Nominal runs extractor images on amd64, so build with --platform linux/amd64. Registration does not check the tarball’s architecture: an arm64 image (the default on Apple Silicon) registers and activates, then fails at ingest with an exec format error.

Parameters:

  • tarball – Path to a docker save tarball of the extractor image, built for linux/amd64.

  • tag – Tag to register the image under.

  • inputs – Input files the extractor consumes.

  • default_timestamp_column – Name of the column containing timestamp data in the extractor’s output files, when no more specific timestamp metadata applies — see default_timestamp_type.

  • default_timestamp_type – How timestamps in that column are interpreted. Together with default_timestamp_column, stored as the image’s default_timestamp_metadata — the fallback timestamp encoding for data ingested through this extractor; required at registration even when every ingest overrides it. See ContainerImage.default_timestamp_metadata for the full resolution order.

  • output_format – File format the extractor writes. Must be one of REGISTERABLE_OUTPUT_FORMATS — the backend cannot currently ingest the others, so registering an image with one would produce an extractor whose ingests always fail.

  • parameters – Scalar parameters passed to the extractor.

  • exit_code_mappings – Fallback canonical errors for failed container exit codes. A valid structured error in /dev/termination-log takes precedence over these mappings. Defaults to no mappings.

  • resources – Compute resource overrides for this image’s extractor container. Fields left as None use deployment-wide defaults. Defaults to no overrides.

Returns:

The newly registered image. Current backends push the image to the registry within this call and return it READY; if a backend processes asynchronously (a non-READY image), set_active_image polls it to readiness before activating (or use ContainerImage.poll_until_ready directly).

Raises:

  • ValueError – If output_format is not currently ingestible via containerized extraction.

  • NominalAlreadyExistsError – If an image with this tag is already registered for this extractor.

  • NominalInvalidArgumentError – If a resources field is outside its documented bounds. The server enforces these, so this surfaces only after the tarball is uploaded.

search_container_images(*, tag: str | None = None, status: ContainerImageStatus | None = None) → Sequence[ContainerImage]#

Search for container images associated with this extractor

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

Returns:

All container images matching all of the provided filters.

set_active_image(image: ContainerImage | str, *, poll_until_ready: bool = True) → Self#

Select the container image this extractor runs when ingesting.

Parameters:

  • image – Image (or RID of one) to activate. Must be registered against this extractor.

  • poll_until_ready – If true, block until the image has finished processing before activating it. If false, raise immediately if the image is not READY.

Returns:

This instance, refreshed with the newly activated image.

Raises:

NominalContainerImageError – If the image is not READY (or, when polling, reaches a state from which it cannot become READY).

unarchive() → None#

Unarchive this extractor, making it available for searching and ingesting once more.

update(*, name: str | None = None, description: str | None = None, is_archived: bool | None = None, active_container_image: ContainerImage | str | None = None, labels: Iterable[str] | None = None, properties: Mapping[str, str] | None = None) → Self#

Update the extractor in-place.

Parameters:

  • name – New name of the extractor.

  • description – New description of the extractor.

  • is_archived – New archived state of the extractor.

  • active_container_image – Registered container image the extractor should run.

  • labels – Labels replacing the existing ones. An empty sequence clears them.

  • properties – Key-value properties replacing the existing ones. An empty mapping clears them.

Returns:

This instance, refreshed with the updated values.

Note

Arguments left as None are omitted and the corresponding fields are unchanged. Name and description cannot be cleared. Labels and properties are replaced rather than appended; merge them before calling to retain existing values.