ALTER TABLE … ALTER COLUMN

Este tópico descreve como modificar uma ou mais propriedades de coluna para uma tabela usando uma cláusula ALTER COLUMN em uma instrução ALTER TABLE.

A tabela a seguir descreve as ações suportadas/não suportadas para modificar as propriedades das colunas:

Ação

Com suporte

Sem suporte

Notas

Valores padrão

Descartar o padrão para uma coluna (isto é, DROP DEFAULT).

Não permitido se a coluna e o padrão fossem definidos por um comando ALTER TABLE. Para obter mais detalhes, consulte as Notas de uso abaixo.

Alterar a sequência padrão de uma coluna (isto é, SET DEFAULT seq_name.NEXTVAL).

Usar somente para colunas que já tenham uma sequência.

Alterar o padrão para uma coluna, a menos que o padrão seja uma sequência.

Adicionar um padrão para uma coluna.

Nulidade

Alterar a nulidade de uma coluna (isto é, SET NOT NULL ou DROP NOT NULL).

Tipos de dados

Alterar um tipo de dados da coluna para um tipo sinônimo (por exemplo, STRING para VARCHAR).

Alterar um tipo de dados da coluna para um tipo diferente (por exemplo, STRING para NUMBER).

Aumentar o comprimento de uma coluna de texto/cadeia de caracteres (por exemplo VARCHAR(50) para VARCHAR(100)).

Diminuir o comprimento de uma coluna de texto/cadeia de caracteres (por exemplo VARCHAR(50) para VARCHAR(25)).

Aumentar a precisão de uma coluna de número (por exemplo, NUMBER(10,2) para NUMBER(20,2)).

Diminuir a precisão de uma coluna de número (por exemplo, NUMBER(20,2) para NUMBER(10,2)).

Somente permitido se a nova precisão for suficiente para manter todos os valores atualmente na coluna. Além disso, a diminuição da precisão pode afetar o Time Travel (consulte Notas de uso para obter detalhes).

Alterar a escala de uma coluna de número (por exemplo, NUMBER(10,2) para NUMBER(10,4)).

Comentários

Defina ou remova o comentário para uma coluna.

Política de mascaramento

Definir ou remover uma política de mascaramento Segurança em nível de coluna em uma coluna.

Marcação de objetos

Definir ou remover uma tag em uma coluna.

Uma coluna pode suportar até 20 tags, e o número máximo de caracteres para um valor de cadeia de caracteres de tags é 256.

Consulte também:

ALTER TABLE , CREATE TABLE , DROP TABLE , SHOW TABLES , DESCRIBE TABLE

Sintaxe

ALTER TABLE <name> { ALTER | MODIFY } [ ( ]
                                              [ COLUMN ] <col1_name> DROP DEFAULT
                                            , [ COLUMN ] <col1_name> SET DEFAULT <seq_name>.NEXTVAL
                                            , [ COLUMN ] <col1_name> { [ SET ] NOT NULL | DROP NOT NULL }
                                            , [ COLUMN ] <col1_name> [ [ SET DATA ] TYPE ] <type>
                                            , [ COLUMN ] <col1_name> COMMENT '<string>'
                                            , [ COLUMN ] <col1_name> UNSET COMMENT
                                          [ , [ COLUMN ] <col2_name> ... ]
                                          [ , ... ]
                                      [ ) ]

ALTER TABLE <name> { ALTER | MODIFY } COLUMN <col1_name> SET MASKING POLICY <policy_name> [ USING ( <col1_name> , cond_col_1 , ... ) ]
                                                                                          [ FORCE ]

ALTER TABLE <name> { ALTER | MODIFY } COLUMN <col1_name> UNSET MASKING POLICY

ALTER TABLE <name> { ALTER | MODIFY }
                                       [ COLUMN ] <col1_name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
                                     , [ COLUMN ] <col2_name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
                                     ...

ALTER TABLE <name> { ALTER | MODIFY }
                                       COLUMN <col1_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
                                     , COLUMN <col2_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
                                     ...

Notas de uso

  • Uma única instrução ALTER TABLE pode ser usada para modificar várias colunas em uma tabela. Cada mudança é especificada como uma cláusula que consiste na coluna e na propriedade da coluna a ser modificada, separada por vírgulas:

    • Use a palavra-chave ALTER ou MODIFY para iniciar a lista de cláusulas (ou seja, colunas/propriedades a modificar) na instrução.

    • Parênteses podem ser usados para agrupar as cláusulas, mas não são necessários.

    • A palavra-chave COLUMN pode ser especificada em cada cláusula, mas não é necessária.

    • As cláusulas podem ser especificadas em qualquer ordem.

  • Ao definir uma coluna para NOT NULL, se a coluna contiver valores NULL, um erro é retornado e nenhuma alteração é aplicada à coluna.

  • Para alterar a sequência padrão de uma coluna, a coluna já deve ter uma sequência padrão. Você não pode usar o comando ALTER TABLE ... SET DEFAULT <nome_seq> para adicionar uma sequência a uma coluna que ainda não tenha uma sequência.

  • Se você alterar uma tabela para adicionar uma coluna com um valor DEFAULT, então você não pode descartar o valor padrão para aquela coluna. Por exemplo, na sequência de instruções a seguir, a última instrução ALTER TABLE ... ALTER COLUMN causa um erro:

    CREATE TABLE t(x INT);
    INSERT INTO t VALUES (1), (2), (3);
    ALTER TABLE t ADD COLUMN y INT DEFAULT 100;
    INSERT INTO t(x) VALUES (4), (5), (6);
    
    ALTER TABLE t ALTER COLUMN y DROP DEFAULT;
    

    Esta restrição evita a inconsistência entre os valores nas linhas inseridas antes da adição da coluna e as linhas inseridas após a adição da coluna. Se o padrão fosse descartado, então a coluna conteria:

    • Um valor NULL para as linhas inseridas antes da adição da coluna.

    • O valor padrão das linhas inseridas depois que a coluna era adicionada.

    Também é proibido remover o valor padrão da coluna de qualquer clone da tabela.

  • Ao definir o TYPE para uma coluna, o tipo especificado (isto é, type) deve ser NUMBER ou um tipo de dados de texto (VARCHAR, STRING, TEXT etc.).

    • Para o tipo de dados NUMBER, TYPE pode ser usado para:

      • Aumentar a precisão da coluna de números especificada.

      • Diminuir a precisão da coluna de números especificada se a nova precisão for suficiente para manter todos os valores de dados atualmente na coluna.

    • Para tipos de dados de texto, TYPE só pode ser usado para aumentar o comprimento da coluna.

  • Se a precisão de uma coluna for diminuída e ficar abaixo da precisão máxima de qualquer dado de coluna retido no Time Travel, não será possível restaurar a tabela sem antes aumentar a precisão.

  • Para políticas de mascaramento:

    • A cláusula USING e a palavra-chave FORCE são ambas opcionais; nenhuma delas é necessária para definir uma política de mascaramento em uma coluna. A cláusula USING e a palavra-chave FORCE podem ser usadas separadamente ou em conjunto. Para obter mais detalhes, consulte:

    • Uma única política de mascaramento que utilize colunas condicionais pode ser aplicada a várias tabelas, desde que a estrutura de colunas da tabela corresponda às colunas especificadas na política.

    • Ao modificar uma ou mais colunas da tabela com uma política de mascaramento ou a própria tabela com uma política de acesso a linhas, use a função POLICY_CONTEXT para simular uma consulta na(s) coluna(s) protegida(s) por uma política de mascaramento e na tabela protegida por uma política de acesso a linhas.

  • Em relação aos metadados (por exemplo, o campo COMMENT):

    Atenção

    Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

Exemplos

Exemplo de configuração:

CREATE OR REPLACE TABLE t1 (
   c1 NUMBER NOT NULL,
   c2 NUMBER DEFAULT 3,
   c3 NUMBER DEFAULT seq1.nextval,
   c4 VARCHAR(20) DEFAULT 'abcde',
   c5 STRING);

DESC TABLE t1;

+------+-------------------+--------+-------+-------------------------+-------------+------------+-------+------------+---------+
| name | type              | kind   | null? | default                 | primary key | unique key | check | expression | comment |
|------+-------------------+--------+-------+-------------------------+-------------+------------+-------+------------+---------|
| C1   | NUMBER(38,0)      | COLUMN | N     | NULL                    | N           | N          | NULL  | NULL       | NULL    |
| C2   | NUMBER(38,0)      | COLUMN | Y     | 3                       | N           | N          | NULL  | NULL       | NULL    |
| C3   | NUMBER(38,0)      | COLUMN | Y     | DB1.PUBLIC.SEQ1.NEXTVAL | N           | N          | NULL  | NULL       | NULL    |
| C4   | VARCHAR(20)       | COLUMN | Y     | 'abcde'                 | N           | N          | NULL  | NULL       | NULL    |
| C5   | VARCHAR(16777216) | COLUMN | Y     | NULL                    | N           | N          | NULL  | NULL       | NULL    |
+------+-------------------+--------+-------+-------------------------+-------------+------------+-------+------------+---------+

Fazer as seguintes mudanças em t1:

  • Alterar a coluna NOT NULL c1 para NULL.

  • Abandonar o padrão da coluna c2 e alterar a sequência padrão da coluna c3.

  • Aumentar o comprimento da coluna c4 e descartar o padrão para a coluna.

  • Adicionar um comentário para a coluna c5.

ALTER TABLE t1 ALTER COLUMN c1 DROP NOT NULL;

ALTER TABLE t1 MODIFY c2 DROP DEFAULT, c3 SET DEFAULT seq5.nextval ;

ALTER TABLE t1 ALTER c4 SET DATA TYPE VARCHAR(50), COLUMN c4 DROP DEFAULT;

ALTER TABLE t1 ALTER c5 COMMENT '50 character column';

DESC TABLE t1;

+------+-------------------+--------+-------+-------------------------+-------------+------------+-------+------------+---------------------+
| name | type              | kind   | null? | default                 | primary key | unique key | check | expression | comment             |
|------+-------------------+--------+-------+-------------------------+-------------+------------+-------+------------+---------------------|
| C1   | NUMBER(38,0)      | COLUMN | Y     | NULL                    | N           | N          | NULL  | NULL       | NULL                |
| C2   | NUMBER(38,0)      | COLUMN | Y     | NULL                    | N           | N          | NULL  | NULL       | NULL                |
| C3   | NUMBER(38,0)      | COLUMN | Y     | DB1.PUBLIC.SEQ5.NEXTVAL | N           | N          | NULL  | NULL       | NULL                |
| C4   | VARCHAR(50)       | COLUMN | Y     | NULL                    | N           | N          | NULL  | NULL       | NULL                |
| C5   | VARCHAR(16777216) | COLUMN | Y     | NULL                    | N           | N          | NULL  | NULL       | 50 character column |
+------+-------------------+--------+-------+-------------------------+-------------+------------+-------+------------+---------------------+

O mesmo do exemplo anterior, mas com as seguintes mudanças para ilustrar a versatilidade/flexibilidade do comando:

  • Todas as ações executadas em uma única cláusula ALTER COLUMN.

  • A ordem das colunas dentro da cláusula é diferente.

  • SET DATA TYPE abreviado para TYPE.

ALTER TABLE t1 ALTER (
   c1 DROP NOT NULL,
   c5 COMMENT '50 character column',
   c4 TYPE VARCHAR(50),
   c2 DROP DEFAULT,
   COLUMN c4 DROP DEFAULT,
   COLUMN c3 SET DEFAULT seq5.nextval
  );

Este exemplo produz os mesmos resultados.

Aplique uma política de mascaramento de segurança em nível de coluna a uma coluna de tabela:

-- single column

ALTER TABLE empl_info MODIFY COLUMN empl_id SET MASKING POLICY mask_empl_id;

-- multiple columns

ALTER TABLE empl_info MODIFY
    COLUMN empl_id SET MASKING POLICY mask_empl_id
  , COLUMN empl_dob SET MASKING POLICY mask_empl_dob
;

Remover uma política de mascaramento de segurança em nível de coluna de uma coluna da tabela:

-- single column

ALTER TABLE empl_info modify column empl_id unset masking policy;

-- multiple columns

ALTER TABLE empl_info MODIFY
    COLUMN empl_id UNSET MASKING POLICY
  , COLUMN empl_dob UNSET MASKING POLICY
;