ALTER TABLE (Databricks SQL)

Alters the schema or properties of a table.

For type changes or renaming columns in Delta Lake see rewrite the data.

To change the comment on a table use COMMENT ON.

If the table is cached, the command clears cached data of the table and all its dependents that refer to it. The cache will be lazily filled when the table or the dependents are accessed the next time.

Required permissions

If you use Unity Catalog you must have MODIFY permission to:

ALTER COLUMN
ADD COLUMN
DROP COLUMN
SET TBLPROPERTIES
UNSET TBLPROPERTIES

All other operations require ownership of the table.

Syntax

ALTER TABLE table_name
   { RENAME TO clause |
     ADD COLUMN clause |
     ALTER COLUMN clause |
     DROP COLUMN clause |
     RENAME COLUMN clause |
     ADD CONSTRAINT clause |
     DROP CONSTRAINT clause |
     ADD PARTITION clause |
     DROP PARTITION clause |
     RENAME PARTITION clause |
     RECOVER PARTITIONS clause |
     SET TBLPROPERTIES clause |
     UNSET TBLPROPERTIES clause |
     SET LOCATION clause |
     OWNER TO clause }

Parameters

table_name

Identifies the table being altered. The name must not include a temporal specification.
RENAME TO to_table_name

Renames the table within the same schema.

Note

If you use AWS Glue Data Catalog as the metastore, RENAME is not supported.
- to_table_name
  
  Identifies the new table name. The name must not include a temporal specification.
ADD COLUMN

This clause is not supported for JDBC data sources.

Adds one or more columns to the table, or fields to existing columns in a Delta Lake table.
```
{ ADD [COLUMN | COLUMNS ]
  ( { {column_identifier | field_name} data_type [COMMENT comment] [FIRST | AFTER identifier] } [, ...] ) }
```
- column_identifier
  
  The name of the column to be added. The name must be unique within the table.
  
  Unless FIRST or AFTER name are specified the column or field will be appended at the end.
- field_name
  
  The fully qualified name of the field to be added to an existing column. All components of the path to the nested field must exist and the field name itself must be unique.
- COMMENT comment
  
  An optional STRING literal describing the added column or field.
- FIRST
  
  If specified the column will be added as the first column of the table, or the field will be added as the first field of in the containing struct.
- AFTER identifier
  
  If specified the column or field will be added immediately after the field or column identifier.
ALTER COLUMN

Changes a property or the location of a column.
```
{ { ALTER | CHANGE } [COLUMN] { column_identifier | field_name }
  { COMMENT comment |
    { FIRST | AFTER column_identifier } |
    { SET | DROP } NOT NULL |
    SYNC IDENTITY } }
```
- column_identifier
  
  The name of the column to be altered.
- field_name
  
  The fully qualified name of the field to be altered. All components of the path to the nested field must exist.
- COMMENT comment
  
  Changes the description of the column_name column. comment must be a STRING literal.
- FIRST or AFTER identifier
  
  Moves the column from its current position to the front (FIRST) or immediately AFTER the identifier. This clause is only supported if table_name is a Delta table.
- SET NOT NULL or DROP NOT NULL
  
  Changes the domain of valid column values to exclude nulls SET NOT NULL, or include nulls DROP NOT NULL. This option is only supported for Delta Lake tables. Delta Lake will ensure the constraint is valid for all existing and new data.
- SYNC IDENTITY
  
  Synchronize the metadata of an identity column with the actual data. When you write your own values to an identity column, it might not comply with the metadata. This option evaluates the state and updates the metadata to be consistent with the actual data. After this command, the next automatically assigned identity value will start from start + (n + 1) * step, where n is the smallest value that satisfies start + n * step >= max() (for a positive step).
  
  This option is only supported for identity columns on Delta Lake tables.
DROP COLUMN

Drop one or more columns or fields in a Delta Lake table.

When you drop a column or field, you must drop dependent check constraints and generated columns.
```
DROP [COLUMN | COLUMNS] [ IF EXISTS ] ( { {column_identifier | field_name} [, ...] )
```
- IF EXISTS
  
  When you specify IF EXISTS, Databricks SQL ignores an attempt to drop columns that do not exist. Otherwise, dropping non-existing columns will cause an error.
- column_identifier
  
  The name of the existing column.
- field_name
  
  The fully qualified name of an existing field.
RENAME COLUMN

Renames a column or field in a Delta Lake table.

When you rename a column or field you also need to change dependent check constraints and generated columns. Any primary keys and foreign keys using the column will be dropped. In case of foreign keys you must own the table on which the foreign key is defined.
```
RENAME COLUMN { column_identifier TO to_column_identifier|
                field_name TO to_field_identifier }
```
- column_identifier
  
  The existing name of the column.
- to_column_identifier
  
  The new column identifier. The identifier must be unique within the table.
- field_name
  
  The existing fully qualified name of a field.
- to_field_identifier
  
  The new field identifier. The identifier must be unique within the local struct.
ADD CONSTRAINT

Adds a check constraint, foreign key constraint, or primary key constraint to the table.

Foreign keys and primary keys are not supported for tables in the hive_metastore catalog.
DROP CONSTRAINT

Drops a primary key, foreign key, or check constraint from the table.
ADD PARTITION

If specified adds one or more partitions to the table. Adding partitions is not supported for Delta Lake tables.
```
ADD [IF NOT EXISTS] { PARTITION clause [ LOCATION path ] } [...]
```
- IF NOT EXISTS
  
  An optional clause directing Databricks SQL to ignore the statement if the partition already exists.
- PARTITION clause
  
  A partition to be added. The partition keys must match the partitioning of the table and be associated with values. If the partition already exists an error is raised unless IF NOT EXISTS has been specified.
- LOCATION path
  
  path must be a STRING literal representing an optional location pointing to the partition.
  
  If no location is specified the location will be derived from the location of the table and the partition keys.
  
  If there are files present at the location they populate the partition and must be compatible with the data_source of the table and its options.
DROP PARTITION

If specified this clause drops one or more partitions from the table, optionally deleting any files at the partitions’ locations.

Delta Lake tables do not support dropping of partitions.
```
DROP [ IF EXISTS ] PARTITION clause [, ...] [PURGE]
```
- IF EXISTS
  
  When you specify IF EXISTS Databricks will ignore an attempt to drop partitions that do not exists. Otherwise, non existing partitions will cause an error.
- PARTITION clause
  
  Specifies a partition to be dropped. If the partition is only partially identified a slice of partitions is dropped.
- PURGE
  
  If set, the table catalog must remove partition data by skipping the Trash folder even when the catalog has configured one. The option is applicable only for managed tables. It is effective only when:
  
  The file system supports a Trash folder. The catalog has been configured for moving the dropped partition to the Trash folder. There is no Trash folder in AWS S3, so it is not effective.
  
  There is no need to manually delete files after dropping partitions.
RENAME PARTITION

Replaces the keys of a partition.

Delta Lake tables do not support renaming partitions.
```
from_partition_clause RENAME TO to_partition_clause
```
- from_partition_clause
  
  The definition of the partition to be renamed.
- to_partition_clause
  
  The new definition for this partition. A partition with the same keys must not already exist.
RECOVER PARTITIONS

This clause does not apply to Delta Lake tables.

Instructs Databricks SQL to scan the table’s location and add any files to the table which have been added directly to the filesystem.
SET TBLPROPERTIES

Sets or resets one or more user defined properties.
UNSET TBLPROPERTIES

Removes one or more user defined properties.
SET LOCATION

Moves the location of a partition or table.

Delta Lake does not support moving individual partitions of a Delta Lake table.
```
[ PARTITION clause ] SET LOCATION path
```
- PARTITION clause
  
  Optionally identifies the partition for which the location will to be changed. If you omit naming a partition Databricks moves the location of the table.
- LOCATION path
  
  path must be a STRING literal. Specifies the new location for the partition or table.
  
  Files in the original location will not be moved to the new location.
OWNER TO principal

Transfers ownership of the table to principal.

Examples

For Delta Lake add, and alter column examples, see

-- RENAME table
> DESCRIBE student;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

> ALTER TABLE Student RENAME TO StudentInfo;

-- After Renaming the table
> DESCRIBE StudentInfo;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL


-- RENAME partition
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=10
    age=11
    age=12

> ALTER TABLE default.StudentInfo PARTITION (age='10') RENAME TO PARTITION (age='15');

-- After renaming Partition
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

-- Add new columns to a table
> DESCRIBE StudentInfo;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL


> ALTER TABLE StudentInfo ADD columns (LastName string, DOB timestamp);

-- After Adding New columns to the table
> DESCRIBE StudentInfo;
                col_name data_type comment
 ----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                LastName    string    NULL
                     DOB timestamp    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

-- Add a new partition to a table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

> ALTER TABLE StudentInfo ADD IF NOT EXISTS PARTITION (age=18);

-- After adding a new partition to the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15
    age=18


-- Drop a partition from the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15
    age=18

> ALTER TABLE StudentInfo DROP IF EXISTS PARTITION (age=18);

-- After dropping the partition of the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15

-- Adding multiple partitions to the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15


> ALTER TABLE StudentInfo ADD IF NOT EXISTS PARTITION (age=18) PARTITION (age=20);

-- After adding multiple partitions to the table
> SHOW PARTITIONS StudentInfo;
 partition
 ---------
    age=11
    age=12
    age=15
    age=18
    age=20


-- ALTER or CHANGE COLUMNS
> DESCRIBE StudentInfo;
                col_name data_type comment
+-----------------------+---------+-------
                    name    string    NULL
                  rollno       int    NULL
                LastName    string    NULL
                     DOB timestamp    NULL
                     age       int    NULL
 # Partition Information
              # col_name data_type comment
                     age       int    NULL

ALTER TABLE StudentInfo ALTER COLUMN name COMMENT "new comment";

--After ALTER or CHANGE COLUMNS
> DESCRIBE StudentInfo;
                col_name data_type     comment
 ----------------------- --------- -----------
                    name    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL
 # Partition Information
              # col_name data_type     comment
                     age       int        NULL

-- RENAME COLUMN
> ALTER TABLE StudentInfo RENAME COLUMN name TO FirstName;

--After RENAME COLUMN
> DESCRIBE StudentInfo;
                col_name data_type     comment
 ----------------------- --------- -----------
               FirstName    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL
 # Partition Information
              # col_name data_type     comment
                     age       int        NULL

-- Change the file Location
> ALTER TABLE dbx.tab1 PARTITION (a='1', b='2') SET LOCATION '/path/to/part/ways'

-- SET TABLE PROPERTIES
> ALTER TABLE dbx.tab1 SET TBLPROPERTIES ('winner' = 'loser');

-- DROP TABLE PROPERTIES
> ALTER TABLE dbx.tab1 UNSET TBLPROPERTIES ('winner');