pola-rs/polars · error · NotImplementedError

write_table: table format of {catalog_name}.{namespace}.{tab

Error message

write_table: table format of {catalog_name}.{namespace}.{table_name} ({data_source_format}) is unsupported.

What it means

NotImplementedError from Catalog.write_table (py-polars/src/polars/catalog/unity/client.py:390-402). Writing through the Unity Catalog integration supports only the DELTA format (handled by the earlier branch that calls into the delta writer with mode/delta_write_options/delta_merge_options). Any other data_source_format (CSV, JSON, PARQUET, UNITY_*) falls into the else branch and is explicitly unsupported at write time, with the fully qualified table name and format in the message.

Source

Thrown at py-polars/src/polars/catalog/unity/client.py:400

        )

        if data_source_format in ["DELTA", "DELTASHARING"]:
            return df.write_delta(  # type: ignore[misc]
                storage_location,
                storage_options=storage_options,
                credential_provider=credential_provider,
                mode=delta_mode,
                delta_write_options=delta_write_options,
                delta_merge_options=delta_merge_options,
            )  # type: ignore[call-overload]

        else:
            msg = (
                "write_table: table format of "
                f"{catalog_name}.{namespace}.{table_name} "
                f"({data_source_format}) is unsupported."
            )
            raise NotImplementedError(msg)

    def create_catalog(
        self,
        catalog_name: str,
        *,
        comment: str | None = None,
        storage_root: str | None = None,
    ) -> CatalogInfo:
        """
        Create a catalog.

        .. warning::
            This functionality is considered **unstable**. It may be changed
            at any point without it being considered a breaking change.

        Parameters
        ----------
        catalog_name

View on GitHub (pinned to df599052da)

Solutions

Write to (or create) a DELTA-format table: CREATE TABLE ... USING DELTA, then call write_table
For non-Delta targets, write directly with polars IO to the storage location (e.g. scan/write parquet with storage_options) instead of the catalog write API
Check the format first: catalog.get_table('cat.ns.tbl').data_source_format == 'DELTA' before write_table

Example fix

# before
catalog.write_table(lf, 'cat.ns.parquet_tbl')  # NotImplementedError

# after
# ensure the target exists as Delta
# spark.sql('CREATE TABLE cat.ns.tbl USING DELTA AS SELECT ...')
catalog.write_table(lf, 'cat.ns.tbl')

Defensive patterns

Strategy: validation

Validate before calling

def writable_via_catalog(table_info) -> bool:
    return str(table_info.data_source_format).endswith('DELTA')

Try / catch

try:
    catalog.write_table(lf, f'{cat}.{ns}.{tbl}')
except NotImplementedError:
    catalog.write_table(lf, f'{cat}.{ns}.{tbl}_delta')  # Delta target instead

Prevention

Verify table format is DELTA before write_table; create targets with USING DELTA
For non-Delta targets write directly with polars IO plus storage_options
Fail fast in pipelines by checking format up front rather than at write time

When it happens

Trigger: catalog.write_table(lf, 'cat.ns.tbl', ...) where the pre-existing table's data_source_format is PARQUET, CSV, or JSON instead of DELTA.

Common situations: Writing to tables auto-created by external tools (Databricks SQL CTAS defaults to Delta, but external/foreign tables often are not); targeting tables created by other engines; assuming format conversion is automatic.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/d3c6eb122d2e0168. Report an issue: GitHub.