ALTER TABLE¶

Sintaxe¶

ALTER TABLE [ IF EXISTS ] <name> RENAME TO <new_table_name>

ALTER TABLE [ IF EXISTS ] <name> SWAP WITH <target_table_name>

ALTER TABLE [ IF EXISTS ] <name> { clusteringAction | tableColumnAction | constraintAction  }

ALTER TABLE [ IF EXISTS ] <name> dataMetricFunctionAction

ALTER TABLE [ IF EXISTS ] <name> dataGovnPolicyTagAction

ALTER TABLE [ IF EXISTS ] <name> extTableColumnAction

ALTER TABLE [ IF EXISTS ] <name> searchOptimizationAction

ALTER TABLE [ IF EXISTS ] <name> SET
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ CHANGE_TRACKING = { TRUE | FALSE  } ]
  [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
  [ ENABLE_SCHEMA_EVOLUTION = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]

ALTER TABLE [ IF EXISTS ] <name> UNSET {
                                       DATA_RETENTION_TIME_IN_DAYS         |
                                       MAX_DATA_EXTENSION_TIME_IN_DAYS     |
                                       CHANGE_TRACKING                     |
                                       DEFAULT_DDL_COLLATION               |
                                       ENABLE_SCHEMA_EVOLUTION             |
                                       COMMENT                             |
                                       }
                                       [ , ... ]

Onde:

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
     /* RECLUSTER is deprecated */
   | RECLUSTER [ MAX_SIZE = <budget_in_bytes> ] [ WHERE <condition> ]
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }

Copy

tableColumnAction ::=
  {
     ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
        [
           {
              DEFAULT <default_value>
              | { AUTOINCREMENT | IDENTITY }
                 /* AUTOINCREMENT (or IDENTITY) is supported only for           */
                 /* columns with numeric data types (NUMBER, INT, FLOAT, etc.). */
                 /* Also, if the table is not empty (i.e. if the table contains */
                 /* any rows), only DEFAULT can be altered.                     */
                 [
                    {
                       ( <start_num> , <step_num> )
                       | START <num> INCREMENT <num>
                    }
                 ]
                 [  { ORDER | NOORDER } ]
           }
        ]
        [ inlineConstraint ]
        [ COLLATE '<collation_specification>' ]

   | RENAME COLUMN <col_name> TO <new_col_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> ... ]
                        [ , ... ]
                    [ ) ]

   | DROP [ COLUMN ] [ IF EXISTS ] <col1_name> [, <col2_name> ... ]
  }

  inlineConstraint ::=
    [ NOT NULL ]
    [ CONSTRAINT <constraint_name> ]
    { UNIQUE | PRIMARY KEY | { [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ] } }
    [ <constraint_properties> ]

Copy

Para obter sintaxes detalhadas e exemplos de alteração de colunas, consulte ALTER TABLE … ALTER COLUMN. .

Para obter sintaxes detalhadas e exemplos de criação/alteração de restrições em linha, consulte CREATE | ALTER TABLE … CONSTRAINT.

dataMetricFunctionAction ::=

    SET DATA_METRIC_SCHEDULE = {
        '<num> MINUTE'
      | 'USING CRON <expr> <time_zone>'
      | 'TRIGGER_ON_CHANGES'
    }

  | UNSET DATA_METRIC_SCHEDULE

  | { ADD | DROP } DATA METRIC FUNCTION <metric_name>
      ON ( <col_name> [ , ... ] )
      [ , <metric_name_2> ON ( <col_name> [ , ... ] ) ]
  | MODIFY DATA METRIC FUNCTION <metric_name>
      ON ( <col_name> [ , ... ] ) { SUSPEND | RESUME }
      [ , <metric_name_2> ON ( <col_name> [ , ... ] ) { SUSPEND | RESUME } ]

Copy

dataGovnPolicyTagAction ::=
  {
      SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
    | UNSET TAG <tag_name> [ , <tag_name> ... ]
  }
  |
  {
      ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ROW ACCESS POLICY <policy_name>
    | DROP ROW ACCESS POLICY <policy_name> ,
        ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ALL ROW ACCESS POLICIES
  }
  |
  {
      SET AGGREGATION POLICY <policy_name>
        [ ENTITY KEY ( <col_name> [, ... ] ) ]
        [ FORCE ]
    | UNSET AGGREGATION POLICY
  }
  |
  ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
    [ [ WITH ] MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] ]
    [ [ WITH ] PROJECTION POLICY <policy_name> ]
    [ [ WITH ] TAG ( <tag_name> = '<tag_value>'
          [ , <tag_name> = '<tag_value>' , ... ] ) ]
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] [ FORCE ]
      | UNSET MASKING POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET PROJECTION POLICY <policy_name>
          [ FORCE ]
      | UNSET PROJECTION POLICY
  }
  |
  { 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 | MODIFY } [ COLUMN ] <col1_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
                   , [ COLUMN ] <col2_name> UNSET TAG <tag_name> [ , <tag_name> ... ]

Copy

extTableColumnAction ::=
  {
     ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type> AS ( <expr> )

   | RENAME COLUMN <col_name> TO <new_col_name>

   | DROP [ COLUMN ] [ IF EXISTS ] <col1_name> [, <col2_name> ... ]
  }

Copy

constraintAction ::=
  {
     ADD outoflineConstraint
   | RENAME CONSTRAINT <constraint_name> TO <new_constraint_name>
   | { ALTER | MODIFY } { CONSTRAINT <constraint_name> | PRIMARY KEY | UNIQUE | FOREIGN KEY } ( <col_name> [ , ... ] )
                         [ [ NOT ] ENFORCED ] [ VALIDATE | NOVALIDATE ] [ RELY | NORELY ]
   | DROP { CONSTRAINT <constraint_name> | PRIMARY KEY | UNIQUE | FOREIGN KEY } ( <col_name> [ , ... ] )
                         [ CASCADE | RESTRICT ]
  }

  outoflineConstraint ::=
    [ CONSTRAINT <constraint_name> ]
    {
       UNIQUE [ ( <col_name> [ , <col_name> , ... ] ) ]
     | PRIMARY KEY [ ( <col_name> [ , <col_name> , ... ] ) ]
     | [ FOREIGN KEY ] [ ( <col_name> [ , <col_name> , ... ] ) ]
                          REFERENCES <ref_table_name> [ ( <ref_col_name> [ , <ref_col_name> , ... ] ) ]
    }
    [ <constraint_properties> ]

Copy

Para obter sintaxes detalhadas e exemplos de criação/alteração de restrições fora de linha, consulte CREATE | ALTER TABLE … CONSTRAINT.

searchOptimizationAction ::=
  {
     ADD SEARCH OPTIMIZATION [
       ON <search_method_with_target> [ , <search_method_with_target> ... ]
     ]

   | DROP SEARCH OPTIMIZATION [
       ON { <search_method_with_target> | <column_name> | <expression_id> }
          [ , ... ]
     ]
  }

Copy

Para obter mais detalhes, consulte Ações de otimização de pesquisa (searchOptimizationAction).

Parâmetros¶

name

Identificador da tabela a ser alterada. Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Identificadores entre aspas duplas também diferenciam maiúsculas de minúsculas.

RENAME TO new_table_name

Renomeia a tabela especificada com um novo identificador que não está sendo usado atualmente por nenhuma outra tabela no esquema.

Para obter mais informações sobre identificadores de tabela, consulte Requisitos para identificadores.

Você pode mover o objeto para um banco de dados e/ou esquema diferente enquanto opcionalmente renomeia o objeto. Para isso, especifique um valor qualificado new_name que inclua o novo banco de dados e/ou nome do esquema no formulário db_name.schema_name.object_name ou schema_name.object_name, respectivamente.

Nota

• O banco de dados e/ou esquema de destino já deve existir. Além disso, um objeto com o mesmo nome não pode já existir no banco de dados de destino; caso contrário, a instrução retorna um erro.

• É proibido mover um objeto para um esquema de acesso gerenciado a menos que o proprietário do objeto (ou seja, a função que tem o privilégio OWNERSHIP sobre o objeto) também possua o esquema de destino.

Quando um objeto (tabela, coluna etc.) é renomeado, outros objetos que fazem referência a ele devem ser atualizados com o novo nome.

SWAP WITH target_table_name

A troca renomeia duas tabelas em uma única transação.

Observe que a troca de uma tabela permanente ou transitória por uma tabela temporária, existente apenas durante a sessão do usuário em que foi criada, não é permitida. Esta restrição evita um conflito de nomes que pode ocorrer quando uma tabela temporária é trocada por uma tabela permanente ou transitória, e uma tabela permanente ou transitória existente tem o mesmo nome que a tabela temporária. Para trocar uma tabela permanente ou transitória por uma tabela temporária, use três instruções ALTER TABLE ... RENAME TO: renomear tabela a como c, b como a e c como b.

SET ...

Especifica uma ou mais propriedades/parâmetros a serem definidos para a tabela (separados por espaços em branco, vírgulas ou novas linhas):

DATA_RETENTION_TIME_IN_DAYS = integer

Parâmetro de nível de objeto que modifica o período de retenção da tabela do Time Travel. Para obter mais informações, consulte Compreensão e uso do Time Travel e Como trabalhar com tabelas temporárias e transitórias.

Para uma descrição detalhada deste parâmetro, bem como mais informações sobre parâmetros de objetos, consulte Parâmetros.

Valores:

• Standard Edition: 0 ou 1

• Enterprise Edition:

  • 0 a 90 para tabelas permanentes

  • 0 ou 1 para tabelas temporárias e transitórias

Nota

Um valor de 0 desabilita efetivamente o Time Travel para a tabela.

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

Parâmetro de objeto que especifica o número máximo de dias para os quais o Snowflake pode estender o período de retenção de dados da tabela para evitar que os fluxos na tabela se tornem obsoletos.

Para uma descrição detalhada deste parâmetro, consulte MAX_DATA_EXTENSION_TIME_IN_DAYS.

CHANGE_TRACKING = TRUE | FALSE

Especifica a habilitação ou desabilitação do rastreamento de alterações na tabela.

• TRUE habilita o rastreamento de alterações na tabela. Essa opção adiciona algumas colunas ocultas à tabela de origem e começa a armazenar os metadados de rastreamento de alterações nas colunas. Estas colunas consomem uma pequena quantidade de armazenamento.

  Os metadados de rastreamento de alterações podem ser consultados usando a cláusula CHANGES para instruções SELECT ou criando e consultando um ou mais fluxos na tabela.

• FALSE desabilita o rastreamento de alterações na tabela. As colunas ocultas associadas são descartadas da tabela.

DEFAULT_DDL_COLLATION = 'collation_specification'

Determina uma especificação de agrupamento padrão para novas colunas adicionadas à tabela.

A definição do parâmetro não altera a especificação de agrupamento para qualquer coluna existente.

Para obter mais informações sobre o parâmetro, consulte DEFAULT_DDL_COLLATION.

ENABLE_SCHEMA_EVOLUTION = { TRUE | FALSE }

Ativa ou desativa as alterações automáticas no esquema da tabela a partir dos dados carregados na tabela dos arquivos de origem, incluindo:

• Colunas adicionadas.

  Por padrão, a evolução do esquema é limitada a um máximo de 10 colunas adicionadas por operação de carregamento. Para solicitar mais de 10 colunas adicionadas por operação de carga, entre em contato com o suporte Snowflake.

• A restrição NOT NULL pode ser descartada de qualquer número de colunas ausentes em novos arquivos de dados.

Configurando como TRUE permite a evolução automática do esquema da tabela. O padrão FALSE desativa a evolução automática do esquema da tabela.

Nota

O carregamento de dados de arquivos evolui as colunas da tabela quando todas as condições a seguir forem verdadeiras:

• A instrução COPY INTO <tabela> inclui a opção MATCH_BY_COLUMN_NAME.

• A função usada para carregar os dados tem o privilégio EVOLVE SCHEMA ou OWNERSHIP na tabela.

Além disso, para a evolução do esquema com CSV, quando usado com MATCH_BY_COLUMN_NAME e PARSE_HEADER, ERROR_ON_COLUMN_COUNT_MISMATCH deve ser definido como falso.

COMMENT = 'string_literal'

Adiciona um comentário ou substitui o comentário existente da tabela.

UNSET ...

Especifica uma ou mais propriedades/parâmetros a serem desativados para a tabela, o que os restaura aos seus padrões:

• DATA_RETENTION_TIME_IN_DAYS

• MAX_DATA_EXTENSION_TIME_IN_DAYS

• CHANGE_TRACKING

• DEFAULT_DDL_COLLATION

• ENABLE_SCHEMA_EVOLUTION

• COMMENT

Ações de clustering (clusteringAction)¶

CLUSTER BY ( expr [ , expr , ... ] )

Especifica (ou modifica) uma ou mais colunas de tabela ou expressões de coluna como a chave de clustering da tabela. No caso dessas colunas/expressões, o Clustering automático mantém o clustering.

Importante

As chaves de clustering não são destinadas ou recomendadas para todas as tabelas; elas normalmente são vantajosas para tabelas muito grandes (ou seja, com vários terabytes).

Antes de especificar uma chave de clustering para uma tabela, consulte Explicação das estruturas de tabela do Snowflake.

RECLUSTER ...

Obsoleto

Executa o reclustering manual e incremental de uma tabela que tem uma chave de clustering definida:

MAX_SIZE = budget_in_bytes

Obsoleto — use um warehouse maior para obter um reclustering manual mais eficiente

Especifica o limite superior da quantidade de dados (em bytes) na tabela para reclustering.

WHERE condition

Especifica uma condição ou faixa na qual é feito o reclustering dos dados na tabela.

Nota

Somente funções com o privilégio OWNERSHIP ou INSERT em uma tabela podem fazer o reclustering da tabela.

SUSPEND | RESUME RECLUSTER

Habilita ou desabilita Clustering automático para a tabela.

DROP CLUSTERING KEY

Descarta a chave de clustering para a tabela.

Para obter mais informações sobre chaves de clustering e reclustering, consulte Explicação das estruturas de tabela do Snowflake.

Ações de coluna da tabela (tableColumnAction)¶

ADD [ COLUMN ] [ IF NOT EXISTS ] col_name col_data_type . [ DEFAULT default_value | AUTOINCREMENT ... ] . [ inlineConstraint ] [ COLLATE 'collation_specification' ] . [ [ WITH ] MASKING POLICY policy_name ] . [ [ WITH ] PROJECTION POLICY policy_name ] . [ [ WITH ] TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] ) ] [ , ...]

Adiciona uma nova coluna. Você pode especificar um valor padrão, uma restrição inline, uma especificação de agrupamento, uma política de mascaramento e/ou uma ou mais tags.

Um valor padrão para uma coluna que você está adicionando deve ser um valor literal; não pode ser uma expressão ou um valor retornado por uma função. Por exemplo, o comando a seguir retorna um erro esperado:

ALTER TABLE t1 ADD COLUMN c5 VARCHAR DEFAULT 12345::VARCHAR;

Copy

002263 (22000): SQL compilation error:
Invalid column default expression [CAST(12345 AS VARCHAR(16777216))]

Ao criar uma tabela pela primeira vez, você pode usar expressões como valores padrão, mas não ao adicionar colunas.

O valor padrão de uma coluna deve corresponder ao tipo de dados da coluna. Uma tentativa de definir um valor padrão com um tipo de dados não correspondente falha com um erro. Por exemplo:

ALTER TABLE t1 ADD COLUMN c6 DATE DEFAULT '20230101';

Copy

002023 (22000): SQL compilation error:
Expression type does not match column data type, expecting DATE but got VARCHAR(8) for column C6

Para obter detalhes adicionais sobre ações de coluna de tabela, consulte:

• CREATE TABLE

• CREATE | ALTER TABLE … CONSTRAINT

• CREATE MASKING POLICY

• CREATE TAG

As operações ADD COLUMN podem ser realizadas em várias colunas no mesmo comando.

Se não tiver certeza se a coluna já existe, você poderá especificar IF NOT EXISTS ao adicionar a coluna. Se a coluna já existir, ADD COLUMN não terá efeito na coluna existente e não resultará em erro.

Nota

Você não poderá especificar IF NOT EXISTS se também estiver especificando qualquer uma das seguintes opções para a nova coluna:

• DEFAULT, AUTOINCREMENT ou IDENTITY

• UNIQUE, PRIMARY KEY ou FOREIGN KEY

RENAME COLUMN col_name to new_col_name

Renomeia a coluna especificada com um novo nome que atualmente não é usado para nenhuma outra coluna da tabela.

Você não pode renomear uma coluna que faz parte de uma chave de clustering.

Quando um objeto (tabela, coluna etc.) é renomeado, outros objetos que fazem referência a ele devem ser atualizados com o novo nome.

DROP COLUMN [ IF EXISTS ] col_name [ CASCADE | RESTRICT ]

Remove a coluna especificada da tabela.

Se não tiver certeza se a coluna já existe, você poderá especificar IF EXISTS ao descartar a coluna. Se a coluna não existir, DROP COLUMN não terá efeito e não resultará em erro.

O descarte de uma coluna é uma operação somente de metadados. Ele não regrava imediatamente a(s) micropartição(ões) e, portanto, não libera imediatamente o espaço utilizado pela coluna. Normalmente, o espaço dentro de uma micropartição individual é liberado na próxima vez em que a micropartição é regravada, o que normalmente ocorre quando uma gravação é feita devido a DML (INSERT, UPDATE, DELETE) ou a reclustering.

Ações de função de métrica de dados (dataMetricFunctionAction)¶

DATA_METRIC_SCHEDULE ...

Especifica o agendamento para executar a função de métrica de dados periodicamente.

'num MINUTE'

Especifica um intervalo (em minutos) de espera inserido entre as execuções da função da métrica de dados. Aceita apenas números inteiros positivos.

Também oferece suporte à sintaxe num M.

Para funções de métricas de dados, use um dos seguintes valores: 5, 15, 30, 60, 720 ou 1440.

'USING CRON expr time_zone'

Especifica uma expressão cron e um fuso horário para executar periodicamente a função da métrica de dados. Oferece suporte a um subconjunto de sintaxe de utilitário cron padrão.

Para uma lista de fusos horários, consulte a lista de fusos horários do banco de dados tz.

A expressão cron consiste nos seguintes campos e o intervalo periódico deve ser de pelo menos 5 minutos:

# __________ minute (0-59)
# | ________ hour (0-23)
# | | ______ day of month (1-31, or L)
# | | | ____ month (1-12, JAN-DEC)
# | | | | _ day of week (0-6, SUN-SAT, or L)
# | | | | |
# | | | | |
  * * * * *

Copy

Os seguintes caracteres especiais são suportados:

*

Curinga. Especifica qualquer ocorrência do campo.

L

Significa “último”. Quando usado no campo do dia da semana, permite especificar construções como “a última sexta-feira” (“5L”) de um determinado mês. No campo do dia do mês, ele especifica o último dia do mês.

/{n}

Indica a enésima instância de uma determinada unidade de tempo. Cada quanta de tempo é computada independentemente. Por exemplo, se 4/3 estiver especificado no campo do mês, a função de métrica de dados será programada para abril, julho e outubro (ou seja, a cada 3 meses, começando com o quarto mês do ano). O mesmo cronograma é mantido nos anos seguintes. Ou seja, a função da métrica de dados não está programada para ser executada em janeiro (3 meses após a execução de outubro).

Nota

• Atualmente, a expressão cron avalia apenas em relação ao fuso horário especificado. Alterar o valor do parâmetro TIMEZONE para a conta (ou definir o valor no nível do usuário ou da sessão) não altera o fuso horário da função da métrica de dados.

• A expressão cron define todos os tempos de execução válidos para a função da métrica de dados. O Snowflake tenta executar uma função da métrica de dados com base neste cronograma; no entanto, qualquer tempo de execução válido é ignorado se uma execução anterior não tiver sido concluída antes do próximo tempo de execução válido começar.

• Quando tanto um dia específico do mês como um dia da semana são incluídos na expressão cron, a função da métrica de dados é programada em dias que satisfaçam o dia do mês ou o dia da semana. Por exemplo, DATA_METRIC_SCHEDULE = 'USING CRON 0 0 10-20 * TUE,THU UTC' programa uma função da métrica de dados no horário 0AM em qualquer dia de 10 a 20 e também em qualquer terça-feira ou quinta-feira fora dessas datas.

• A granularidade de tempo mais curta em cron é de minutos.

  Se uma função de métricas de dados for retomada durante o minuto definido em sua expressão cron, a primeira execução agendada da função de métrica de dados será a próxima ocorrência da instância da expressão cron. Por exemplo, se a função de métricas de dados agendada para ser executada diariamente à meia-noite (USING CRON 0 0 * * *) for retomada à meia-noite mais 5 segundos (00:00:05), a primeira execução da função de métrica de dados será programada para a meia-noite seguinte.

'TRIGGER_ON_CHANGES'

Especifica que a DMF é executada quando uma operação DML modifica a tabela, como inserir uma nova linha ou excluir uma linha.

É possível especificar 'TRIGGER_ON_CHANGES' para os seguintes objetos:

• Tabelas dinâmicas

• Tabelas externas

• Tabelas Apache Iceberg™

• Tabelas regulares

• Tabelas temporárias

• Tabelas transitórias

Alterações na tabela como resultado de reclustering não acionam a execução da DMF.

{ ADD | DROP } DATA METRIC FUNCTION metric_name

Identificador da função de métrica de dados a ser adicionada à tabela ou exibição ou removida da tabela ou exibição.

ON ( col_name [ , ... ] )

As colunas da tabela ou exibição nas quais a função de métrica de dados será associada. Os tipos de dados das colunas devem corresponder aos tipos de dados das colunas especificados na definição da função de métrica de dados.

[ , metric_name_2 ON ( col_name [ , ... ] ) [ , ... ] ]

Funções de métricas de dados adicionais para adicionar à tabela ou exibição. Use uma vírgula para separar cada função de métrica de dados e suas colunas especificadas.

MODIFY DATA METRIC FUNCTION metric_name

Identificador da função de métricas de dados a ser modificada.

ON ( col_name [ , ... ] ) { SUSPEND | RESUME }

Suspende ou retoma a função de métricas de dados nas colunas especificadas. Quando uma função de métrica de dados é definida para uma tabela ou exibição, a função de métricas de dados é automaticamente incluída na cronograma.

• SUSPEND remove a função de métricas de dados do cronograma.

• RESUME traz uma função de métricas de dados suspensa de volta ao cronograma.

[ , metric_name_2 ON ( col_name [ , ... ] ) [ , ... ] { SUSPEND | RESUME } ]

Funções de métricas de dados adicionais para suspender ou retomar. Use uma vírgula para separar cada função de métrica de dados e suas colunas especificadas.

Para obter detalhes sobre os requisitos de controle de acesso para essas ações, consulte Privilégios de DMF.

Ações de coluna da tabela externa (extTableColumnAction)¶

Para todas as outras modificações da tabela externa, consulte ALTER EXTERNAL TABLE.

ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type> AS ( <expr> ) [, ...]

Adiciona uma nova coluna à tabela externa.

Se não tiver certeza se a coluna já existe, você poderá especificar IF NOT EXISTS ao adicionar a coluna. Se a coluna já existir, ADD COLUMN não terá efeito na coluna existente e não resultará em erro.

Essa operação pode ser realizada em várias colunas no mesmo comando.

col_name

Cadeia de caracteres que especifica o identificador da coluna (ou seja, o nome). Todos os requisitos de identificadores de tabela também se aplicam aos identificadores de coluna.

Para obter mais informações, consulte Requisitos para identificadores.

col_type

Cadeia de caracteres (constante) que especifica o tipo de dados da coluna. O tipo de dados deve corresponder ao resultado de expr da coluna.

Para obter mais detalhes sobre os tipos de dados que podem ser especificados para colunas de tabela, consulte Referência dos tipos de dados SQL.

expr

Cadeia de caracteres que especifica a expressão da coluna. Quando consultada, a coluna retorna resultados derivados dessa expressão.

As colunas da tabela externa são colunas virtuais, que são definidas usando uma expressão explícita. Adicione colunas virtuais como expressões usando a coluna VALUE e/ou a pseudocoluna METADATA$FILENAME:

VALUE:

Uma coluna do tipo VARIANT que representa uma única linha no arquivo externo.

CSV:

A coluna VALUE estrutura cada linha como um objeto com elementos identificados pela posição da coluna (ou seja, {c1: <valor_da_coluna_1>, c2: <valor_da_coluna_2>, c3: <valor_da_coluna_1> ...}).

Por exemplo, adicione uma coluna VARCHAR chamada mycol que faça referência à primeira coluna nos arquivos CSV preparados:

mycol varchar as (value:c1::varchar)

Copy

Dados semiestruturados:

Inclua os nomes e valores dos elementos entre aspas duplas. Percorra o caminho na coluna VALUE usando a notação de pontos.

Por exemplo, suponha que o seguinte represente uma única linha de dados semiestruturados em um arquivo preparado:

{ "a":"1", "b": { "c":"2", "d":"3" } }

Copy

Adicione uma coluna VARCHAR chamada mycol que faça referência ao elemento c repetido aninhado no arquivo preparado:

mycol varchar as (value:"b"."c"::varchar)

Copy

METADATA$FILENAME:

Uma pseudocoluna que identifica o nome de cada arquivo de dados preparado incluído na tabela externa, incluindo seu caminho no estágio.

RENAME COLUMN col_name to new_col_name

Renomeia a coluna especificada com um novo nome que atualmente não é usado para nenhuma outra coluna na tabela externa.

DROP COLUMN [ IF EXISTS ] col_name

Remove a coluna especificada da tabela externa.

Se não tiver certeza se a coluna já existe, você poderá especificar IF EXISTS ao descartar a coluna. Se a coluna não existir, DROP COLUMN não terá efeito e não resultará em erro.

Ações de restrição (constraintAction)¶

ADD CONSTRAINT

Adiciona uma restrição de integridade fora de linha a uma ou mais colunas da tabela. Para adicionar uma restrição em linha (para uma coluna), consulte Ações de coluna (neste tópico).

RENAME CONSTRAINT constraint_name TO new_constraint_name

Renomeia a restrição especificada.

ALTER | MODIFY CONSTRAINT ...

Altera as propriedades da restrição especificada.

DROP CONSTRAINT constraint_name | PRIMARY KEY | UNIQUE | FOREIGN KEY ( col_name [ , ... ] ) [ CASCADE | RESTRICT ]

Descarta a restrição especificada para a coluna ou o conjunto de colunas especificado.

Para sintaxes detalhadas e exemplos de adição ou alteração de restrições, consulte CREATE | ALTER TABLE … CONSTRAINT.

Política de governança de dados e ações de tag (dataGovnPolicyTagAction)¶

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

Especifica o nome da tag e o valor da cadeia de caracteres dela.

O valor de tag é sempre uma cadeia de caracteres, e o número máximo de caracteres do valor da tag é 256.

Para obter informações sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.

policy_name

Identificador da política; deve ser único para seu esquema.

As cláusulas a seguir se aplicam a todos os tipos de tabelas que suportam políticas de acesso a linhas, como, entre outras, tabelas, exibições e tabelas de eventos. Para simplificar, as cláusulas referem-se apenas a “tabela”.

ADD ROW ACCESS POLICY policy_name ON (col_name [ , ... ])

Adiciona um política de acesso a linhas à tabela.

Pelo menos um nome de coluna deve ser especificado. Colunas adicionais podem ser especificadas com uma vírgula que separa cada nome de coluna. Use esta expressão para adicionar uma política de acesso a linhas tanto a uma tabela de eventos como a uma tabela externa.

DROP ROW ACCESS POLICY policy_name

Descarta uma política de acesso a linhas da tabela.

Use esta cláusula para descartar a política da tabela.

DROP ROW ACCESS POLICY policy_name, ADD ROW ACCESS POLICY policy_name ON ( col_name [ , ... ] )

Descarta a política de acesso a linhas definida na tabela e adiciona uma política de acesso a linhas à mesma tabela em uma única instrução SQL.

DROP ALL ROW ACCESS POLICIES

Descarta todas as associações de política de acesso a linhas de uma tabela.

Esta expressão é útil quando uma política de acesso a linhas é descartada de um esquema antes de descartar a política de uma tabela de eventos. Use esta expressão para descartar as associações de política de acesso a linhas da tabela.

SET AGGREGATION POLICY policy_name

[ ENTITY KEY (col_name [ , ... ]) ] [ FORCE ]

Atribui uma política de agregação à tabela.

Use o parâmetro opcional ENTITY KEY para definir quais colunas identificam exclusivamente uma entidade dentro da tabela. Para obter mais informações, consulte Implementação de privacidade ao nível de entidade com políticas de agregação.

Use o parâmetro opcional FORCE para substituir atomicamente uma política de agregação existente pela nova política de agregação.

UNSET AGGREGATION POLICY

Desanexa uma política de agregação da tabela.

{ ALTER | MODIFY } [ COLUMN ] ...

USING ( col_name , cond_col_1 ... )

Especifica os argumentos para passar para a expressão SQL da política de mascaramento condicional.

A primeira coluna da lista especifica a coluna das condições da política para mascarar ou tokenizar os dados e deve corresponder à coluna para a qual a política de mascaramento é definida.

As colunas adicionais especificam as colunas a serem avaliadas para determinar se os dados em cada linha do resultado da consulta devem ser mascarados ou tokenizados quando uma consulta é feita na primeira coluna.

Se a cláusula USING for omitida, o Snowflake tratará a política de mascaramento condicional como uma política de mascaramento normal.

FORCE

Substitui uma política de mascaramento ou projeção que está atualmente definida em uma coluna por uma política diferente em uma única instrução.

Observe que a utilização da palavra-chave FORCE com uma política de mascaramento exige o tipo de dados da política na instrução ALTER TABLE (isto é, STRING) para corresponder ao tipo de dados da política de mascaramento atualmente definida na coluna (isto é, STRING).

Se uma política de mascaramento não estiver definida atualmente na coluna, a especificação dessa palavra-chave não tem efeito.

Para obter mais detalhes, consulte: Substituição de uma política de mascaramento em uma coluna ou Substituir uma política de projeção.

Ações de otimização de pesquisa (searchOptimizationAction)¶

ADD SEARCH OPTIMIZATION

Adiciona uma otimização de pesquisa para toda a tabela ou, se você especificar a cláusula opcional ON, para colunas específicas.

Nota:

• A otimização de pesquisa pode ser de cara manutenção, especialmente se os dados na tabela mudam com frequência. Para obter mais informações, consulte Estimativa e gerenciamento de custos de otimização de pesquisa.

• Se você tentar adicionar otimização de pesquisa em uma exibição materializada, o Snowflake retornará uma mensagem de erro.

ON search_method_with_target [, search_method_with_target ... ]

Especifica que você deseja configurar a otimização de pesquisa para colunas ou campos VARIANT específicos (e não para toda a tabela).

Para search_method_with_target, use uma expressão com a seguinte sintaxe:

<search_method>( <target> [ , <target> , ... ] [ , ANALYZER => '<analyzer_name>' ] )

Copy

Onde:

• search_method especifica um dos seguintes métodos que otimiza as consultas para um determinado tipo de predicado:

  Método de pesquisa	Descrição
  FULL_TEXT	Predicados que usam os tipos VARCHAR (texto), VARIANT, ARRAY e OBJECT.
  EQUALITY	Igualdade e predicados IN.
  SUBSTRING	Predicados que correspondem a substrings e expressões regulares (por exemplo, [ NOT ] LIKE, [ NOT ] ILIKE, [ NOT ] RLIKE, REGEXP_LIKE etc.)
  GEO	Predicados que usam tipos GEOGRAPHY.

• target especifica a coluna, campo VARIANT ou um asterisco (*).

  Dependendo do valor de search_method, você pode especificar uma coluna ou campo VARIANT de um dos seguintes tipos:

  Método de pesquisa	Alvos suportados
  FULL_TEXT	Colunas de tipos de dados VARCHAR (texto), VARIANT, ARRAY e OBJECT, incluindo caminhos para campos em VARIANTs.
  EQUALITY	Colunas de tipos de dados numéricos, cadeias de caracteres, binários e VARIANT, incluindo caminhos para campos em VARIANTs.
  SUBSTRING	Colunas de tipos de dados de cadeia de caracteres ou VARIANT, incluindo caminhos para campos em VARIANTs. Especifique caminhos para campos conforme descrito acima em EQUALITY; pesquisas em campos aninhados são melhoradas da mesma maneira.
  GEO	Limitações do tipo de dados GEOGRAPHY

  Para especificar um campo VARIANT, use a notação de ponto ou colchete (por exemplo, my_column:my_field_name.my_nested_field_name ou my_column['my_field_name']['my_nested_field_name']). Também é possível usar um caminho delimitado por dois pontos para o campo (por exemplo, my_column:my_field_name:my_nested_field_name).

  Quando você especifica um campo VARIANT, a configuração se aplica a todos os campos aninhados sob esse campo. Por exemplo, se você especificar ON EQUALITY(src:a.b):

  • Esta configuração pode melhorar consultas on src:a.b e em quaisquer campos aninhados (por exemplo, src:a.b.c, src:a.b.c.d etc.).

  • Esta configuração não afeta consultas que não usam o prefixo src:a.b (por exemplo, src:a, src:z etc.).

  Para especificar todas as colunas aplicáveis na tabela como alvos, use um asterisco (*).

  Note que você não pode especificar ao mesmo tempo um asterisco e nomes de colunas específicos para um determinado método de busca. Entretanto, você pode especificar um asterisco em diferentes métodos de busca.

  Por exemplo, você pode especificar as seguintes expressões:

  -- Allowed
  ON SUBSTRING(*)
  ON EQUALITY(*), SUBSTRING(*), GEO(*)
  

  Copy

  Você não pode especificar as seguintes expressões:

  -- Not allowed
  ON EQUALITY(*, c1)
  ON EQUALITY(c1, *)
  ON EQUALITY(v1:path, *)
  ON EQUALITY(c1), EQUALITY(*)
  

  Copy

• ANALYZER => 'analyzer_name' especifica o nome do analisador de texto, se search_method for FULL_TEXT.

  Quando o método de pesquisa FULL_TEXT é usado e as consultas são executadas com a função SEARCH ou SEARCH_IP, o analisador divide os termos de pesquisa (e o texto da coluna que está sendo pesquisada) em tokens. Uma linha encontra correspondência se algum dos tokens extraídos da cadeia de caracteres de pesquisa corresponder a um token extraído de qualquer uma das colunas ou campos que estão sendo pesquisados. O analisador não é relevante quando o método de pesquisa FULL_TEXT não é usado ou para consultas que não usam a função SEARCH ou SEARCH_IP.

  O analisador tokeniza uma cadeia de caracteres dividindo-a onde encontra certos delimitadores. Esses delimitadores não são incluídos nos tokens resultantes e os tokens vazios não são extraídos.

  Este parâmetro aceita um dos seguintes valores:

  • DEFAULT_ANALYZER: Divide o texto em tokens com base nos seguintes delimitadores:

    Caractere	Código Unicode	Descrição
    	U+0020	Espaço
    [	U+005B	Colchete esquerdo
    ]	U+005D	Colchete direito
    ;	U+003B	Ponto e vírgula
    <	U+003C	Sinal de menor que
    >	U+003E	Sinal de maior que
    (	U+0028	Parêntese esquerdo
    )	U+0029	Parêntese direito
    {	U+007B	Chave esquerda
    }	U+007D	Chave direita
    |	U+007C	Barra vertical
    !	U+0021	Ponto de exclamação
    ,	U+002C	Vírgula
    '	U+0027	Apóstrofo
    "	U+0022	Aspa
    *	U+002A	Asterisco
    &	U+0026	E comercial
    ?	U+003F	Ponto de interrogação
    +	U+002B	Sinal de mais
    /	U+002F	Barra
    :	U+003A	Dois pontos
    =	U+003D	Sinal de igual
    @	U+0040	No sinal
    .	U+002E	Ponto final
    -	U+002D	Hífen
    $	U+0024	Símbolo de dólar
    %	U+0025	Sinal de porcentagem
    \	U+005C	Barra invertida
    _	U+005F	Sublinhado (traço subscrito)
    \n	U+000A	Nova linha (alimentação de linha)
    \r	U+000D	Retorno de carro
    \t	U+0009	Guia horizontal

  • UNICODE_ANALYZER: Tokeniza com base em regras de segmentação Unicode que tratam espaços e certos caracteres de pontuação como delimitadores. Essas regras internas são projetadas para pesquisas em linguagem natural (em muitos idiomas diferentes). Por exemplo, o analisador padrão trata pontos em endereços IP e apóstrofos em contrações como delimitadores, mas o analisador Unicode não. Consulte Como usar um analisador para ajustar o comportamento da pesquisa.

    Para obter mais informações sobre o algoritmo de segmentação de texto Unicode, consulte https://unicode.org/reports/tr29/.

  • NO_OP_ANALYZER: Não tokeniza nem os dados nem a cadeia de caracteres de consulta. Um termo de pesquisa deve corresponder exatamente ao texto completo em uma coluna ou campo, incluindo diferenciação de maiúsculas e minúsculas; caso contrário, a função SEARCH retornará FALSE. Mesmo que a cadeia de caracteres de consulta pareça conter vários tokens (por exemplo, 'sky blue'), a coluna ou o campo deve ser exatamente igual à cadeia de caracteres de consulta inteira. Neste caso, apenas 'sky blue' é uma correspondência; 'sky' e 'blue' não são correspondências.

  • ENTITY_ANALYZER: Tokeniza os dados para pesquisas de endereço IP.

    Este analisador é usado apenas para consultas executadas com a função SEARCH_IP.

Para especificar mais de um método de busca em um alvo, use uma vírgula para separar cada método seguinte do alvo:

ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1), EQUALITY(c2, c3);

Copy

Se você executar o comando ALTER TABLE … ADD SEARCH OPTIMIZATION ON … várias vezes na mesma tabela, cada comando seguinte será adicionado à configuração existente para a tabela. Por exemplo, suponha que você execute os seguintes comandos:

ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2);
ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c3, c4);

Copy

Isso acrescenta os predicados de igualdade para as colunas c1, c2, c3 e c4 à configuração da tabela. Isso é equivalente a executar o comando:

ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2, c3, c4);

Copy

Para exemplos, consulte Habilitação da otimização de pesquisa para colunas específicas.

DROP SEARCH OPTIMIZATION

Remove a otimização de pesquisa para toda a tabela ou, se você especificar a cláusula opcional ON, de colunas específicas.

Nota:

• Se uma tabela tiver a propriedade de otimização de pesquisa, descartar a tabela e cancelar o descarte preservará a propriedade de otimização de pesquisa.

• Remover a propriedade de otimização de pesquisa de uma tabela e voltar a adicioná-la incorre no mesmo custo que adicioná-la pela primeira vez.

ON search_method_with_target | column_name | expression_id [ , ... ]

Especifica que você deseja remover a configuração de otimização de pesquisa para colunas ou campos VARIANT específicos (em vez de remover a otimização de pesquisa para toda a tabela).

Para identificar a configuração da coluna a ser removida, especifique uma das seguintes opções:

• Para search_method_with_target, especifique um método para otimizar consultas para um ou mais alvos específicos, que podem ser colunas ou campos VARIANT. Use a sintaxe descrita anteriormente.

• Para column_name, especifique o nome da coluna configurada para otimização de pesquisa. Especificar o nome da coluna remove todas as expressões para a coluna, incluindo expressões que utilizam campos VARIANT na coluna.

• Para expression_id, especifique a ID para uma expressão listada na saída do comando DESCRIBE SEARCH OPTIMIZATION.

Para especificar mais de um deles, use uma vírgula entre os itens.

Você pode especificar qualquer combinação de métodos de pesquisa com alvos, nomes de colunas e IDs de expressão.

Para exemplos, consulte Descarte da otimização de pesquisa para colunas específicas.

Notas de uso: geral¶

• As mudanças em uma tabela não são automaticamente propagadas para as exibições criadas sobre essa tabela. Por exemplo, se você descartar uma coluna em uma tabela, e uma exibição for definida para incluir essa coluna, a exibição torna-se inválida; a exibição não é ajustada para remover a coluna.

• O descarte de uma coluna não libera o espaço de armazenamento da coluna de imediato.

  • O espaço em cada micropartição não é recuperado até que essa micropartição seja regravada. Operações de gravação (inserir, atualizar, excluir etc.) em 1 ou mais linhas nessa micropartição faz com que a micropartição seja regravada. Se quiser forçar a recuperação do espaço, você pode seguir estas etapas:

    1. Use uma instrução CREATE TABLE AS SELECT (CTAS) para criar uma nova tabela que contenha apenas as colunas da tabela antiga que você deseja manter.

    2. Defina o parâmetro DATA_RETENTION_TIME_IN_DAYS como 0 para a tabela antiga (opcional).

    3. Descarte a tabela antiga.

  • Se a tabela for protegida pelo recurso Time Travel, o espaço utilizado pelo armazenamento do Time Travel só será recuperado quando o período de retenção do Time Travel expirar.

• Se uma nova coluna com um valor padrão for adicionada a uma tabela com linhas existentes, todas as linhas existentes serão preenchidas com o valor padrão.

• Atualmente, não é possível adicionar uma nova coluna com um valor padrão que contenha uma função. O seguinte erro ocorre:

  Invalid column default expression (expr)

• Para alterar uma tabela, você deve estar usando uma função que tenha privilégio de propriedade para a tabela.

• Para adicionar clustering a uma tabela, você também deve ter privilégios USAGE ou OWNERSHIP para o esquema e o banco de dados que contém a tabela.

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

    • Aplicação de uma política de mascaramento condicional em uma coluna

    • Substituição de uma política de mascaramento em uma coluna

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

• Para políticas de acesso a linhas:

  • O Snowflake oferece suporte à adição e ao descarte de políticas de acesso a linhas em uma única instrução SQL.

    Por exemplo, para substituir uma política de acesso a linhas que já esteja definida em uma tabela por uma política diferente, primeiro descarte a política de acesso a linhas e depois adicione a nova política.

  • Para determinado recurso (ou seja, tabela ou exibição), para ADD ou DROP uma política de acesso a linhas, você deve ter o privilégio APPLY ROW ACCESS POLICY no esquema, ou o privilégio OWNERSHIP no recurso e o privilégio APPLY no recurso da política de acesso a linhas.

  • Uma tabela ou exibição só pode ser protegida por uma política de acesso a linhas de cada vez. A adição de uma política falhará se o corpo da política se referir a uma coluna de exibição ou tabela protegida por uma política de acesso a linhas ou à coluna protegida por uma política de mascaramento.

    Da mesma forma, a adição de uma política de mascaramento a uma coluna da tabela falhará se o corpo da política de mascaramento se referir a uma tabela protegida por uma política de acesso a linhas ou outra política de mascaramento.

  • As políticas de acesso a linhas não podem ser aplicadas a exibições do sistema ou funções de tabela.

  • Semelhante a outras operações DROP <objeto>, o Snowflake retornará um erro se tentar descartar uma política de acesso a linhas de um recurso que não tenha uma política de acesso a linhas adicionada a ele.

  • Se um objeto tiver uma política de acesso a linhas e uma ou mais políticas de mascaramento, a política de acesso a linhas será avaliada primeiro.

• Se você criar uma chave estrangeira, as colunas na cláusula REFERENCES deverão ser listadas na mesma ordem em que foram listadas para a chave primária. Por exemplo:

  CREATE TABLE parent ... CONSTRAINT primary_key_1 PRIMARY KEY (c_1, c_2) ...
  CREATE TABLE child  ... CONSTRAINT foreign_key_1 FOREIGN KEY (...) REFERENCES parent (c_1, c_2) ...
  

  Copy

  Em ambos os casos, a ordem das colunas é c_1, c_2. Se a ordem das colunas na chave estrangeira fosse diferente (por exemplo, c_2, c_1), a tentativa de criar a chave estrangeira teria falhado.

• Em relação aos metadados:

  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.

• ALTER TABLE … CHANGE_TRACKING = TRUE

  • Quando uma tabela é alterada para permitir o rastreamento de alterações, a tabela é bloqueada durante a operação. Os bloqueios podem causar latência com algumas operações associadas DDL/DML. Para obter mais informações, consulte Bloqueio de recursos.

• Índices em tabelas híbridas:

  • Quando você usa o comando ALTER TABLE para adicionar ou descartar uma restrição exclusiva ou de chave estrangeira em uma tabela híbrida, o índice correspondente também será criado ou descartado. Para obter mais informações sobre índices em uma tabela híbrida, consulte CREATE INDEX.

  • As restrições de chave estrangeira são suportadas apenas em tabelas híbridas armazenadas no mesmo banco de dados. A capacidade de mover uma tabela híbrida de um banco de dados para outro não é suportada. As restrições de chave primária, exclusiva e de chave estrangeira definidas em tabelas híbridas têm seu campo RELY marcado como TRUE.

  • Uma coluna usada por um índice não pode ser descartada antes que o índice correspondente seja descartado.

Notas de uso: funções de métricas de dados¶

Adicione uma DMF a uma tabela:

Antes de adicionar uma função de métrica de dados a uma tabela, você deve:

• Definir o agendamento para a execução da função de métrica de dados. Para obter mais detalhes, consulte DATA_METRIC_SCHEDULE.

• Configure a tabela de eventos para armazenar os resultados da chamada da função de métrica de dados. Para obter mais detalhes, consulte Visualize os resultados da DMF:.

• Certifique-se de que a exibição da tabela não seja concedida a um compartilhamento, pois você não pode definir uma função de métrica de dados em uma tabela ou exibição compartilhada.

Adicionalmente:

• É possível adicionar uma função de métricas de dados a uma tabela, tabela externa, exibição ou exibição materializada. Não é possível definir uma função de métricas de dados em nenhum outro tipo de tabela, como uma tabela dinâmica.

• Quando você especifica uma coluna, o Snowflake usa a posição ordinal. Se você renomear uma coluna depois de adicionar uma função de métrica de dados à tabela ou exibição, a associação da função de métrica de dados à coluna permanecerá válida.

• Somente uma função de métrica de dados desse tipo pode ser adicionada a uma coluna. Por exemplo, uma função da métrica de dados NULL_COUNT não pode ser adicionada a uma única coluna duas vezes.

• Se você remover uma coluna depois de adicionar uma função de métrica de dados que faz referência à coluna, o Snowflake não poderá avaliar a função de métrica de dados.

• Não há suporte para fazer referência a uma coluna virtual.

Descarte uma DMF de uma tabela:

• Remova a função de métrica de dados da tabela antes de usar o comando DROP FUNCTION para remover a função de métrica de dados do sistema.

• Você pode usar a função DATA_METRIC_FUNCTION_REFERENCES para identificar a tabela e visualizar objetos que têm uma função de métrica de dados definida neles.

Agendamento de uma DMF

Leva dez minutos para que o cronograma entre em vigor depois que ele é definido.

Da mesma forma, leva dez minutos uma vez que a DMF não está definida para que as alterações de agendamento entrem em vigor. Para obter mais informações, consulte Como agendar suas DMFs para serem executadas.

Exemplos¶

As seções a seguir fornecem exemplos de uso do comando ALTER COLUMN:

• Renomeação de uma tabela

• Troca de tabelas

• Adição de colunas

• Como renomear colunas

• Descarte de colunas

• Adição, renomeação e descarte de colunas em uma tabela externa

• Alteração da ordem das chaves de clustering

• Adição e descarte das políticas de acesso a linhas

CREATE OR REPLACE TABLE t1(a1 number);

SHOW TABLES LIKE 't1';

+-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------+
| created_on                    | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes | owner  | retention_time | change_tracking | is_external | enable_schema_evolution | owner_role_type | is_event | budget |
|-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------|
| 2023-10-19 10:37:04.858 -0700 | T1   | TESTDB        | MY_SCHEMA   | TABLE |         |            |    0 |     0 | PUBLIC | 1              | OFF             | N           | N                       | ROLE            | N        | NULL   |
+-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------+

ALTER TABLE t1 RENAME TO tt1;

SHOW TABLES LIKE 'tt1';

+-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------+
| created_on                    | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes | owner  | retention_time | change_tracking | is_external | enable_schema_evolution | owner_role_type | is_event | budget |
|-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------|
| 2023-10-19 10:37:04.858 -0700 | TT1  | TESTDB        | MY_SCHEMA   | TABLE |         |            |    0 |     0 | PUBLIC | 1              | OFF             | N           | N                       | ROLE            | N        | NULL   |
+-------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+-----------------+-------------+-------------------------+-----------------+----------+--------+

CREATE OR REPLACE TABLE t1(a1 NUMBER, a2 VARCHAR, a3 DATE);
CREATE OR REPLACE TABLE t2(b1 VARCHAR);

DESC TABLE t1;

+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0)      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | VARCHAR(16777216) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | DATE              | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

DESC TABLE t2;

+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | VARCHAR(16777216) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

ALTER TABLE t1 SWAP WITH t2;

DESC TABLE t1;

+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | VARCHAR(16777216) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

DESC TABLE t2;

+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0)      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | VARCHAR(16777216) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | DATE              | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

CREATE OR REPLACE TABLE t1(a1 NUMBER);

DESC TABLE t1;

+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type         | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

ALTER TABLE t1 ADD COLUMN a2 NUMBER;

ALTER TABLE t1 ADD COLUMN a3 NUMBER NOT NULL;

ALTER TABLE t1 ADD COLUMN a4 NUMBER DEFAULT 0 NOT NULL;

ALTER TABLE t1 ADD COLUMN a5 VARCHAR COLLATE 'en_US';

DESC TABLE t1;

+------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type                              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0)                      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | NUMBER(38,0)                      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0)                      | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0)                      | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A5   | VARCHAR(16777216) COLLATE 'en_us' | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

ALTER TABLE t1 ADD COLUMN IF NOT EXISTS a2 NUMBER;

DESC TABLE t1;

+------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type                              | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| A1   | NUMBER(38,0)                      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | NUMBER(38,0)                      | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0)                      | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0)                      | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A5   | VARCHAR(16777216) COLLATE 'en_us' | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+-----------------------------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

ALTER TABLE t1 RENAME COLUMN a1 TO b1;

DESC TABLE t1;

+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type         | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A2   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0) | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0) | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

ALTER TABLE t1 DROP COLUMN a2;

DESC TABLE t1;

+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type         | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0) | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0) | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

ALTER TABLE t1 DROP COLUMN IF EXISTS a2;

+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+
| name | type         | kind   | null? | default | primary key | unique key | check | expression | comment | policy name |
|------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------|
| B1   | NUMBER(38,0) | COLUMN | Y     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A3   | NUMBER(38,0) | COLUMN | N     | NULL    | N           | N          | NULL  | NULL       | NULL    | NULL        |
| A4   | NUMBER(38,0) | COLUMN | N     | 0       | N           | N          | NULL  | NULL       | NULL    | NULL        |
+------+--------------+--------+-------+---------+-------------+------------+-------+------------+---------+-------------+

CREATE EXTERNAL TABLE exttable1
  LOCATION=@mystage/logs/
  AUTO_REFRESH = true
  FILE_FORMAT = (TYPE = PARQUET)
  ;

DESC EXTERNAL TABLE exttable1;

+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+
| name      | type              | kind      | null? | default | primary key | unique key | check | expression                                               | comment               |
|-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------|
| VALUE     | VARIANT           | COLUMN    | Y     | NULL    | N           | N          | NULL  | NULL                                                     | The value of this row |
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+

ALTER TABLE exttable1 ADD COLUMN a1 VARCHAR AS (value:a1::VARCHAR);

DESC EXTERNAL TABLE exttable1;

+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+
| name      | type              | kind      | null? | default | primary key | unique key | check | expression                                               | comment               |
|-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------|
| VALUE     | VARIANT           | COLUMN    | Y     | NULL    | N           | N          | NULL  | NULL                                                     | The value of this row |
| A1        | VARCHAR(16777216) | VIRTUAL   | Y     | NULL    | N           | N          | NULL  | TO_CHAR(GET(VALUE, 'a1'))                                | NULL                  |
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+

ALTER TABLE exttable1 RENAME COLUMN a1 TO b1;

DESC EXTERNAL TABLE exttable1;

+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+
| name      | type              | kind      | null? | default | primary key | unique key | check | expression                                               | comment               |
|-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------|
| VALUE     | VARIANT           | COLUMN    | Y     | NULL    | N           | N          | NULL  | NULL                                                     | The value of this row |
| B1        | VARCHAR(16777216) | VIRTUAL   | Y     | NULL    | N           | N          | NULL  | TO_CHAR(GET(VALUE, 'a1'))                                | NULL                  |
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+

ALTER TABLE exttable1 DROP COLUMN b1;

DESC EXTERNAL TABLE exttable1;

+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+
| name      | type              | kind      | null? | default | primary key | unique key | check | expression                                               | comment               |
|-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------|
| VALUE     | VARIANT           | COLUMN    | Y     | NULL    | N           | N          | NULL  | NULL                                                     | The value of this row |
+-----------+-------------------+-----------+-------+---------+-------------+------------+-------+----------------------------------------------------------+-----------------------+

CREATE OR REPLACE TABLE T1 (id NUMBER, date TIMESTAMP_NTZ, name STRING) CLUSTER BY (id, date);

SHOW TABLES LIKE 'T1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes |    owner     | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
 Tue, 21 Jun 2016 15:42:12 -0700 | T1   | TESTDB        | TESTSCHEMA  | TABLE |         | (ID,DATE)  | 0    | 0     | ACCOUNTADMIN | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+

ALTER TABLE t1 CLUSTER BY (date, id);

SHOW TABLES LIKE 'T1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes |    owner     | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
 Tue, 21 Jun 2016 15:42:12 -0700 | T1   | TESTDB        | TESTSCHEMA  | TABLE |         | (DATE,ID)  | 0    | 0     | ACCOUNTADMIN | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+