ContainerizedExtractor

class nominal.core.ContainerizedExtractor(rid, name, description, is_archived, active_image, created_at, labels, properties)

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()

Archive this extractor.

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

refresh()

Return type:

Self

register_image(tarball, *, tag, inputs, default_timestamp_column, default_timestamp_type, output_format=FileOutputFormat.PARQUET, parameters=(), exit_code_mappings=(), resources=None)

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 | str)

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

• tag (str)

  Tag to register the image under.

• inputs (Sequence[FileExtractionInput])

  Input files the extractor consumes.

• default_timestamp_column (str)

  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 (Iso8601 | Epoch | Relative | Custom | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days'])

  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 (FileOutputFormat)

  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 (Sequence[FileExtractionParameter])

  Scalar parameters passed to the extractor.

• exit_code_mappings (Sequence[ExitCodeMapping])

  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 (ContainerResources | None)

  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.

Return type:

ContainerImage

search_container_images(*, tag=None, status=None)

Search for container images associated with this extractor

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

Returns:

All container images matching all of the provided filters.

Return type:

Sequence[ContainerImage]

set_active_image(image, *, poll_until_ready=True)

Select the container image this extractor runs when ingesting.

Parameters:

• image (ContainerImage | str)

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

• poll_until_ready (bool)

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

Return type:

Self

unarchive()

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

update(*, name=None, description=None, is_archived=None, active_container_image=None, labels=None, properties=None)

Update the extractor in-place.

Parameters:

• name (str | None)

  New name of the extractor.

• description (str | None)

  New description of the extractor.

• is_archived (bool | None)

  New archived state of the extractor.

• active_container_image (ContainerImage | str | None)

  Registered container image the extractor should run.

• labels (Iterable[str] | None)

  Labels replacing the existing ones. An empty sequence clears them.

• properties (Mapping[str, str] | None)

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

Returns:

This instance, refreshed with the updated values.

Return type:

Self

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.