# 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*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### 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`](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerizedExtractor.md#nominal.core.ContainerizedExtractor.set_active_image "nominal.core.ContainerizedExtractor.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*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to a `docker save` tarball of the extractor image, built for linux/amd64.
    - **tag** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Tag to register the image under.
    - **inputs** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*FileExtractionInput*](https://dev.nominal.io/python/ref/generated/nominal.core.FileExtractionInput.md#nominal.core.FileExtractionInput "nominal.core.container_image.FileExtractionInput")*]*)

      Input files the extractor consumes.
    - **default_timestamp_column** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      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*](https://dev.nominal.io/python/ref/generated/nominal.ts.Iso8601.md#nominal.ts.Iso8601 "nominal.ts.Iso8601") *|* [*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Relative*](https://dev.nominal.io/python/ref/generated/nominal.ts.Relative.md#nominal.ts.Relative "nominal.ts.Relative") *|* [*Custom*](https://dev.nominal.io/python/ref/generated/nominal.ts.Custom.md#nominal.ts.Custom "nominal.ts.Custom") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'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`](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImage.md#nominal.core.ContainerImage.default_timestamp_metadata "nominal.core.ContainerImage.default_timestamp_metadata") for the full resolution order.
    - **output_format** ([*FileOutputFormat*](https://dev.nominal.io/python/ref/generated/nominal.core.FileOutputFormat.md#nominal.core.FileOutputFormat "nominal.core.container_image.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*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*FileExtractionParameter*](https://dev.nominal.io/python/ref/generated/nominal.core.FileExtractionParameter.md#nominal.core.FileExtractionParameter "nominal.core.container_image.FileExtractionParameter")*]*)

      Scalar parameters passed to the extractor.
    - **exit_code_mappings** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*ExitCodeMapping*](https://dev.nominal.io/python/ref/generated/nominal.core.ExitCodeMapping.md#nominal.core.ExitCodeMapping "nominal.core.container_image.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*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerResources.md#nominal.core.ContainerResources "nominal.core.container_image.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`](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerizedExtractor.md#nominal.core.ContainerizedExtractor.set_active_image "nominal.core.ContainerizedExtractor.set_active_image") polls it to readiness before activating (or use
    [`ContainerImage.poll_until_ready`](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImage.md#nominal.core.ContainerImage.poll_until_ready "nominal.core.ContainerImage.poll_until_ready") directly).

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `output_format` is not currently ingestible via containerized extraction.
    - [**NominalAlreadyExistsError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalAlreadyExistsError.md#nominal.exceptions.NominalAlreadyExistsError "nominal.exceptions.NominalAlreadyExistsError") – If an image with this tag is already registered for this
      extractor.
    - [**NominalInvalidArgumentError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalInvalidArgumentError.md#nominal.exceptions.NominalInvalidArgumentError "nominal.exceptions.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*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImage.md#nominal.core.ContainerImage "nominal.core.container_image.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*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      If provided, only include images registered with this tag
    - **status** ([*ContainerImageStatus*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImageStatus.md#nominal.core.ContainerImageStatus "nominal.core.container_image.ContainerImageStatus") *|* *None*)

      If provided, only include images with this status

Returns:
:   All container images matching all of the provided filters.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*ContainerImage*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImage.md#nominal.core.ContainerImage "nominal.core.container_image.ContainerImage")]

### set_active_image(image, *, poll_until_ready=True)

Select the container image this extractor runs when ingesting.

Parameters:
:   - **image** ([*ContainerImage*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImage.md#nominal.core.ContainerImage "nominal.core.container_image.ContainerImage") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Image (or RID of one) to activate. Must be registered against this extractor.
    - **poll_until_ready** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      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**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalContainerImageError.md#nominal.exceptions.NominalContainerImageError "nominal.exceptions.NominalContainerImageError") – If the image is not READY (or, when polling, reaches a state
    from which it cannot become READY).

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### 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*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      New name of the extractor.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      New description of the extractor.
    - **is_archived** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      New archived state of the extractor.
    - **active_container_image** ([*ContainerImage*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImage.md#nominal.core.ContainerImage "nominal.core.container_image.ContainerImage") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Registered container image the extractor should run.
    - **labels** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Labels replacing the existing ones. An empty sequence clears them.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

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

Returns:
:   This instance, refreshed with the updated values.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

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