Your one-second column rename broke three things you didn't check

Stop rewriting terabytes to rename a column

Delta Lake column mapping decouples logical column names from physical Parquet files, so renames and drops become metadata-only operations—but the switch bumps the table protocol and has three documented blast radii. Flip it with a checklist, not a whim.

ALTER TABLE demo.events SET TBLPROPERTIES ('delta.columnMapping.mode' = 'name');
-- 'name' mode: the only mode allowed on an EXISTING table ('id' mode must be set at creation).
-- Prereq: reader version 2+ / writer version 5+; every reader needs Databricks Runtime 10.4 LTS+.
ALTER TABLE demo.events RENAME COLUMN full_name TO customer_name;  -- metadata-only, no files rewritten
ALTER TABLE demo.events DROP COLUMN signup_ts;                      -- metadata-only, no files rewritten

Illustrative walkthrough

Illustrative scenario: a two-row Delta table needs a logical rename and drop. The setup is deliberately rerunnable. Expected results describe shapes only; they are not measured results.

1. Setup a fresh table—mapping off by default

CREATE OR REPLACE TABLE demo.colmap_demo (
  user_id BIGINT,
  full_name STRING,
  signup_ts TIMESTAMP
) USING DELTA;

INSERT INTO demo.colmap_demo VALUES
  (1, 'Amara Osei', TIMESTAMP '2026-09-01 10:00:00'),
  (2, 'Lena Marsh', TIMESTAMP '2026-09-02 11:30:00');

2. Gate 0—confirm the current mode

SHOW TBLPROPERTIES demo.colmap_demo ('delta.columnMapping.mode');

3. Enable name mode, then rename and drop

ALTER TABLE demo.colmap_demo
SET TBLPROPERTIES ('delta.columnMapping.mode' = 'name');

ALTER TABLE demo.colmap_demo RENAME COLUMN full_name TO customer_name;
ALTER TABLE demo.colmap_demo DROP COLUMN signup_ts;
DESCRIBE demo.colmap_demo;

The three breakage checks

1. Streaming reads

Non-additive schema changes—renames and drops—can break streaming reads. The documented fix is a schemaTrackingLocation for each streaming read, inside the target's checkpointLocation directory, with unique subdirectories per source table.

1. Stop the active stream.
2. Enable column mapping.
3. Restart once to initialize mapping.
4. Restart again to enable schema changes.
5. Restart after every later rename, drop, add, or type change.

2. Partitioned directory names

Partitioned tables with column mapping use random prefixes instead of column names for partition directories. Legacy readers that infer partitions from directory names break.

3. Change data feed downstream

The documentation lists downstream change data feed operations as a breakage risk. Check the CDF interoperability documentation before flipping the switch; see Issue 019 for CDF mechanics.

Gate 1—fleet audit, not a row count

SHOW TBLPROPERTIES demo.colmap_demo ('delta.columnMapping.mode');
DESCRIBE DETAIL demo.colmap_demo;

delta.columnMapping.mode must read name. DESCRIBE DETAIL must show minReaderVersion = 2 and minWriterVersion = 5. Every reader and writer on the table must run Databricks Runtime 10.4+. One legacy reader that cannot be upgraded means: do not enable—the way back rewrites everything.

The reversal, priced honestly

ALTER TABLE demo.colmap_demo
SET TBLPROPERTIES ('delta.columnMapping.mode' = 'none');

Removing mapping rewrites all data files, offers no row-level or physical conflict resolution, and concurrent writes throw ConcurrentModificationException. Prepare exactly as the documentation recommends: pause all concurrent writes—including streaming jobs and ETL—turn off predictive optimization, and schedule a low-activity window.

On Databricks Runtime 15.4 LTS+, DROP FEATURE additionally downgrades the table protocol for readers stuck on Databricks Runtime 10.3 and below. Random partition-directory prefixes are not removed by the reversal.

1. Inventory readers: every reader and writer on Databricks Runtime 10.4+? Any legacy directory-name readers or CDF consumers? If yes and unfixable—stop.
2. Pick the mode: id on new tables, Databricks' recommended mode; name on existing tables because id cannot be set on an existing table.
3. Enable and confirm: use ALTER, verify with SHOW TBLPROPERTIES, and note minReaderVersion 2 / minWriterVersion 5 in DESCRIBE DETAIL.
4. Prepare streaming sources: stop the stream first; use one schemaTrackingLocation per source inside the checkpointLocation directory; restart twice.
5. Rename or drop with plain DDL: then verify downstream, not just the table.
6. Write the reversal plan first: removal rewrites all files; pause writes; disable predictive optimization; use a low-activity window; on Databricks Runtime 15.4+ use DROP FEATURE for protocol downgrade.

Use this when

1. Renaming or dropping columns on a large table where a full rewrite is too expensive.
2. Ingesting CSV or JSON with spaces or special characters—, ; { } ( ), newline, tab, or =—in headers, so you can map them directly instead of renaming on ingest.
3. A schema must evolve—renames for clarity or logically dropping PII columns—without downtime.
4. Creating new tables where future renames are likely; set id mode at creation, Databricks' recommended mode.

Avoid this when

1. Any reader runs below Databricks Runtime 10.4 and cannot be upgraded. It loses the table, and the way back rewrites everything.
2. Legacy tools read partition directories by column name. Mapping replaces them with random prefixes.
3. A change-data-feed pipeline consumes the table. The docs flag downstream CDF operations as a breakage risk; Issue 019's cutover assumes a stable read path.
4. An active streaming source has no plan. Do not enable mid-flight without schemaTrackingLocation and the two-restart sequence.