Persistently registers an existing Delta table under a fully qualified zone.schema.table name. LOCATION must be a relative path under the zone's storage_root. The caller is automatically granted admin on the new catalog entry.
REGISTER DELTA TABLE <zone>.<schema>.<table> LOCATION '<relative_path>'## Overview Writes a persistent catalog row for an existing Delta table located under the named zone's storage_root, makes the table queryable in the current session immediately, and grants admin on the new catalog row to the user running the command. This is the catalog-persisted counterpart to OPEN DELTA TABLE: the registration survives across sessions, CLI invocations, and compute-node restarts. Use REGISTER DELTA TABLE when the data already exists at a known location (for example, written by an external job, an earlier CREATE DELTA TABLE, or a cross-cluster handoff) and you want it to appear in the catalog under a stable three-part name without copying or rewriting any data. ## Why DELTA is in the keyword REGISTER DELTA TABLE is Delta-only by design. The three-keyword opener matches the rest of the Delta-table command family (CREATE DELTA TABLE, OPEN DELTA TABLE, DROP DELTA TABLE) so the surface stays self-documenting. There is no FORMAT clause; non-Delta data is loaded through CREATE EXTERNAL TABLE which owns the OPTIONS surface those formats need (header, delimiter, partition discovery, schema overrides). ## Behavior - The table name must be a fully qualified `zone.schema.table`. One- or two-part names are rejected. For a session-only attach use OPEN DELTA TABLE. - LOCATION must be a relative path. It is joined onto the zone's `storage_root` to produce the on-disk (or in-cloud) path the table lives at. `..` traversal in the relative fragment is clamped so it cannot escape the zone root. - Absolute filesystem paths, UNC paths, and cloud URLs are rejected outright. REGISTER DELTA TABLE is not a tool for stitching cross-storage layouts into one catalog; that would defeat the zone abstraction and break when the zone is moved or its storage_root is changed. Use OPEN DELTA TABLE for an out-of-zone session attach. - The resolved path is validated: REGISTER refuses to write the catalog row unless `_delta_log/00000000000000000000.json` exists at the resolved location. This prevents a poisoned catalog row that would crash future sessions. - On success: - The table is registered with the current DataFusion session via the cloud-aware engine, so subsequent statements in the same script can query it without a SYNC CATALOG. - A `tables` row is written to the control-plane catalog over the compute node's HMAC-signed channel. The compute node identity, not the user's bearer token, performs the write. - The calling user receives an `admin` grant on the new catalog entry, the same ownership contract CREATE DELTA TABLE applies. - The schema observer fires immediately, populating `information_schema.columns` so BI tools and catalog browsers see the schema without a separate DETECT SCHEMA. - The catalog epoch advances (Postgres trigger on `tables`, in-process EventBus publish, plus the SQL executor's `needs_catalog_sync` flag), so every other compute session refreshes its permission token and provider caches, and ODBC clients refetch their info_schema snapshot. ## Idempotency If a row already exists for the same `zone.schema.table`, the control plane short-circuits with a success response and does not overwrite the existing entry. The session-side registration is still applied (so the table is queryable in this session). To re-point a registered table at a different LOCATION, UNREGISTER first. ## Compute-node token vs. user token The catalog write itself is performed by the compute node using its HMAC-signed identity (`Authorization: HMAC <opaque>`), not the user's bearer token. The admin grant that follows is attributed to the user running the command. This split mirrors how CREATE DELTA TABLE persists its catalog row. ## REGISTER DELTA TABLE vs. OPEN DELTA TABLE | Aspect | REGISTER DELTA TABLE | OPEN DELTA TABLE | |-------------------|---------------------------------------|---------------------------| | Persistence | Catalog-persisted, survives sessions | Session-scoped only | | Name | Three-part `zone.schema.table` only | Any alias | | LOCATION | Relative, under the zone | Absolute, cloud URL, or relative | | Catalog row | Yes | No | | Admin grant | Yes, to the caller | No | | Epoch bump | Yes | No | | Schema in catalog | Yes (auto) | No | ## Compatibility REGISTER DELTA TABLE is a DeltaForge extension. It provides a declarative attach for existing Delta data into the catalog namespace without data movement.
| Name | Type | Description |
|---|---|---|
table_name | Fully qualified three-part name 'zone.schema.table'. The zone must already exist; the schema is auto-created if missing. One- or two-part names are rejected (use OPEN DELTA TABLE for a session-only attach under a bare alias). | |
location | Relative path under the zone's storage_root pointing at an existing Delta table directory (one containing _delta_log/). Examples: 'events', 'bronze/raw/events', 'sales_2024'. Absolute filesystem paths (/data/..., C:/...), UNC paths (//host/share/...), and cloud URLs (s3://, abfss://, gs://, file://) are rejected; the catalog row's location is intended to be re-resolved against the zone on every read, so baking in an absolute or cross-storage layout is not allowed. Use OPEN DELTA TABLE for a session-only attach of an out-of-zone path. '..' traversal in the relative fragment is clamped at the zone root. |
-- Register an existing Delta table under a relative path in the zone
REGISTER DELTA TABLE bronze.raw.events LOCATION 'events';-- Register a nested subfolder under the zone
REGISTER DELTA TABLE bronze.raw.orders LOCATION 'sales/2024/orders';-- Register several tables in one script; epoch is seeded after each so subsequent statements see the new rows
REGISTER DELTA TABLE gold.analytics.daily_revenue LOCATION 'analytics/daily_revenue';
REGISTER DELTA TABLE gold.analytics.monthly_summary LOCATION 'analytics/monthly_summary';
SELECT COUNT(*) FROM gold.analytics.daily_revenue;-- Re-point a registered table at a different relative path (within the same zone)
UNREGISTER TABLE silver.curated.customers;
REGISTER DELTA TABLE silver.curated.customers LOCATION 'customers_v2';