ALTER TABLE (tabelas de eventos)¶

Sintaxe¶

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

ALTER TABLE [ IF EXISTS ] <name> clusteringAction

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  } ]
  [ COMMENT = '<string_literal>' ]

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

ALTER TABLE [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER TABLE [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

ALTER TABLE [ IF EXISTS ] <name>
  ADD ROW ACCESS POLICY <policy_name> ON (<col_name> [ , ... ])

ALTER TABLE [ IF EXISTS ] <name>
  DROP ROW ACCESS POLICY <policy_name>

ALTER TABLE [ IF EXISTS ] <name>
  DROP ROW ACCESS POLICY <policy_name>,
  ADD ROW ACCESS POLICY <policy_name> ON (<col_name> [ , ... ])

ALTER TABLE [ IF EXISTS ] <name> DROP ALL ROW ACCESS POLICIES

Onde:

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }

Copy

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 de eventos a ser alterada. Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

RENAME TO new_table_name

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

Para obter mais detalhes sobre os identificadores de tabela de eventos, 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.

SET ...

Especifica uma ou mais propriedades/parâmetros a serem definidos para a tabela de eventos (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 de eventos do Time Travel. Para obter mais detalhes, 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 de eventos permanentes

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

Nota

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

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 de eventos para evitar que os fluxos na tabela de eventos 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 de eventos.

• TRUE habilita o rastreamento de alterações na tabela de eventos. Essa opção adiciona um par de colunas ocultas à tabela de eventos 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 de eventos.

• FALSE desabilita o rastreamento de alterações na tabela de eventos. O par de colunas ocultas é descartado da tabela de eventos.

COMMENT = 'string_literal'

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

UNSET ...

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

• DATA_RETENTION_TIME_IN_DAYS

• MAX_DATA_EXTENSION_TIME_IN_DAYS

• CHANGE_TRACKING

• COMMENT

policy_name

Identificador da política de mascaramento ou da política de acesso a linhas; deve ser único para seu esquema.

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

Adiciona uma política de acesso a linhas a uma tabela de eventos.

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 de uma tabela de eventos.

Use esta expressão para descartar uma política tanto de uma tabela de eventos como de uma tabela externa de eventos.

DROP ALL ROW ACCESS POLICIES

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

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 associações de política de acesso a linhas tanto de uma tabela de eventos como de uma tabela externa.

Ações de clustering (clusteringAction)¶

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

Especifica (ou modifica) uma ou mais colunas de tabela de eventos ou expressões de coluna como a chave de clustering da tabela de eventos. 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 de eventos; elas normalmente são vantajosas para tabelas de eventos muito grandes (ou seja, com vários terabytes).

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

SUSPEND | RESUME RECLUSTER

Habilita ou desabilita Clustering automático para a tabela de eventos.

DROP CLUSTERING KEY

Descarta a chave de clustering para a tabela de eventos.

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

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

ADD SEARCH OPTIMIZATION

Adiciona uma otimização de pesquisa para toda a tabela de eventos 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 de eventos 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 de eventos).

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

<search_method>(<target> [, ...])

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
  EQUALITY	Igualdade e predicados IN.
  SUBSTRING	Predicados que correspondem a subcadeias de caracteres e expressões regulares (por exemplo, LIKE, ILIKE, 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
  EQUALITY	Colunas de tipos de dados numéricos, cadeias de caracteres, binários e VARIANT, incluindo caminhos para campos em VARIANTs. Para especificar um campo VARIANT, use um caminho delimitado por dois pontos para o campo (por exemplo, my_column:my_field_name:my_nested_field_name), ou use a notação de ponto ou colchetes (por exemplo, my_column:my_field_name.my_nested_field_name ou 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, suponha que você especifique ON EQUALITY(src:a.b): Essa configuração pode melhorar as consultas on src:a.b e em qualquer campo aninhado (por exemplo, src:a.b.c, src:a.b.c.d, etc.). Essa configuração não afeta consultas que não utilizam o prefixo src:a.b (por exemplo, src:a, src:z, etc.).
  SUBSTRING	Colunas de tipos de dados de cadeia de caracteres.
  GEO	Limitações do tipo de dados GEOGRAPHY

  Para especificar todas as colunas aplicáveis na tabela de eventos como destinos, 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

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 de eventos, cada comando seguinte será adicionado à configuração existente para a tabela de eventos. 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 de eventos. 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 de eventos ou, se você especificar a cláusula opcional ON, de colunas específicas.

Nota:

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

• Remover a propriedade de otimização de pesquisa de uma tabela de eventos 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 de eventos).

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¶

• As mudanças em uma tabela de eventos não são automaticamente propagadas para as exibições criadas sobre essa tabela de eventos.

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

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

• 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 da cláusula REFERENCES deverão ser listadas na mesma ordem em que as colunas 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 tivesse sido 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 de eventos é alterada para permitir o rastreamento de alterações, a tabela de eventos é 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.

Exemplos¶

Renomear a tabela de eventos t1 como a1:

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 |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
 Tue, 17 Mar 2015 16:52:33 -0700 | T1   | TESTDB        | MY_SCHEMA   | TABLE |         |            | 0    | 0     | PUBLIC | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+

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 |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
 Tue, 17 Mar 2015 16:52:33 -0700 | TT1  | TESTDB        | MY_SCHEMA   | TABLE |         |            | 0    | 0     | PUBLIC | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+

Copy

Alterar a ordem da chave de clustering para uma tabela de eventos:

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

-- Change the order of the clustering key
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              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+

Copy

O exemplo seguinte adiciona uma política de acesso a linhas a uma tabela de eventos enquanto especifica uma única coluna. Após definir a política, você pode verificar o esquema de informação.

ALTER TABLE t1
  ADD ROW ACCESS POLICY rap_t1 ON (empl_id);

Copy

O exemplo a seguir adiciona uma política de acesso a linhas ao mesmo tempo em que especifica duas colunas em uma única tabela de eventos.

ALTER TABLE t1
  ADD ROW ACCESS POLICY rap_test2 ON (cost, item);

Copy

O exemplo a seguir descarta uma política de acesso a linhas de uma tabela de eventos. Verifique se as políticas foram descartadas consultando o esquema de informação.

ALTER TABLE t1
  DROP ROW ACCESS POLICY rap_v1;

Copy

O exemplo a seguir mostra como combinar a adição e a eliminação de políticas de acesso a linhas em uma única instrução SQL para uma tabela. Verifique os resultados conferindo o esquema de informação.

alter table t1
  drop row access policy rap_t1_version_1,
  add row access policy rap_t1_version_2 on (empl_id);

Copy