ALTER TABLE (Databricks SQL)

Изменяет схему или свойства таблицы.

Сведения о том, как изменять типы или имена столбцов в Delta Lake см. в статье Перезапись данных.

Чтобы изменить комментарий для таблицы, используйте оператор COMMENT ON.

Если таблица кэшируется, команда очищает кэшированные данные таблицы и все зависимые от нее параметры. Кэш будет неактивно заполняться при следующем обращении к таблице или зависимым параметрам.

Необходимые разрешения

Если вы используете каталог Unity, вам необходимо разрешение MODIFY на выполнение следующих действий:

  • ALTER COLUMN
  • ADD COLUMN
  • DROP COLUMN
  • SET TBLPROPERTIES
  • UNSET TBLPROPERTIES

Для всех остальных операций необходимо быть владельцем таблицы.

Синтаксис

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 }

Параметры

  • table_name

    Определяет таблицу, которую нужно изменить. Имя не должно содержать временную спецификацию.

  • RENAME TO to_table_name

    Переименовывает таблицу, сохраняя для нее прежнюю схему.

  • ADD COLUMN

    Это предложение не поддерживается для источников данных JDBC.

    Добавляет один или несколько столбцов в таблицу или одно или несколько полей в существующие столбцы в таблице Delta Lake.

    { ADD [COLUMN | COLUMNS ]
      ( { {column_identifier | field_name} data_type [COMMENT comment] [FIRST | AFTER identifier] } [, ...] ) }
    
    • column_identifier

      Имя добавляемого столбца. Имя должно быть уникальным в пределах таблицы.

      Если не указаны параметры FIRST и AFTER name, новый столбец или новое поле будут добавлены в конец.

    • field_name

      Полное имя поля, которое будет добавлено к существующему столбцу. Должны существовать все компоненты пути вплоть до уровня вложенности нового поля, а само имя поля должно быть уникальным.

    • Комментарий COMMENT

      Необязательное литеральное выражение STRING, которое описывает добавляемый столбец или поле.

    • FIRST

      Если указан этот параметр, столбец будет добавлен на первую позицию в таблице или поле будет добавлено на первую позицию в содержащей его структуре.

    • AFTER identifier

      Если указан этот параметр, то столбец или поле будет добавлены сразу после поля или столбца с идентификатором identifier.

  • ALTER COLUMN

    Изменяет свойство или расположение столбца.

    { { ALTER | CHANGE } [COLUMN] { column_identifier | field_name }
      { COMMENT comment |
        { FIRST | AFTER column_identifier } |
        { SET | DROP } NOT NULL |
        SYNC IDENTITY } }
    
    • column_identifier

      Имя столбца, который требуется изменить.

    • field_name

      Полное имя изменяемого поля. Должны существовать все компоненты пути к вложенному полю.

    • Комментарий COMMENT

      Изменяет описание столбца column_name. comment должен быть СТРОКОВЫМ литералом.

    • FIRST или AFTER identifier

      Перемещает столбец из текущего положения на первую позицию (FIRST) или сразу после указанного элемента (AFTERidentifier). Это предложение поддерживается, только если table_name указывает на таблицу Delta.

    • SET NOT NULL или DROP NOT NULL

      Изменяет домен допустимых значений столбца, чтобы исключить значения NULL (SET NOT NULL) или включить значения NULL (DROP NOT NULL). Эта возможность поддерживается только для таблиц Delta Lake. Delta Lake будет отслеживать соблюдение этого ограничения для всех существующих и новых данных.

    • SYNC IDENTITY

      Синхронизируйте метаданные для столбца идентификаторов с фактическими данными. Если вы сохраняете собственные значения в столбец идентификаторов, они могут не соответствовать метаданным. Этот механизм оценивает состояние и обновляет метаданные в соответствии с фактическими данными. После выполнения этой команды следующее автоматически назначенное значение идентификатора будет начинаться с позиции start + (n + 1) * step, где n — наименьшее значение, удовлетворяющее start + n * step >= max() (для положительного шага).

      Этот механизм поддерживается только для столбцов идентификаторов в таблицах Delta Lake.

  • DROP COLUMN

    Важно!

    Эта функция предоставляется в режиме общедоступной предварительной версии.

    Удаляет один или несколько столбцов или полей в таблице Delta Lake.

    При удалении столбца или поля также нужно удалить все зависимые проверочные ограничения и автоматически создаваемые столбцы.

    Требования см. в статье Сопоставление столбцов в Azure Databricks.

    DROP [COLUMN | COLUMNS] [ IF EXISTS ] ( { {column_identifier | field_name} [, ...] )
    
    • IF EXISTS

      Если указан параметр IF EXISTS, Databricks SQL игнорирует попытки удаления несуществующих столбцов. В противном случае удаление несуществующих столбцов вызовет ошибку.

    • column_identifier

      Имя существующего столбца.

    • field_name

      Полное имя существующего поля.

  • RENAME COLUMN

    Важно!

    Эта функция предоставляется в режиме общедоступной предварительной версии.

    Переименовывает столбец или поле в таблице Delta Lake.

    При изменении имени столбца или поля необходимо также изменить зависимые проверочные ограничения и созданные столбцы. Все первичные ключи и внешние ключи, использующие столбец, будут удалены. При использовании внешних ключей необходимо владеть таблицей, для которой определен внешний ключ.

    Требования см. в статье Сопоставление столбцов в Azure Databricks.

    RENAME COLUMN { column_identifier TO to_column_identifier|
                    field_name TO to_field_identifier }
    
    • column_identifier

      Существующее имя столбца.

    • to_column_identifier

      Новый идентификатор столбца. Идентификатор должен быть уникальным в пределах таблицы.

    • field_name

      Существующее полное имя поля.

    • to_field_identifier

      Новый идентификатор поля. Идентификатор должен быть уникальным в пределах локальной структуры.

  • ADD CONSTRAINT

    Добавляет в таблицу ограничение проверки, ограничение внешнего ключа или ограничение первичного ключа.

    Внешние ключи и первичные ключи не поддерживаются для таблиц в каталоге hive_metastore.

  • DROP CONSTRAINT

    Удаляет из таблицы ограничение первичного ключа, внешнего ключа или проверки.

  • ADD PARTITION

    Если значение указано, в таблицу добавляется одна или несколько секций. Добавление секций не поддерживается для таблиц Delta Lake.

    ADD [IF NOT EXISTS] { PARTITION clause [ LOCATION path ] } [...]
    
    • IF NOT EXISTS

      Необязательное предложение, при наличии которого Databricks SQL будет игнорировать инструкцию, если указанная секция уже существует.

    • PARTITION clause

      Секция, которую нужно добавить. Ключи секций должны соответствовать структуре секций в таблице и быть связаны со значениями. Если такая секция уже существует, возникает ошибка, если не указано предложение IF NOT EXISTS.

    • LOCATION path

      Значение path должно иметь тип STRING. Оно описывает необязательное расположение, указывающее на секцию.

      Если расположение не указано, расположение будет автоматически выведено из расположения таблицы и ключей секции.

      Если в указанном расположении уже есть файлы, они применяются для заполнения секции. Для этого они должны быть совместимы с таблицей data_source и ее настройками.

  • DROP PARTITION

    Если указано это предложение, из таблицы удаляются одна или несколько секций, по вашему желанию вместе со всем файлами в расположениях этих секций.

    Таблицы Delta Lake не поддерживают удаление секций.

    DROP [ IF EXISTS ] PARTITION clause [, ...] [PURGE]
    
    • IF EXISTS

      Если указан параметр IF EXISTS, Azure Databricks будет игнорировать попытку удаления несуществующих секций. В противном случае удаление несуществующих секций создает ошибку.

    • Предложение PARTITION

      Указывает секцию, которую нужно удалить. Если секция идентифицирована частично, удаляется целый срез секций.

    • PURGE

      Если задано это предложение, каталог таблиц будет безвозвратно удалять данные секции, а не помещать их в папку корзины, даже если она настроена для этого каталога. Этот механизм применим только для управляемых таблиц. Он действует только при соблюдении следующих условий:

      файловая система поддерживает папку корзины; для каталога настроено перемещение удаляемой секции в папку корзины. В AWS S3 папка корзины отсутствует, поэтому это предложение не применяется.

      Нет необходимости удалять файлы вручную после удаления секций.

  • RENAME PARTITION

    Заменяет ключи секции.

    Таблицы Delta Lake не поддерживают переименование секций.

    from_partition_clause RENAME TO to_partition_clause
    
    • from_partition_clause

      Определение секции, которую нужно переименовать.

    • to_partition_clause

      Новое определение для этой секции. Не должно существовать секции с указанными значениями ключей.

  • RECOVER PARTITIONS

    Это предложение не применяется к таблицам Delta Lake.

    Оно указывает, что Databricks SQL нужно просканировать расположение таблицы и добавить в нее любые файлы, которые были добавлены непосредственно в файловую систему.

  • SET TBLPROPERTIES

    Задает или сбрасывает одно или несколько свойств, определяемых пользователем.

  • UNSET TBLPROPERTIES

    Удаляет одно или несколько свойств, определяемых пользователем.

  • SET LOCATION

    Перемещает расположение секции или таблицы.

    Delta Lake не поддерживает перемещение отдельных секций для таблиц Delta Lake.

    [ PARTITION clause ] SET LOCATION path
    
    • Предложение PARTITION

      Необязательное определение секции, для которой будет изменено расположение. Если имя секции не указано, Azure Databricks перемещает расположение всей таблицы.

    • LOCATION path

      path должен быть СТРОКОВЫМ литералом. Задает новое расположение для секции или таблицы.

      Файлы в исходном расположении не будут перемещаться в новое расположение.

  • OWNER TO principal

    Передает права владения таблицей субъекту principal.

Примеры

Примеры добавления и изменения столбцов в Delta Lake см. в следующих статьях:

-- 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');