ALTER TABLE ... COLUMN cláusula

Aplica-se a: SQL do Databricks Databricks Runtime

Adiciona, modifica ou descarta uma coluna em uma tabela ou um campo em uma coluna em uma tabela Delta Lake.

Permissões necessárias

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

• ALTER COLUMN
• ADD COLUMN
• DROP COLUMN

Todas as outras operações exigem 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

Essa cláusula não tem suporte das fontes de dados JDBC.

Adiciona uma ou mais colunas à tabela ou aos campos às colunas existentes em uma tabela do 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 precisa ser exclusivo dentro da tabela.

  A menos que FIRST ou AFTER name esteja especificado, a coluna ou campo será anexado ao 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 exclusivo.

  Para adicionar campos a structs aninhados 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: SQL do Databricks Databricks Runtime 11.3 LTS e versões posteriores

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

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

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

  • Funções de agregação
  • Funções de janela analíticas
  • Classificação de funções de janela
  • Funções geradoras com valor de tabela

  default_expression não deve conter nenhuma subconsulta.

  DEFAULT há suporte para as fontes CSV, JSON, PARQUET e ORC.

• tipo_de_dado

  Especifica o tipo dos dados da coluna ou campo. Nem todos os tipos de dados com suporte pelo Azure Databricks têm suporte de todas as fontes de dados.

• COLLATE collation_name

  data_type STRING especifica opcionalmente a ordenação a ser usada com a coluna ou o campo. Se não for especificado, a UTF8_BINARY ordenação se aplicará.

• COMMENT comment

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

  Se quiser adicionar um comentário gerado por IA em uma tabela ou coluna de tabela gerenciada pelo Catálogo do Unity, confira Adicionar comentários gerados por IA a objetos do catálogo do Unity.

• FIRST

  Se especificado, a coluna será adicionada como a primeira coluna da tabela ou o campo será adicionado como o primeiro campo de no struct contido.

• AFTER identificador

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

• Cláusula MASK

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

  Importante

  Esse recurso está em uma versão prévia.

  Adiciona uma função de máscara de coluna para anonimizar dados confidenciais. Todas as consultas subsequentes dessa coluna receberão o resultado da aplicação dessa função na coluna, em substituição ao valor original da coluna. Isso pode ser útil para fins de um controle de acesso detalhado, em que a função pode inspecionar a identidade e/ou as filiações a grupos do usuário que a invocou para determinar se quer ocultar o valor.

Cláusula ALTER COLUMN

Aplica-se a: SQL do Databricks Databricks Runtime

Altera uma propriedade ou o local 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 dá suporte à 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 coluna column_name. comment deve ser uma literal de STRING.

• FIRST ou AFTERidentificador

  Move a coluna de sua posição atual para a frente (FIRST) ou imediatamente AFTER o identifier. Só haverá suporte para essa cláusula se table_name for uma tabela Delta.

• TYPE tipo_de_dado

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

  Altera o tipo de dados da coluna column_name.

  Só haverá suporte para essa cláusula 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 coluna VARCHAR, por exemplo, de VARCHAR(5)para VARCHAR(10)
  • Alterar o tipo de uma coluna CHAR para 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.enableTypeWideningdefinido como true:

  Importante

  Esse recurso está em Visualização pública no Databricks Runtime 15.2 e superior.

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

  Para obter informações mais detalhadas sobre ampliação de tipo, veja Ampliação de tipo.

• SET NOT NULL ou DROP NOT NULL

  Altera o domínio de valores de coluna válidos para excluir SET NOT NULL nulos ou incluir DROP NOT NULL nulos. Só há suporte para essa opção em tabelas do 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: SQL do Databricks Databricks Runtime 10.4 LTS e versões posteriores

  Sincronizar 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. Essa 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, em que n é o valor que satisfaz start + n * step >= max() (para uma etapa positiva).

  Só há suporte dessa opção para colunas de identidade em tabelas do Delta Lake.

• DROP DEFAULT

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

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

• SET DEFAULT default_expression

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

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

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

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

  • Funções de agregação
  • Funções de janela analíticas
  • Classificação de funções de janela
  • Funções geradoras com valor de tabela

  default_expression não deve conter nenhuma subconsulta.

  DEFAULT há suporte para as fontes CSV, JSON, ORC e PARQUET.

  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 quando 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 linhas.

  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: SQL do Databricks Databricks Runtime 12.2 LTS e versões posteriores Somente Catálogo do Unity

  Importante

  Esse recurso está em uma versão prévia.

  Adiciona uma função de máscara de coluna para anonimizar dados confidenciais. Todas as consultas subsequentes dessa coluna receberão o resultado da aplicação dessa função na coluna, em substituição ao valor original da coluna. Isso pode ser útil para fins de um controle de acesso detalhado, em que a função pode inspecionar a identidade e/ou as filiações a grupos do usuário que a invocou para determinar se quer ocultar o valor.

• DROP MASK

  Aplica-se a: Somente Catálogo do Unity

  Importante

  Esse recurso está em uma versão prévia.

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

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

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

  Aplicar marcas à coluna. Você precisa ter a permissão APPLY TAG para adicionar marcas à coluna.

  • nome_da_tag

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

  • tag_value

    Um literal STRING.

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

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

  Remover marcas da coluna. Você precisa ter a permissão APPLY TAG para remover marcas da coluna.

  • nome_da_tag

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

Cláusula DROP COLUMN

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

Remova uma ou mais colunas ou campos em uma relação.

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

Para obter os requisitos, confira Renomear e remover colunas usando o mapeamento de colunas do Delta Lake.

Sintaxe

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

Parâmetros

• IF EXISTS

  Ao especificar IF EXISTS, o Azure Databricks ignora uma tentativa de remover colunas que não existem. Caso contrário, remoção de colunas não existentes causarão 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: SQL do Databricks Databricks Runtime 10.4 LTS e versões posteriores

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

Ao renomear uma coluna ou campo, você também precisa alterar as restrições de verificação dependentes e as colunas geradas. Quaisquer chaves primárias e estrangeiras que usam a coluna serão removidas. No caso de chaves estrangeiras, você deve ter a propriedade da tabela na qual a chave estrangeira está definida.

Para obter os requisitos e como habilitar o mapeamento de coluna, consulte Renomear e descartar colunas com o mapeamento de coluna 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 da 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 do struct local.

Exemplos

Veja ALTER TABLE exemplos.

Artigos relacionados

• ALTER MATERIALIZED VIEW
• ALTER STREAMING TABLE
• ALTER TABLE
• tipo ampliação