ALTER TABLE ALTER COLUMN SET METADATA

Sets or updates JSON metadata on a column for type widening tracking, custom annotations, or feature-specific hints.

Category: ddlDeltaForge extension

Syntax

ALTER TABLE <table> ALTER COLUMN <column> SET METADATA '<json>'

Description

## Overview Sets arbitrary JSON metadata on a column in the Delta schema. Column metadata is stored in the Parquet/Delta schema metadata map alongside the column definition. This command is primarily used for: - **Type widening tracking**: Recording `delta.typeChanges` entries when a column's type has been widened (e.g., INT to BIGINT). The Delta reader uses this metadata to cast values from older Parquet files. - **Custom annotations**: Tagging columns with PII flags, encryption requirements, data classification labels, or other application-specific metadata. - **Feature-specific metadata**: Storing hints for row tracking, clustering, or other Delta features. ## Behavior - The column must exist in the table's current schema. If the column is not found, the command fails. - The JSON string is parsed and validated before being applied. Invalid JSON causes the command to fail with a descriptive error. - The metadata is merged with any existing column metadata. Existing keys that are not present in the new JSON are preserved; keys present in both are overwritten with the new values. - This is a metadata-only operation. No data files are rewritten. ## Compatibility This is a DeltaForge extension. Column metadata is stored in the standard Delta schema metadata map, which is compatible with all Delta readers. However, custom keys are specific to DeltaForge and may be ignored by other Delta implementations.

Parameters

Name	Type	Description
`table`		Fully qualified table name or registered table name. The table must be registered in the current session.
`column_name`		Column to alter.
`metadata_json`		JSON metadata string.

Examples

-- Track type widening from INT to BIGINT
ALTER TABLE warehouse.sales.products
ALTER COLUMN product_id
SET METADATA '{"delta.typeChanges":[{"toType":"long","fromType":"integer","tableVersion":5}]}';

-- Set custom PII annotation
ALTER TABLE warehouse.sales.customers
ALTER COLUMN email
SET METADATA '{"pii": "true", "encryption": "AES-256"}';

-- Add a data classification tag to a column
ALTER TABLE warehouse.sales.orders
ALTER COLUMN total_amount
SET METADATA '{"classification": "financial", "sensitivity": "high"}';

Pitfalls

The JSON string must contain only string values. Nested objects or non-string values cause a parse error.
Overwriting delta.typeChanges metadata without including existing entries can break type widening reads for older Parquet files.
Column metadata is not validated against any schema. Typos in key names (e.g., 'pI' instead of 'pii') are silently accepted.