oss_unity_catalog — Unity Catalog Registration

Helpers for the open-source Unity Catalog implementation (unitycatalog.io). Register tables, schemas, and catalogs against a self-hosted Unity Catalog REST API.

Helpers for the open-source Unity Catalog implementation (unitycatalog.io).

OSS Unity Catalog is the open-source reference catalog server published at https://github.com/unitycatalog/unitycatalog (Docker image unitycatalog/unitycatalog). It exposes a REST API for catalog / schema / table metadata management. Unlike Databricks-managed Unity Catalog it has no native query federation primitive — for live federation to a foreign RDBMS see siege_utilities.trino.federation.

This package’s first surface is siege_utilities.oss_unity_catalog.external_tables, which generates payloads for (and optionally POSTs) external table registrations against the OSS UC REST endpoint POST /api/2.1/unity-catalog/tables.

Filed under SU#521 (umbrella) following the SU#519 rename of the Databricks-only helper.

siege_utilities.oss_unity_catalog.build_external_table_payload(catalog, schema, name, storage_location, data_source_format, columns, *, properties=None, comment=None)[source]

Build the JSON payload for POST /api/2.1/unity-catalog/tables.

Parameters:

  • catalog (str) – Existing OSS UC catalog name.

  • schema (str) – Existing OSS UC schema within catalog.

  • name (str) – Table name to create.

  • storage_location (str) – Absolute URI to the data location (e.g. "s3://bucket/path/persons" or "file:///srv/uc/data/persons").

  • data_source_format (str) – One of SUPPORTED_DATA_SOURCE_FORMATS. Case-insensitive on input; normalized to upper case in the payload.

  • columns (list[Mapping[str, Any]]) – Ordered list of column specs. Each entry must be a Mapping with name (str) and type_name (str — one of OSS UC’s typed column names like LONG, STRING, DOUBLE). Optional per-column: type_text, type_json, nullable (default True), comment, partition_index. position defaults to the column’s index in the list.

  • properties (Mapping[str, str] | None) – Optional table properties (key/value strings).

  • comment (str | None) – Optional human-readable table description.

Returns:

Plain dict ready to be passed to requests.post(..., json=payload).

Raises:

  • ValueError – identifier failed allow-list, format unsupported, or a column spec is malformed.

  • TypeError – a column entry is not a Mapping.

Return type:

dict[str, Any]

siege_utilities.oss_unity_catalog.register_external_table(uc_base_url, payload, *, auth_token=None, timeout=30.0, session=None)[source]

POST payload to {uc_base_url}/api/2.1/unity-catalog/tables.

Thin convenience wrapper around requests.post(). Use this when you have the payload from build_external_table_payload() and want the one-call shape. Callers who prefer to manage their own HTTP client (retry policies, mTLS, proxies, etc.) should build the payload with build_external_table_payload() and POST it themselves.

Parameters:

  • uc_base_url (str) – Base URL of the OSS UC server (e.g. "http://uc.internal:8080"). Trailing slashes are tolerated.

  • payload (Mapping[str, Any]) – A dict in the shape produced by build_external_table_payload().

  • auth_token (str | None) – Optional bearer token. When set, sent as Authorization: Bearer <token>.

  • timeout (float) – Per-request timeout in seconds.

  • session (Session | None) – Optional requests.Session. Useful for connection pooling across many registrations.

Returns:

Parsed JSON response from the server.

Raises:

requests.HTTPError – non-2xx response (via raise_for_status).

Return type:

dict[str, Any]