Catalog interoperability
Understand the four layers behind a successful zero-copy catalog query.
DataLakeCatalog can expose an external catalog as a ClickHouse database, allowing one
ClickHouse query to combine catalog-backed and native tables. A successful attachment
depends on four distinct layers.
Four layers
| Layer | What it controls | Proof |
|---|---|---|
| Catalog metadata | Namespaces, tables, schemas, locations, and snapshots visible to the catalog identity | SHOW TABLES exposes the expected fully qualified object |
| Object-store access | Permission to read the Parquet/Iceberg objects referenced by metadata | A count and deterministic result hash read actual table data |
| Credential vending | How a catalog or identity service supplies scoped, temporary storage access | Logs/configuration show the intended vending path without exposing the credential |
| Copied-native ownership | Rows physically copied into MergeTree storage and their lifecycle | ClickHouse database ownership, RBAC grants, retention, and deletion process are explicit |
Metadata access does not imply object access. A credential that lists Unity namespaces may still fail when ClickHouse opens the referenced objects. Conversely, object-store permission alone does not provide catalog discovery or snapshot semantics.
Version-sensitive attachment
The workshop templates intentionally contain placeholders:
CREATE DATABASE unity_tpch
ENGINE = DataLakeCatalog('<unity-catalog-uri>')
SETTINGS
catalog_type = 'unity',
warehouse = '<unity-warehouse>',
catalog_credential = '<unity-catalog-credential>',
allow_database_unity_catalog = 1;CREATE DATABASE rest_catalog_tpch
ENGINE = DataLakeCatalog('<rest-catalog-uri>')
SETTINGS
catalog_type = 'rest',
warehouse = '<rest-warehouse>',
catalog_credential = '<rest-catalog-credential>';This DataLakeCatalog syntax, integration availability, setting names, and credential
flows are version-sensitive. Unity integration entered ClickHouse Cloud beta in 25.8,
but a version floor alone is not a compatibility proof. Test the exact delivery service
and settings against both endpoints before the workshop; do not silently enable an
experimental feature. Pass credentials through the approved instructor setup, never
learner chat, committed SQL, or screenshots.
Namespace and hybrid query contract
After attachment, use SHOW TABLES to discover the names ClickHouse exposes. The lab
expects a Unity customer table and REST nation table whose catalog namespaces are part
of the quoted table names. Its native side is the migrated migration_demo.orders
table, so the shipped exercise needs no adapter view.
The three-way query proves composition:
- native hot facts are read from ClickHouse storage;
- Unity metadata and object authorization govern its zero-copy input; and
- the REST fixture's catalog and storage identities govern its zero-copy input.
Record each count/hash and a redacted query plan. Do not describe this as one shared policy plane, and do not imply that MigrationRoom performed the attachments.
Operational boundaries
External catalog freshness follows its published snapshots and integration behavior; native freshness follows the copy or ingestion pipeline. A cross-catalog query can fail because any one metadata, credential-vending, storage, network, or native RBAC boundary fails. Monitor and rotate them independently. ClickHouse is read-only with respect to this workshop's catalog path; writing back through Unity is outside scope.