ALTER TABLE

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

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

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

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

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

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

ALTER TABLE table_name ALTER COLUMN column_name SET DEFAULT default_expression

On foreign tables, you can perform only ALTER TABLE SET OWNER and ALTER TABLE RENAME TO.

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

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

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

If you use Unity Catalog you must have MANAGE permission or ownership to:

• 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

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

• ADD COLUMN

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

• ALTER COLUMN

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

• УДАЛИТЬ COLUMN

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

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

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

• ADD CONSTRAINT

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

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

• DEFAULT COLLATION collation_name

  Applies to: Databricks Runtime 16.3 and above

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

• DROP CONSTRAINT

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

• DROP FEATURE feature_name [ TRUNCATE HISTORY ]

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

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

  Удаление функций, влияющих как на читателей, так и на писателей, требует двухэтапного процесса.

  • The first invocation clears any traces of the feature and informs you of partial success.

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

    If you initiate the second invocation too early, Azure Databricks raises DELTA_FEATURE_DROP_WAIT_FOR_RETENTION_PERIOD or DELTA_FEATURE_DROP_HISTORICAL_VERSIONS_EXIST.

  Дополнительные сведения см. в разделе "Функции таблицы" для обеспечения совместимости протокола .

  • feature_name

    The name of a feature in form of a STRING literal or identifier, that must be understood by Azure Databricks and be supported on the table.

    Supported feature_names are:

    • ‘deletionVectors’ or deletionvectors
      • ‘v2Checkpoint’ or v2checkpoint

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

  • TRUNCATE HISTORY

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

    Truncating the table history limits your ability to perform DESCRIBE HISTORY and execute time travel queries.

• ADD PARTITION

  Adds one or more partitions to the table.

• УДАЛИТЬ PARTITION

  Drops one or more partitions from the table.

• PARTITION … SET LOCATION

  Sets the location of a partition.

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

  Replaces the keys of a partition.

• RECOVER PARTITIONS

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

• SET ROW FILTER clause

  Applies to: Databricks SQL Databricks Runtime 12.2 LTS and above Unity Catalog only

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

• DROP ROW FILTER

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

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

• SET TBLPROPERTIES

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

• UNSET TBLPROPERTIES

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

• SET LOCATION

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

  SET LOCATION path
  

  • LOCATION path

    path must be a STRING literal. Указывает новое расположение таблицы.

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

• [ 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

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

  • tag_value

    A literal STRING.

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

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

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

  • tag_name

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

• CLUSTER BY clause

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

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

• { ENABLE | DISABLE | INHERIT } PREDICTIVE OPTIMIZATION

  Applies to: Databricks SQL Databricks Runtime 12.2 LTS and above Unity Catalog only

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

  By default, when tables are created, the behavior is to INHERIT from the schema.

  When predictive optimization is explicitly enabled or inherited as enabled OPTIMIZE and VACUUM will be automatically invoked on the table as deemed appropriate by Azure Databricks. Дополнительные сведения см. в разделе прогнозной оптимизации управляемых таблиц каталога Unity.

Примеры

For Delta Lake add constraints and alter column examples, see

• Обновление схемы таблицы Delta Lake
• Ограничения в Azure Databricks

-- 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 multiple columns in a single statement
-- 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

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

• ADD CONSTRAINT

• ALTER STREAMING TABLE

• ALTER VIEW
• CLUSTER BY
• COMMENT ON
• CREATE TABLE
• DROP CONSTRAINT
• DROP TABLE
• manage COLUMN
• manage PARTITION
• REPAIR TABLE
• PARTITION