ALTER TABLE

Aplica-se a: marca de seleção positiva SQL do Databricks Databricks Runtime

Altera o esquema ou as propriedades de uma tabela.

As tabelas temporárias dão suporte ALTER TABLE ... SET TBLPROPERTIES e ALTER TABLE ... UNSET TBLPROPERTIES em computação sem servidor, Databricks Runtime 18.2 e superior e Databricks SQL 2026.15 e superior. Não há suporte para outras ALTER TABLE cláusulas em tabelas temporárias e retornam um erro. Se a tabela estiver armazenada em cache, o comando limpará os dados armazenados em cache da tabela e todos os dependentes que se referem a ela. O cache será preenchido de forma ociosa quando a tabela ou os dependentes forem acessados da próxima vez.

Tabelas estrangeiras suportam um conjunto limitado de ALTER TABLE operações, incluindo ALTER TABLE SET OWNER, ALTER TABLE RENAME TO, ALTER TABLE SET MANAGED { MOVE | COPY }, e ALTER TABLE SET EXTERNAL. SET MANAGED e SET EXTERNAL exigem uma federação de uma tabela estrangeira usando metastore Hive e Glue Federation, além SET MANAGED de exigir o formato Delta Lake. Veja tabelas estrangeiras e Converter uma tabela estrangeira em uma tabela externa do Catálogo Unity.

Permissões necessárias

Se você usar o Catálogo do Unity, deverá ter MODIFY permissão para:

ALTER COLUMN
ADD COLUMN
DROP COLUMN
SET TBLPROPERTIES
UNSET TBLPROPERTIES

Se você usar o Unity Catalog, precisará ter a permissão MANAGE ou propriedade para:

SET OWNER TO
PREDICTIVE OPTIMIZATION

Todas as outras operações exigem a propriedade da tabela, incluindo SET MANAGED e UNSET MANAGED.

SET EXTERNAL e a forma de tabela estrangeira de SET MANAGED também requer CREATE permissão no EXTERNAL LOCATION. Para os pré-requisitos completos de cada conversão, veja Pré-requisitos e Pré-requisitos.

Sintaxe

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 EXTERNAL clause |
      SET MANAGED clause |
      UNSET MANAGED clause |
      SET OWNER TO clause |
      SET TAGS clause |
      UNSET TAGS clause |
      CLUSTER BY clause |
      REPLACE PARTITIONED BY WITH CLUSTER BY clause |
      PREDICTIVE OPTIMIZATION clause}

Parâmetros

table_name

Identifica a tabela que está sendo alterada. O nome não deve incluir uma especificação temporal ou especificação de opções. Se a tabela não puder ser encontrada, o Azure Databricks gerará um erro TABLE_OR_VIEW_NOT_FOUND.
RENAME TO to_table_name

Renomeia a tabela.
- to_table_name
  
  Identifica o novo nome da tabela. O nome não deve incluir uma especificação temporal ou especificação de opções.
  
  Para tabelas do Catálogo do Unity, to_table_name deve estar dentro do mesmo catálogo que table_name. Para outras tabelas, o to_table_name deve estar dentro do mesmo esquema que o table_name.
  
  Se to_table_name não for qualificado, ele será automaticamente qualificado com o esquema atual.
```
> ALTER TABLE student RENAME TO student_info;
```

ADICIONAR COLUMN

Adiciona uma ou mais colunas à tabela.

Quando você adiciona uma coluna a uma tabela delta lake existente, não é possível definir um DEFAULT valor. Todas as colunas adicionadas às tabelas delta lake são tratadas como NULL para linhas existentes. Depois de adicionar uma coluna, opcionalmente, você pode definir um valor padrão para novas linhas usando 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';

ALTERAR COLUMN

Altera uma propriedade ou o local de uma coluna.

> 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

Altere várias colunas em uma única instrução:

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

Deixar cair COLUMN

Remover uma ou mais colunas ou campos em uma tabela Delta Lake.

RENOMEAR COLUMN

Renomeia uma coluna ou campo em uma tabela do 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

Adiciona uma restrição de verificação, uma restrição de chave estrangeira informativa ou uma restrição de chave primária informativa à tabela.

As chaves estrangeiras e as chaves primárias não têm suporte para tabelas no catálogo hive_metastore.
DEFAULT COLLATION Collation_name

Aplica-se a: Databricks SQL Databricks Runtime 16.3 e versões superiores

Altera a ordenação padrão da tabela para novas STRING colunas. As colunas existentes não são afetadas por essa cláusula. Para alterar a ordenação de uma coluna existente, use ALTER TABLE ... ALTER COLUMN ... COLLATE collation_name.

DROP CONSTRAINT

Remove uma chave primária, uma chave estrangeira ou uma restrição de verificação da tabela.
DROP FEATURE feature_name [ TRUNCATE HISTORY ]

Aplica-se a: Databricks Runtime 14.3 LTS e superior

O suporte herdado para DROP FEATURE está disponível a partir do Databricks Runtime 14.3 LTS. Para a documentação de funcionalidades herdadas, consulte Drop Delta table features (legacy).

Aplica-se a: Databricks SQL Databricks Runtime 16.3 e versões superiores
O Azure Databricks recomenda o uso do Databricks Runtime 16.3 e superior para todos os DROP FEATURE comandos, o que substitui o comportamento herdado.

Remove um recurso de uma tabela do Delta Lake.

Remover uma funcionalidade pode resultar na adição da funcionalidade de checkpointProtection gravador ao protocolo de tabelas. Para obter mais informações, consulte Os recursos da tabela Drop Delta e versões de protocolo e recursos de tabela.
- feature_name
  
  O nome de um recurso na forma de um literal STRING ou identificador, que deve ser compreendido pelo Azure Databricks e ter suporte na tabela.
  
  Se o recurso não estiver presente na tabela, o Azure Databricks aciona DELTA_FEATURE_DROP_FEATURE_NOT_PRESENT.
- HISTÓRICO DE TRUNCADOS
  
  Remoção de funcionalidades por meio de truncamento do histórico. Isso requer um processo de dois estágios:

A remoção de recursos truncando o histórico requer um processo de duas etapas:

A primeira invocação limpa os rastreamentos do recurso e informa sobre o êxito parcial.
Em seguida, aguarde o término do período de retenção antes de executar novamente a instrução para concluir a remoção.

Se você iniciar a segunda invocação muito cedo, o Azure Databricks gerará DELTA_FEATURE_DROP_WAIT_FOR_RETENTION_PERIOD ou DELTA_FEATURE_DROP_HISTORICAL_VERSIONS_EXIST.

Truncar o histórico da tabela limita sua capacidade de executar DESCRIBE HISTORY e executar consultas de viagem no tempo.
```
-- 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;
```

ADICIONAR PARTITION

Adiciona uma ou mais partições à tabela.

> 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

Deixar cair PARTITION

Descarta uma ou mais partições da tabela.

> 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 LOCALIZAÇÃO

Define o local de uma partição.

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

RENOMEAR PARTITION

Substitui as chaves de uma partição.

> 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

RECUPERAR PARTIÇÕES

Instrui o Azure Databricks a verificar o local da tabela e adicionar todos os arquivos à tabela que foram adicionados diretamente ao sistema de arquivos.
Cláusula SETROW FILTER

Aplica-se a: SQL do Databricks Databricks Runtime 12.2 LTS e versões posteriores Somente Catálogo do Unity

Adiciona uma função de filtro de linha à tabela. Todas as consultas subsequentes à tabela recebem um subconjunto de linhas onde a função avalia como o valor booliano TRUE. Isso pode ser útil para fins de controle de acesso refinado, em que a função pode inspecionar a identidade ou as associações de grupo do usuário que a invocou para determinar se deseja filtrar algumas linhas.
DROP ROW FILTER

Aplica-se a: Somente Catálogo do Unity

Descarta o filtro de linha da tabela, se houver. Consultas futuras retornarão todas as linhas da tabela sem nenhuma filtragem automática.
SET Propriedades TBL

Configura ou reconfigura uma ou mais propriedades definidas pelo usuário.
```
> ALTER TABLE dbx.tab1 SET TBLPROPERTIES ('winner' = 'loser');
```
DESCONFIGURAR TBLPROPERTIES

Remove uma ou mais propriedades definidas pelo usuário.
```
> ALTER TABLE dbx.tab1 UNSET TBLPROPERTIES ('winner');
```
SET SERDE

Aplica-se a: Databricks Runtime

Especifica a classe serDe (serializador/desserializador) usada para ler e gravar dados em uma tabela em formato Hive. Você também pode configurar as propriedades do SerDe com 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

Move o local de uma tabela.
```
SET LOCATION path
```
- LOCATION path
  
  path deve ser uma literal de STRING. Especifica o novo local da tabela.
  
  Os arquivos no local original não serão movidos para o novo local.

SET EXTERNAL [ DRY RUN ]

Aplica-se a: Databricks Runtime 17.3 e a Somente Catálogo do Unity

Converte uma tabela estrangeira em uma tabela externa do Unity Catalog, mantendo o histórico e as configurações da tabela, incluindo nome, configurações, permissões e visualizações. Suportado apenas em mesas estrangeiras federadas usando o Metastore Hive e a Glue Federation.

Requer OWNER ou MANAGE permissões na tabela e CREATE permissão na EXTERNAL LOCATIONtabela .

Para reverter a conversão, tire a mesa. O Azure Databricks a refedera como uma tabela estrangeira durante a próxima sincronização de catálogo.
- DRY RUN
  
  Verifica se a tabela de origem pode ser convertida, sem convertê-la. O comando retorna DRY_RUN_SUCCESS se a tabela puder ser convertida.
Para pré-requisitos e orientações específicas de formato, veja Converter uma tabela estrangeira em uma tabela externa do Unity Catalog.
```
-- Check whether a foreign table can be converted
> ALTER TABLE hms_federated_catalog.my_schema.my_table SET EXTERNAL DRY RUN;

-- Convert a foreign table to an external table
> ALTER TABLE hms_federated_catalog.my_schema.my_table SET EXTERNAL;
```

SET MANAGED

Aplica-se a: Databricks Runtime 17.3 LTS e acima apenas Catálogo Unity

Converte uma tabela Delta Lake externa ou estrangeira do Unity Catalog em uma tabela gerenciada pelo Unity Catalog. A conversão mantém o nome da tabela, configurações, permissões, visualizações e histórico.

Tabelas externas e estrangeiras usam formas diferentes da oração, como mostrado na seguinte sintaxe:
```
SET MANAGED [ TRUNCATE UNIFORM HISTORY ]  -- external tables
SET MANAGED { MOVE | COPY }               -- foreign tables
```
Para tabelas externas, omita MOVE e COPY. Se você incluir qualquer um deles, Azure Databricks aumenta DELTA_ALTER_TABLE_SET_MANAGED_UNSUPPORTED_COPY_MOVE_SYNTAX.

Para tabelas estrangeiras, especifique ou MOVE .COPY Se você omitir ambos, Azure Databricks aumenta DELTA_ALTER_TABLE_SET_MANAGED_COPY_OR_MOVE_REQUIRED. Para escolher entre as duas formas, veja Escolher o comando correto para sua tabela de origem.
- TRUNCATE UNIFORM HISTORY
  
  Aplica-se a tabelas externas que têm leituras Apache Iceberg ativadas. Se a tabela tiver o Iceberg reads ativado e você omite essa opção, Azure Databricks aumenta DELTA_ALTER_TABLE_SET_MANAGED_DOES_NOT_SUPPORT_UNIFORM_ICEBERG.
  
  TRUNCATE UNIFORM HISTORY Trunca a história do UniForm Iceberg e não remove a história do Delta Lake. Truncamento causa um curto tempo de leitura e escrita do iceberg.
- MOVE
  
  Converte uma tabela estrangeira para gerenciada e desativa o acesso à tabela de origem no catálogo externo. Após a conversão, o acesso pelo catálogo externo e o acesso baseado em caminho falham, então todos os leitores e escritores devem usar o namespace do Unity Catalog.
- COPY
  
  Converte uma tabela estrangeira para gerenciada sem modificar ou desabilitar o acesso à tabela de origem no catálogo externo. A conversão copia os dados para o local de armazenamento gerenciado, criando duas cópias separadas dos dados. Você é responsável por desabilitar leituras e gravações na tabela de origem e migrar cargas de trabalho para a tabela gerenciada.
Para pré-requisitos, estimativas de tempo de inatividade e solução de problemas, veja Converter tabelas Delta Lake externas ou estrangeiras para tabelas gerenciadas pelo Catálogo Unity.
```
-- Convert an external table
> ALTER TABLE main.default.my_external_table SET MANAGED;

-- Convert an external table that has Iceberg reads enabled
> ALTER TABLE main.default.my_external_table SET MANAGED TRUNCATE UNIFORM HISTORY;

-- Convert a foreign table and disable access to the source table
> ALTER TABLE hms_federated_catalog.my_schema.my_table SET MANAGED MOVE;
```
UNSET MANAGED

Aplica-se a: Databricks Runtime 17.3 LTS e acima apenas Catálogo Unity

Converte uma tabela SET MANAGED de volta para uma tabela externa atualizando os metadados da tabela para apontar para a localização externa original. O Azure Databricks preserva as escritas feitas na localização gerenciada após a conversão. Para uma tabela externa convertida, você pode reverter dentro de 14 dias após a conversão.
```
UNSET MANAGED [ TRUNCATE UNIFORM HISTORY ]
```
- TRUNCATE UNIFORM HISTORY
  
  Vale para tabelas que têm leituras Iceberg ativadas. Se a tabela tiver Iceberg reads ativado e você omite essa opção, Azure Databricks aumenta DELTA_ALTER_TABLE_UNSET_MANAGED_DOES_NOT_SUPPORT_UNIFORM.
Commits feitos entre conversão e rollback suportam viagem no tempo por versão, mas não por carimbo de tempo.

Para rolar uma tabela estrangeira convertida de volta MOVE para uma tabela estrangeira, execute UNSET MANAGED e então retire a tabela externa resultante, que a refedera durante a próxima sincronização de catálogo. Uma tabela estrangeira convertida com COPY não precisa UNSET MANAGEDde , porque a conversão deixou a tabela de origem sem modificação.

Warning

Se você converteu uma tabela estrangeira com MOVE, não descarte a tabela gerenciada antes de executar UNSET MANAGED. Descartá-lo primeiro pode resultar em perda de dados ou inconsistências.

Para instruções completas de rollback, veja Reverter uma conversão gerenciada de tabela.
```
-- Roll a converted managed table back to an external table
> ALTER TABLE main.default.my_managed_table UNSET MANAGED;
```
[ SET ] OWNER TO entidade

Transfere a propriedade da tabela para principal.

Aplica-se a: SQL do Databricks Databricks Runtime 11.3 LTS e versões posteriores

SET é permitido como uma palavra-chave opcional.

Note

A alteração do proprietário não está disponível em conjuntos de dados gerenciados por um pipeline de workspace.
SET TAGS ( { tag_name = tag_value } [, ...] )

Aplica-se a: SQL do Databricks Databricks Runtime 13.3 LTS e versões posteriores

Aplica tags à tabela. Você precisa ter a permissão APPLY TAG para adicionar tags à tabela.
- nome_da_tag
  
  Um literal STRING. O tag_name deve ser exclusivo na tabela ou coluna.
- tag_value
  
  Um literal 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 [, ...] )

Aplica-se a: SQL do Databricks Databricks Runtime 13.3 LTS e versões posteriores

Remove as tags da tabela. Você precisa ter a permissão APPLY TAG para remover tags da tabela.
- nome_da_tag
  
  Um literal STRING. O tag_name deve ser exclusivo na tabela ou coluna.
```
-- 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');
```
Cláusula CLUSTER BY

Aplica-se a: SQL do Databricks Databricks Runtime 13.3 LTS e versões posteriores

Adiciona, altera ou descarta a estratégia de clustering de uma tabela Delta Lake.
REPLACE PARTITIONED BY WITH CLUSTER BY [( <clustering_columns> ) | AUTO]

Aplica-se a: Databricks SQL Databricks Runtime 18.1 and above

Converte uma tabela delta lake particionada existente em clustering líquido no local, com tempo mínimo de inatividade de leitor e gravador. A CLUSTER BY cláusula aceita colunas de clustering explícitas, AUTO para delegar a seleção de chave à otimização preditiva ou pode ser omitida para usar as colunas de partição existentes.

Consulte Converter uma tabela particionada em clustering líquido.
{ ENABLE | DISABLE | INHERIT } PREDICTIVE OPTIMIZATION

Aplica-se a: SQL do Databricks Databricks Runtime 12.2 LTS e versões posteriores Somente Catálogo do Unity

Altera a tabela Delta Lake gerenciada para a configuração de otimização preditiva desejada.

Por padrão, quando as tabelas são criadas, o comportamento é para INHERIT do esquema.

Quando a otimização preditiva estiver explicitamente habilitada ou herdada como habilitada OPTIMIZE e VACUUM serão automaticamente invocadas na tabela, conforme considerado apropriado pelo Azure Databricks. Para obter mais detalhes, consulte: Otimização preditiva para tabelas gerenciadas do Catálogo do Unity.
```
-- Enables predictive optimization for my_table
> ALTER TABLE my_table ENABLE PREDICTIVE OPTIMIZATION;
```

Exemplos adicionais

Para ver exemplos de adição de restrições e alteração de colunas do Delta Lake, confira

ADD CONSTRAINT cláusula: adicionar ou remover restrições de verificação, chaves primárias e chaves estrangeiras.
ALTER MATERIALIZED VIEW: sintaxe para alterar exibições materializadas.
ALTER STREAMING TABLE: sintaxe para alterar tabelas de streaming.
ALTER TABLE Cláusula ... COLUMN: Sintaxe completa para ADD, ALTER, DROP e RENAMECOLUMN.
ALTER TABLE … PARTITION: sintaxe completa para adicionar, remover e renomear partições.
Atualizar esquemas de tabela com evolução do esquema: renomear ou alterar tipos de coluna em uma tabela Delta.
Converter tabelas Delta Lake externas ou estrangeiras para tabelas gerenciadas pelo Unity Catalog: Pré-requisitos, estimativas de tempo de inatividade e rollback para SET MANAGED e UNSET MANAGED.
Converter uma tabela estrangeira em uma tabela externa do Unity Catalog: Pré-requisitos e orientações específicas de formato para SET EXTERNAL.

Comentários

Esta página foi útil?

Last updated on 2026-08-14