ALTER TABLE ... COLUMN cláusula

Aplica-se a: Databricks SQL Databricks Runtime

Adiciona, modifica ou elimina uma coluna numa tabela, ou um campo numa coluna numa tabela de Delta Lake.

Permissões obrigatórias

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

• ALTER COLUMN
• ADD COLUMN
• DROP COLUMN

Todas as outras operações requerem a propriedade da tabela.

Sintaxe

ALTER TABLE table_name
   { ADD COLUMN clause |
     ALTER COLUMN clause |
     DROP COLUMN clause |
     RENAME COLUMN clause }

Adicionar cláusula COLUMN

Esta cláusula não é suportada para JDBC fontes de dados.

Adiciona uma ou mais colunas à tabela ou campos a colunas existentes em uma tabela Delta Lake.

ALTER TABLE table_name ALTER COLUMN column_name SET DEFAULT default_expression

Sintaxe

{ ADD [ COLUMN | COLUMNS ]
  ( { { column_identifier | field_name } data_type
      [ COLLATE collation_name ]
      [ DEFAULT clause ]
      [ COMMENT comment ]
      [ FIRST | AFTER identifier ]
      [ MASK clause ] } [, ...] ) }

Parâmetros

• column_identifier

  O nome da coluna a ser adicionada. O nome deve ser exclusivo dentro da tabela.

  A menos que FIRST ou AFTER name sejam especificados, a coluna ou campo será anexado no final.

• field_name

  O nome totalmente qualificado do campo a ser adicionado a uma coluna existente. Todos os componentes do caminho para o campo aninhado devem existir e o próprio nome do campo deve ser único.

  Para adicionar campos a estruturas aninhadas ou ARRAYMAP tipos, use os seguintes nomes especiais:

  • ELEMENT para navegar até um ARRAY elemento.
  • KEY para navegar até uma MAP chave.
  • VALUE para navegar até um MAP valor.

  Por exemplo: phonenumbers.element.countrycode adiciona o campo countrycode a cada elemento da phonenumbers matriz.

• DEFAULT default_expression

  Aplica-se a: Databricks SQL Databricks Runtime 11.3 LTS e superior

  Define um DEFAULT valor para a coluna que é usado em INSERT e MERGE ... INSERT quando a coluna não é especificada. Quaisquer literais STRING e funções STRING usados na expressão padrão utilizarão a ordenação UTF8_BINARY.

  Se nenhum padrão for especificado, DEFAULT NULL é considerado implícito para colunas anuláveis.

  default_expression pode ser composto de literais e funções ou operadores SQL internos, exceto:

  • Funções agregadas
  • Funções de janela analítica
  • Funções da janela de classificação
  • Funções geradoras de valores de tabela

  default_expression não deve conter qualquer subconsulta.

  DEFAULT é suportado para CSV, JSON, PARQUETe ORC fontes.

• tipo_de_dado

  Especifica o tipo de dados da coluna ou campo. Nem todos os tipos de dados suportados pelo Azure Databricks são suportados por todas as origens de dados.

• COLLATE collation_name

  Para data_typeSTRING especifica opcionalmente o agrupamento a ser usado com a coluna ou campo. Se não for especificado, aplica-se o agrupamento UTF8_BINARY.

• COMMENT comment

  Um literal STRING opcional que descreve a coluna ou o campo adicionado.

  Se você quiser adicionar um comentário gerado por IA para uma tabela ou coluna de tabela gerenciada pelo Unity Catalog, consulte Adicionar comentários gerados por IA a objetos do Unity Catalog.

• FIRST

  Se especificado, a coluna será adicionada como a primeira coluna da tabela, ou o campo será adicionado como o primeiro campo da estrutura que contém.

• AFTER identificador

  Se especificado, a coluna ou campo será adicionado imediatamente após o campo ou coluna identifier.

• Cláusula MASK

  Aplica-se a: Databricks SQL Databricks Runtime 12.2 LTS e superior apenas no Catálogo Unity

  Importante

  Esta funcionalidade está em Pré-visualização Pública.

  Adiciona uma função de máscara de coluna para anonimizar dados confidenciais. Todas as consultas subsequentes dessa coluna receberão o resultado da avaliação dessa função sobre a coluna no lugar do valor original da coluna. Isso pode ser útil para fins de controle de acesso refinado, onde a função pode inspecionar a identidade ou as associações de grupo do usuário que invoca para determinar se o valor deve ser redigido.

Cláusula ALTER COLUMN

Aplica-se a: Databricks SQL Databricks Runtime

Altera uma propriedade ou a posição de uma coluna.

Sintaxe

 { ALTER | CHANGE } [ COLUMN ]
  { { column_identifier | field_name }
    { COMMENT comment |
    { FIRST | AFTER column_identifier } |
    { SET | DROP } NOT NULL |
    TYPE data_type |
    SET DEFAULT clause |
    DROP DEFAULT |
    SYNC IDENTITY }
  [, ... ]

Antes do Databricks Runtime 16.3, a cláusula não suportava a alteração de várias colunas em uma única cláusula.

{ ALTER | CHANGE } [ COLUMN ]
  { column_identifier | field_name }
  { SET { MASK clause } |
    DROP MASK |
    SET TAGS clause |
    UNSET TAGS clause }

Parâmetros

• column_identifier

  O nome da coluna a ser alterada.

  Se um identificador de coluna for referenciado mais de uma vez, o Azure Databricks gerará NOT_SUPPORTED_CHANGE_SAME_COLUMN.

• field_name

  O nome totalmente qualificado do campo a ser alterado. Todos os componentes do caminho para o campo aninhado devem existir.

  Se um nome de campo for referenciado mais de uma vez, o Azure Databricks gerará NOT_SUPPORTED_CHANGE_SAME_COLUMN.

• COMMENT comment

  Altera a descrição da column_name coluna. comment tem de ser um STRING literal.

• FIRST ou AFTERidentificador

  Move a coluna de sua posição atual para a frente (FIRST) ou imediatamente AFTER o identifier. Esta cláusula só é suportada se table_name for uma tabela Delta.

• TYPE tipo_de_dados

  Aplica-se a: Databricks SQL Databricks Runtime 15.2 e superior

  Altera o tipo de dados da column_name coluna.

  Esta cláusula só é suportada se table_name for uma tabela Delta.

  As seguintes alterações de tipo são suportadas para todas as tabelas Delta:

  • Aumentar o tamanho de uma VARCHAR coluna, por exemplo, de VARCHAR(5) para VARCHAR(10)
  • Alterar o tipo de uma coluna CHAR para um VARCHAR, por exemplo, de CHAR(5) para VARCHAR(5)
  • Alterar o tipo de uma coluna CHAR ou VARCHAR para STRING, por exemplo, de VARCHAR(10) para STRING.

  As seguintes alterações de tipo são suportadas para tabelas Delta com delta.enableTypeWidening definido como true:

  Importante

  Esse recurso está no Public Preview no Databricks Runtime 15.2 e superior.

  Tipo de fonte	Tipos mais amplos suportados
  BYTE	SHORT, INT, BIGINT, DECIMAL, DOUBLE
  SHORT	INT, BIGINT, DECIMAL, DOUBLE
  INT	BIGINT, DECIMAL, DOUBLE
  BIGINT	DECIMAL, DOUBLE
  FLOAT	DOUBLE
  DECIMAL	DECIMAL com maior precisão e escala
  DATE	TIMESTAMP_NTZ

  Para obter informações mais detalhadas sobre alargamento de tipo, consulte Alargamento de tipo.

• SET NOT NULL ou DROP NOT NULL

  Altera o domínio de valores válidos de coluna para excluir nulos SET NOT NULL ou incluir nulos DROP NOT NULL. Esta opção só é suportada para tabelas Delta Lake. O Delta Lake garantirá que a restrição seja válida para todos os dados novos e existentes.

• SYNC IDENTITY

  Aplica-se a: Databricks SQL Databricks Runtime 10.4 LTS e posteriores

  Sincronize os metadados de uma coluna de identidade com os dados reais. Quando você escreve seus próprios valores em uma coluna de identidade, ela pode não estar em conformidade com os metadados. Esta opção avalia o estado e atualiza os metadados para serem consistentes com os dados reais. Após esse comando, o próximo valor de identidade atribuído automaticamente começará a partir de start + (n + 1) * step, onde n é o menor valor que satisfaz start + n * step >= max() (para uma etapa positiva).

  Esta opção só é suportada para colunas de identidade em tabelas Delta Lake.

• DROP DEFAULT

  Aplica-se a: Databricks SQL Databricks Runtime 11.3 LTS e superior

  Remove a expressão padrão da coluna. Para colunas anuláveis, isso é equivalente a SET DEFAULT NULL. Para colunas definidas com NOT NULL você precisa fornecer um valor em cada operação futura INSERT

• SET DEFAULT default_expression

  Aplica-se a: Databricks SQL Databricks Runtime 11.3 LTS e superior

  Define um DEFAULT valor para a coluna que é usado em INSERT e MERGE ... INSERT quando a coluna não é especificada.

  Se nenhum padrão for especificado, DEFAULT NULL é considerado para colunas anuláveis.

  default_expression pode ser composto por literais, funções SQL internas ou operadores, exceto:

  • Funções agregadas
  • Funções de janela analítica
  • Funções da janela de classificação
  • Funções geradoras de valores de tabela

  default_expression não deve conter uma subconsulta.

  DEFAULT é suportado para CSV, JSON, ORCe PARQUET fontes.

  Quando você define o padrão para uma coluna recém-adicionada, o padrão se aplica a todas as linhas pré-existentes. Se o padrão incluir uma função não determinística, como rand ou current_timestamp o valor é calculado uma vez quando o ALTER TABLE é executado, e aplicado como uma constante a linhas pré-existentes. Para linhas recém-inseridas, a expressão padrão é executada uma vez por linha.

  Quando você define um padrão usando ALTER COLUMN, as linhas existentes não são afetadas por essa alteração.

• SET Cláusula MASK

  Aplica-se a: Databricks SQL Databricks Runtime 12.2 LTS e superior apenas no Catálogo Unity

  Importante

  Esta funcionalidade está em Pré-visualização Pública.

  Adiciona uma função de máscara de coluna para anonimizar dados confidenciais. Todas as consultas subsequentes dessa coluna receberão o resultado da avaliação dessa função sobre a coluna no lugar do valor original da coluna. Isso pode ser útil para fins de controle de acesso refinado, onde a função pode inspecionar a identidade ou as associações de grupo do usuário que invoca para determinar se o valor deve ser redigido.

• DROP MASK

  Aplica-se a: apenas ao Unity Catalog

  Importante

  Esta funcionalidade está em Pré-visualização Pública.

  Remova a máscara de coluna desta coluna, se houver. Consultas futuras desta coluna receberão os valores originais da coluna.

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

  Aplica-se a: Databricks SQL Databricks Runtime 13.3 LTS e superior

  Aplique etiquetas à coluna. Você precisa ter APPLY TAG permissão para adicionar tags à coluna.

  • tag_name

    Um literal STRING. O tag_name deve ser exclusivo dentro da tabela ou coluna.

  • tag_value

    Um literal STRING.

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

  Aplica-se a: Databricks SQL Databricks Runtime 13.3 LTS e superior

  Remova as tags da coluna. Você precisa ter APPLY TAG permissão para remover tags da coluna.

  • tag_name

    Um literal STRING. O tag_name deve ser exclusivo dentro da tabela ou coluna.

Cláusula DROP COLUMN

Aplica-se a: Databricks SQL Databricks Runtime 11.3 LTS e superior

Remova uma ou mais colunas ou campos em uma tabela ou entidade.

Ao soltar uma coluna ou campo, você deve descartar restrições de verificação dependentes e colunas geradas.

Para obter os requisitos, consulte Renomear e remover colunas com mapeamento de colunas do Delta Lake.

Sintaxe

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

Parâmetros

• IF EXISTS

  Quando especifica IF EXISTS, o Azure Databricks ignora uma tentativa de eliminar colunas que não existem. Caso contrário, descartar colunas não existentes causará um erro.

• column_identifier

  O nome da coluna existente.

• field_name

  O nome totalmente qualificado de um campo existente.

Cláusula RENAME COLUMN

Aplica-se a: Databricks SQL Databricks Runtime 10.4 LTS e posteriores

Renomeia uma coluna ou campo em uma tabela Delta Lake habilitada para mapeamento de coluna.

Ao renomear uma coluna ou campo, você também precisa alterar restrições de verificação dependentes e colunas geradas. Todas as chaves primárias e chaves estrangeiras associadas à coluna serão descartadas. No caso de chaves estrangeiras, você deve possuir a tabela na qual a chave estrangeira é definida.

Para obter os requisitos e saber como ativar o mapeamento de colunas, veja Renomear e soltar colunas com o mapeamento de colunas do Delta Lake.

Sintaxe

RENAME COLUMN { column_identifier TO to_column_identifier|
                field_name TO to_field_identifier }

Parâmetros

• column_identifier

  O nome existente da coluna.

• to_column_identifier

  O novo identificador de coluna. O identificador deve ser exclusivo dentro da tabela.

• field_name

  O nome totalmente qualificado existente de um campo.

• to_field_identifier

  O novo identificador de campo. O identificador deve ser exclusivo dentro da estrutura local.

Exemplos

Veja exemplos ALTER TABLE.

Artigos relacionados

• ALTER MATERIALIZED VIEW
• ALTER STREAMING TABLE
• ALTER TABLE
• expansão do tipo