ALTER TABLE

Статья
04/18/2024

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

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

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

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

Чтобы изменить STREAMING TABLE, используйте ALTER STREAMING TABLE.

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

Примечание.

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

ALTER TABLE table_name ALTER COLUMN column_name SET DEFAULT default_expression

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

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

Если вы используете каталог 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 |
     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 TOto_table_name

Переименовывает таблицу, сохраняя для нее прежнюю схему.
- to_table_name
  
  Определяет новое имя таблицы. Имя не должно содержать временную спецификацию.
ADD COLUMN

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

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

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

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

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

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

Удаляет из таблицы ограничение первичного ключа, внешнего ключа или проверки.
DROP FEATURE feature_name [ TRUNCATE HISTORY ]

Область применения: Databricks SQL Databricks Runtime 14.1 и более поздних версий

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

Удаление функций, влияющих как на читателей, так и для записи, требуется двухэтапный процесс:
- Первый вызов очищает все трассировки функции и сообщает о частичном успешном выполнении.
- Затем необходимо дождаться окончания срока хранения и повторно выполнить инструкцию, чтобы завершить удаление.
  
  Если вы инициируете второй вызов слишком рано, Azure Databricks вызывает DELTA_FEATURE_DROP_WAIT_FOR_RETENTION_PERIOD или DELTA_FEATURE_DROP_HISTORICAL_VERSIONS_EXIST.
Дополнительные сведения см. в разделе "Что такое функции таблицы".
- feature_name
  
  Имя функции в виде литерала или идентификатораSTRING, которое должно пониматься Azure Databricks и поддерживаться в таблице.
  
  Поддерживаются feature_names :
  - "deletionVectors" или deletionvectors
    - 'v2Checkpoint' или v2checkpoint
  Если функция отсутствует в таблице Azure Databricks, вызывает DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT.
- ЖУРНАЛ УСЕЧЕНИЯ
  
  При необходимости можно инициировать второй этап удаления функции чтения и записи после 24 часов, усечив журнал таблиц до момента выполнения команды вызова.
  
  Усечение журнала таблиц ограничивает возможность выполнения запросов ОПИСАТЬ ЖУРНАЛ и выполнения запросов на поездки по времени.
ADD PARTITION

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

Удаляет одну или несколько секций из таблицы.
РАЗДЕЛ... РАСПОЛОЖЕНИЕ SET

Задает расположение секции.
RENAME PARTITION

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

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

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

Внимание

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

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

Область применения: только каталог Unity

Внимание

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

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

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

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

Перемещает расположение таблицы.
```
SET LOCATION path
```
- LOCATION path
  
  path должен быть литералом STRING . Указывает новое расположение таблицы.
  
  Файлы в исходном расположении не будут перемещаться в новое расположение.
[ SET ] OWNER TOprincipal

Передает права владения таблицей субъекту 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.
UNSET TAGS ( tag_name [, ...] )

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

Удалите теги из таблицы. Необходимо иметь apply_tag разрешение на удаление тегов из таблицы.
- tag_name
  
  Литерал STRING. Он tag_name должен быть уникальным в таблице или столбце.
Предложение 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 из схемы.

Если прогнозная оптимизация явно включена или наследуется как включенная ОПТИМИЗАЦИЯ и ВАКУУМ будет автоматически вызываться в таблице, как считается соответствующим в Azure Databricks. Дополнительные сведения см. в статье "Прогнозная оптимизация для Delta Lake".

Примеры

Сведения о добавлении ограничений и изменении примеров столбцов в 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 SERDE/ SERDE Properties (DBR only)
> 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 TABLE PROPERTIES
> ALTER TABLE dbx.tab1 SET TBLPROPERTIES ('winner' = 'loser');

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

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

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

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

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

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

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

ALTER TABLE

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

Синтаксис

Параметры

Примеры

Связанные статьи

Дополнительные ресурсы