ALTER TABLE

Область применения:отмечено как Databricks SQL отмечено как Databricks Runtime

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

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

В внешних таблицах можно выполнять ALTER TABLE SET OWNER только и ALTER TABLE RENAME TO.

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

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

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

Если вы используете каталог Unity, вы должны обладать разрешением или правом владения MANAGE:

  • SET OWNER TO

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

Синтаксис

ALTER TABLE table_name
    { RENAME TO clause |
      ADD COLUMN clause |
      ALTER COLUMN clause |
      DROP COLUMN clause |
      RENAME COLUMN clause |
      DEFAULT COLLATION clause |
      ADD CONSTRAINT clause |
      DROP CONSTRAINT clause |
      DROP FEATURE clause |
      ADD PARTITION clause |
      DROP PARTITION clause |
      PARTITION SET LOCATION clause |
      RENAME PARTITION clause |
      RECOVER PARTITIONS clause |
      SET { ROW FILTER clause } |
      DROP ROW FILTER |
      SET TBLPROPERTIES clause |
      UNSET TBLPROPERTIES clause |
      SET SERDE clause |
      SET LOCATION clause |
      SET OWNER TO clause |
      SET SERDE clause |
      SET TAGS clause |
      UNSET TAGS clause |
      CLUSTER BY clause |
      PREDICTIVE OPTIMIZATION clause}

Параметры

  • table_name

    Определяет таблицу, которую нужно изменить. Имя не должно включать темпоральную спецификацию или спецификацию параметров. Если не удается найти таблицу Azure Databricks, возникает ошибка TABLE_OR_VIEW_NOT_FOUND .

  • RENAME TO to_table_name

    Переименовывает таблицу.

    • to_table_name

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

      Для таблиц каталога Unity to_table_name должен находиться в том же каталоге, что и table_name. Для других таблиц to_table_name должен находиться в той же схеме, что и table_name.

      Если to_table_name не квалифицирован, он неявно квалифицируется по текущей схеме.

    > ALTER TABLE student RENAME TO student_info;

  • ДОБАВЛЯТЬ COLUMN

    Добавляет в таблицу один или несколько столбцов.

    При добавлении столбца в существующую таблицу Delta Lake нельзя определить DEFAULT значение. Все столбцы, добавленные в таблицы Delta Lake, обрабатываются как NULL для существующих строк. После добавления столбца можно при необходимости определить значение по умолчанию для новых строк с помощью ALTER COLUMN.

    > DESCRIBE StudentInfo;
                col_name data_type comment
----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                     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

-- Optionally set a default value for new rows
> ALTER TABLE StudentInfo ALTER COLUMN LastName SET DEFAULT 'unknown';

  • ИЗМЕНИТЬ COLUMN

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

    > DESCRIBE StudentInfo;
                col_name data_type comment
----------------------- --------- -------
                    name    string    NULL
                  rollno       int    NULL
                LastName    string    NULL
                     DOB timestamp    NULL
                     age       int    NULL

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

-- After altering the column
> DESCRIBE StudentInfo;
                col_name data_type     comment
----------------------- --------- -----------
                    name    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL

    Измените несколько столбцов в одной инструкции:

    -- Create a table with 3 columns
> CREATE TABLE my_table (num INT, str STRING, bool BOOLEAN) TBLPROPERTIES('delta.feature.allowColumnDefaults' = 'supported')
> DESCRIBE TABLE my_table;
  col_name    data_type     comment
  --------    ---------     -------
       num          int        null
       str       string        null
       bool      boolean       null

-- Update comments on multiple columns
> ALTER TABLE table ALTER COLUMN
   num COMMENT 'number column',
   str COMMENT 'string column';

> DESCRIBE TABLE my_table;
  col_name    data_type      comment
  --------    ---------   -------------
       num          int   number column
       str       string   string column
      bool      boolean            null

-- Can mix different types of column alter
> ALTER TABLE table ALTER COLUMN
   bool COMMENT 'boolean column',
   num AFTER bool,
   str AFTER num,
   bool SET DEFAULT true;

> DESCRIBE TABLE my_table;
  col_name    data_type      comment
  --------    ---------   --------------
      bool      boolean   boolean column
       num          int    number column
       str       string    string column

  • УДАЛИТЬ COLUMN

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

  • ПЕРЕИМЕНОВАТЬ COLUMN

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

    > ALTER TABLE StudentInfo RENAME COLUMN name TO FirstName;

-- After renaming the column
> DESCRIBE StudentInfo;
                col_name data_type     comment
----------------------- --------- -----------
               FirstName    string new comment
                  rollno       int        NULL
                LastName    string        NULL
                     DOB timestamp        NULL
                     age       int        NULL

  • ADD CONSTRAINT

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

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

  • DEFAULT COLLATION collation_name

    Применяется к:отмечено галочкой да Databricks SQL отмечено галочкой да Databricks Runtime 16.3 и более поздних версий

    Изменяет параметры сортировки таблицы по умолчанию для новых столбцов STRING. Данный пункт не затрагивает существующие столбцы. Чтобы изменить параметры сортировки существующего столбца, используйте ALTER TABLE ... ALTER COLUMN ... COLLATE collation_name.

  • DROP CONSTRAINT

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

  • DROP FEATURE feature_name [ TRUNCATE HISTORY ]

    Область применения:отмечено да Databricks Runtime 14.3 LTS и выше

    Поддержка прежних версий DROP FEATURE доступна начиная с Databricks Runtime 14.3 LTS. Для документирования устаревших функций см. раздел "Особенности таблицы Delta (устаревшая версия)".

    Применяется к:отмечено галочкой да Databricks SQL отмечено галочкой да Databricks Runtime 16.3 и более поздних версий

  • Azure Databricks рекомендует использовать Databricks Runtime 16.3 и выше для всех DROP FEATURE команд, которые заменяют устаревшее поведение.

    Удаляет функцию из таблицы Delta Lake.

    Удаление функции может привести к добавлению checkpointProtection функции записи в протокол таблицы. Для получения дополнительной информации смотрите Drop Delta table features и Table features for protocol compatibility.

    • feature_name

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

      Если функция отсутствует в таблице, Azure Databricks генерирует DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT.

    • УСЕЧЕНИЕ ИСТОРИИ

      Удаление элементов путем усечения истории. Для этого требуется два этапа:

Для удаления особенностей путем усечения истории требуется двухэтапный процесс:

  • Первый вызов очищает трассировки функции и сообщает о частичном успешном выполнении.

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

    Если вы инициируете второй вызов слишком рано, Azure Databricks вызывает DELTA_FEATURE_DROP_WAIT_FOR_RETENTION_PERIOD или DELTA_FEATURE_DROP_HISTORICAL_VERSIONS_EXIST.

    Усечение истории таблицы ограничивает вашу возможность выполнять DESCRIBE HISTORY и выполнять запросы с функцией путешествия во времени.

    -- Drop the "deletion vectors" from a Delta table
> ALTER TABLE my_table DROP FEATURE deletionVectors;

-- 24 hours later
> ALTER TABLE my_table DROP FEATURE deletionVectors TRUNCATE HISTORY;

  • ДОБАВЛЯТЬ PARTITION

    Добавляет в таблицу один или несколько разделов.

    > 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

-- Adding multiple partitions to the table
> ALTER TABLE StudentInfo ADD IF NOT EXISTS PARTITION (age=18) PARTITION (age=20);

> SHOW PARTITIONS StudentInfo;
partition
---------
    age=11
    age=12
    age=15
    age=18
    age=20

  • УДАЛИТЬ PARTITION

    Удаляет один или несколько разделов из таблицы.

    > 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

  • PARTITION ... SET ЛОКАЦИЯ

    Задает расположение раздела.

    > ALTER TABLE dbx.tab1 PARTITION (a='1', b='2') SET LOCATION '/path/to/part/ways';

  • ПЕРЕИМЕНОВАТЬ 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

  • ВОССТАНОВЛЕНИЕ РАЗДЕЛОВ

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

  • пункт SETROW FILTER

    Применяется к:отмечено галочкой 'да' Databricks SQL отмечено галочкой 'да' Databricks Runtime 12.2 LTS и выше отмечено галочкой 'да' только каталог Unity.

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

  • DROP ROW FILTER

    Область применения:установлен флажок 'Да' только для каталога Unity

    Удаляет фильтр строк из таблицы, если таковой есть. Будущие запросы возвращают все строки из таблицы без автоматической фильтрации.

  • SET TBLPROPERTIES

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

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

  • UNSET TBLPROPERTIES

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

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

  • SET SERDE

    Область применения:отмечено галочкой «Да» Databricks Runtime

    Указывает класс сериализатора или десериализатора (SerDe), используемый для чтения и записи данных в таблице формата Hive. Вы также можете настроить свойства SerDe с WITH SERDEPROPERTIESпомощью .

    > ALTER TABLE test_tab SET SERDE 'org.apache.hadoop.hive.serde2.columnar.LazyBinaryColumnarSerDe';

> ALTER TABLE dbx.tab1 SET SERDE 'org.apache.hadoop' WITH SERDEPROPERTIES ('k' = 'v', 'kay' = 'vee');

  • SET LOCATION

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

    SET LOCATION path

    • LOCATION path

      path должен быть литеральным значением STRING. Указывает новое расположение таблицы.

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

  • [ SET ] OWNER TO директор

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

    Область применения:флажок Databricks SQL флажок Databricks Runtime 11.3 LTS и выше

    SET разрешено в качестве необязательного ключевого слова.

  • SET TAGS ( { tag_name = tag_value } [, ...] )

    Область применения:флажок Databricks SQL флажок Databricks Runtime 13.3 LTS и выше

    Примените теги к таблице. Необходимо иметь APPLY TAG разрешение на добавление тегов в таблицу.

    • tag_name

      Литерал STRING. tag_name должен быть уникальным внутри таблицы или столбца.

    • tag_value

      Литерал STRING.

    -- Applies three tags to the table named `test`.
> ALTER TABLE test SET TAGS ('tag1' = 'val1', 'tag2' = 'val2', 'tag3' = 'val3');

-- Applies three tags to table `main.schema1.test` column `col1`.
> ALTER TABLE main.schema1.test ALTER COLUMN col1 SET TAGS ('tag1' = 'val1', 'tag2' = 'val2', 'tag3' = 'val3');

  • UNSET TAGS ( tag_name [, ...] )

    Область применения:флажок Databricks SQL флажок Databricks Runtime 13.3 LTS и выше

    Удалите теги из таблицы. Необходимо иметь APPLY TAG разрешение на удаление тегов из таблицы.

    • tag_name

      Литерал STRING. tag_name должен быть уникальным внутри таблицы или столбца.

    -- Removes three tags from the table named `test`.
> ALTER TABLE test UNSET TAGS ('tag1', 'tag2', 'tag3');

-- Removes three tags from table `main.schema1.test` column `col1`.
> ALTER TABLE main.schema1.test ALTER COLUMN col1 UNSET TAGS ('tag1', 'tag2', 'tag3');

  • CLUSTER BY пункт

    Область применения:флажок Databricks SQL флажок Databricks Runtime 13.3 LTS и выше

    Добавляет, изменяет или удаляет стратегию кластеризации для таблицы Delta Lake.

  • { ENABLE | DISABLE | INHERIT } PREDICTIVE OPTIMIZATION

    Применяется к:отмечено галочкой 'да' Databricks SQL отмечено галочкой 'да' Databricks Runtime 12.2 LTS и выше отмечено галочкой 'да' только каталог Unity.

    Изменяет управляемую таблицу Delta Lake на нужный параметр прогнозной оптимизации.

    По умолчанию при создании таблиц действует INHERIT из схемы.

    Если прогнозная оптимизация явно включена или унаследована как активированная, OPTIMIZE и VACUUM будут автоматически вызываться в таблице, если это будет сочтено подходящим в Azure Databricks. Дополнительные сведения см. в разделе прогнозной оптимизации управляемых таблиц каталога Unity.

    -- Enables predictive optimization for my_table
> ALTER TABLE my_table ENABLE PREDICTIVE OPTIMIZATION;

Дополнительные примеры

См. раздел о добавлении ограничений и изменении столбцов в Delta Lake для примеров.

  • Last updated on