CREATE <objeto> … CLONE

Cria uma cópia de um objeto existente no sistema. Este comando é usado principalmente para criar clones de zero cópia de bancos de dados, esquemas e tabelas; no entanto, ele também pode ser usado para criar rapidamente/fácilmente clones de outros objetos de esquema (ou seja, estágios externos, formatos de arquivo e sequências).

O comando é uma variação dos comandos CREATE <objeto> específicos do objeto com a adição da palavra-chave CLONE.

Nota

Para bancos de dados, esquemas e tabelas não temporárias, CLONE oferece suporte a uma cláusula adicional AT | BEFORE para clonagem usando Time Travel.

Sintaxe

Bancos de dados, esquemas, tabelas

CREATE [ OR REPLACE ] { DATABASE | SCHEMA | TABLE } [ IF NOT EXISTS ] <object_name>
  CLONE <source_object_name>
        [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ]
  ...
Copy

Outros objetos de esquema

CREATE [ OR REPLACE ] { STAGE | FILE FORMAT | SEQUENCE | STREAM | TASK } [ IF NOT EXISTS ] <object_name>
  CLONE <source_object_name>
  ...
Copy

Notas de uso geral

  • Um clone pode ser gravado e é independente de sua origem (ou seja, as mudanças feitas na origem ou no clone não são refletidas no outro objeto).

  • Os parâmetros que são explicitamente definidos em um banco de dados de origem, esquema ou tabela são mantidos em qualquer clone criado a partir do contêiner de origem ou de objetos filho.

  • Para criar um clone, sua função atual deve ter o(s) seguinte(s) privilégio(s) no objeto de origem:

    Tabelas

    SELECT

    Canais, fluxos, tarefas

    OWNERSHIP

    Outros objetos

    USAGE

    Além disso, para clonar um esquema ou um objeto dentro de um esquema, sua função atual deve ter privilégios no(s) objeto(s) do contêiner, tanto para a origem quanto para o clone.

  • Para bancos de dados e esquemas, a clonagem é recursiva:

    • A clonagem de um banco de dados clona todos os esquemas e outros objetos do banco.

    • A clonagem de um esquema clona todos os objetos contidos no esquema.

    Entretanto, os seguintes tipos de objetos não são clonados:

    • Tabelas externas

    • Estágios internos (Snowflake)

  • Em bancos de dados, esquemas e tabelas, um clone não contribui para o armazenamento geral de dados do objeto até que sejam realizadas operações no clone que modifiquem dados existentes ou adicionem novos dados, como por exemplo:

    • Adicionar, excluir ou modificar linhas em uma tabela clonada.

    • Criação de uma nova tabela preenchida em um esquema clonado.

  • A clonagem de uma tabela replica a estrutura, dados e algumas outras propriedades (por exemplo, STAGE FILE FORMAT) da tabela de origem.

    No entanto:

    • Uma tabela clonada não inclui o histórico de carregamento da tabela de origem. Uma consequência disto é que os arquivos de dados que foram carregados em uma tabela de origem podem ser carregados novamente em seus clones.

    • Embora uma tabela clonada replique as chaves de clustering da tabela de origem, a nova tabela começa com Clustering automático suspenso – mesmo que o Clustering automático não esteja suspenso para a tabela de origem.

  • O CREATE TABLE … CLONE inclui as palavras-chave COPY GRANTS, que afetam um novo clone de tabela como se segue:

    • Se as palavras-chave COPY GRANTS forem usadas, então o novo objeto herda qualquer privilégio de acesso explícito concedido na tabela original, mas não herda qualquer futura concessão definida para o tipo de objeto no esquema.

    • Se as palavras-chave COPY GRANTS não são utilizadas, então o novo clone do objeto não herda nenhum privilégio de acesso explícito concedido na tabela original, mas herda qualquer concessão futura definida para o tipo de objeto no esquema (usando a sintaxe GRANT <privilégios> … ON FUTURE).

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

  • Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando o objeto é substituído, a exclusão do objeto antigo e a criação do novo objeto são processadas em uma única transação.

Regras adicionais que se aplicam à clonagem de objetos

Metadados

Um clone de objeto herda o nome e a estrutura do objeto de origem atual no momento em que a instrução CREATE <objeto> CLONE é executada ou em um momento/ponto especificado no passado usando Time Travel. Um clone de objeto herda quaisquer outros metadados, tais como comentários ou chaves de clustering de tabelas, que são atuais no objeto de origem no momento em que a instrução é executada, independentemente do uso do Time Travel.

Objetos filho

Um banco de dados ou clone de esquema inclui todos os objetos filho ativos no momento em que a instrução é executada ou no momento/ponto especificado no passado. Um instantâneo dos dados da tabela representa o estado dos dados de origem quando a instrução é executada ou no momento/ponto especificado no passado. Os objetos filho herdam o nome e a estrutura dos objetos filho de origem no momento em que a instrução é executada.

Não clonado

A clonagem de um banco de dados ou esquema não clona objetos dos seguintes tipos no banco de dados ou esquema:

  • Tabelas externas

  • Estágios internos (Snowflake)

Canais

Um clone de esquema ou banco de dados inclui apenas objetos de canal que fazem referência a estágios externos (Amazon S3, Google Cloud Storage ou Microsoft Azure); canais internos (Snowflake) não são clonados.

O estado padrão de um clone de canal é o seguinte:

  • Quando AUTO_INGEST = FALSE, um canal clonado é pausado por padrão.

  • Quando AUTO_INGEST = TRUE, um canal clonado é definido como o estado STOPPED_CLONED. Nesse estado, os canais não acumulam notificações de evento como resultado de arquivos preparados recentemente. Quando um canal é explicitamente retomado, ele só processa arquivos de dados acionados como resultado de novas notificações de eventos.

Um clone de canal em qualquer estado pode ser retomado executando uma instrução ALTER PIPE … RESUME.

Tags

A clonagem de um banco de dados ou esquema afeta as tags nesse banco de dados ou esquema, como segue:

  • Associações de tags no objeto de origem (por exemplo, tabela) são mantidas nos objetos clonados.

  • Para um banco de dados ou esquema:

    As tags armazenadas no banco de dados ou esquema também são clonadas.

    Quando um banco de dados ou esquema é clonado, as tags contidas no esquema ou banco de dados também são clonadas.

    Se existir uma tabela ou exibição no esquema de origem/banco de dados e houver referências a tags no mesmo esquema ou banco de dados, a tabela ou exibição clonada será mapeada para a tag clonada correspondente (no esquema/banco de dados de destino) em vez da tag no esquema ou banco de dados de origem.

Dados da tabela

Ao clonar um banco de dados, esquema ou tabela, um instantâneo dos dados em cada tabela é tirado e disponibilizado para o clone. O instantâneo representa o estado dos dados de origem no momento em que a instrução é executada ou no momento/ponto especificado no passado (usando Time Travel).

Referências de objetos

Objetos como exibições, fluxos e tarefas incluem referências a objetos em sua definição. Por exemplo, uma exibição contém uma consulta armazenada que inclui referências de tabela. Um fluxo aponta para uma tabela de origem. Uma tarefa chama um procedimento armazenado ou executa uma instrução SQL que faz referência a outros objetos. E assim por diante.

Quando um desses objetos é clonado, seja em um banco de dados ou esquema clonado ou como um objeto individual, para aqueles tipos de objetos que oferecem suporte à clonagem, o clone herda referências a outros objetos a partir da definição do objeto de origem. Por exemplo, um clone de uma exibição herda a consulta armazenada da exibição de origem, incluindo as referências da tabela na consulta.

Preste muita atenção se algum nome de objeto na definição de um objeto de origem é total ou parcialmente qualificado. Um nome totalmente qualificado inclui o banco de dados e os nomes dos esquemas. Qualquer clone do objeto de origem inclui estas partes em sua própria definição.

Por exemplo:

-- Create a schema to serve as the source for a cloned schema.
CREATE SCHEMA source;

-- Create a table.
CREATE TABLE mytable (col1 string, col2 string);

-- Create a view that references the table with a fully-qualified name.
CREATE VIEW myview AS SELECT col1 FROM source.mytable;

-- Retrieve the DDL for the source schema.
SELECT GET_DDL ('schema', 'source', true);

+--------------------------------------------------------------------------+
| GET_DDL ('SCHEMA', 'SOURCE', TRUE)                                       |
|--------------------------------------------------------------------------|
| create or replace schema MPETERS_DB.SOURCE;                              |
|                                                                          |
| create or replace TABLE MPETERS_DB.SOURCE.MYTABLE (                      |
|   COL1 VARCHAR(16777216),                                                                                                                                                     |
|   COL2 VARCHAR(16777216)                                                                                                                                                     |
| );                                                                       |
|                                                                          |
| CREATE VIEW MPETERS_DB.SOURCE.MYVIEW AS SELECT col1 FROM source.mytable; |
|                                                                          |
+--------------------------------------------------------------------------+

-- Clone the source schema.
CREATE SCHEMA source_clone CLONE source;

-- Retrieve the DDL for the clone of the source schema.
-- The clone of the view references the source table with the same fully-qualified name
-- as in the view in the source schema.
SELECT GET_DDL ('schema', 'source_clone', true);

+--------------------------------------------------------------------------------+
| GET_DDL ('SCHEMA', 'SOURCE_CLONE', TRUE)                                       |
|--------------------------------------------------------------------------------|
| create or replace schema MPETERS_DB.SOURCE_CLONE;                              |
|                                                                                |
| create or replace TABLE MPETERS_DB.SOURCE_CLONE.MYTABLE (                      |
|   COL1 VARCHAR(16777216),                                                                                                                                                   |
|   COL2 VARCHAR(16777216)                                                                                                                                                   |
| );                                                                             |
|                                                                                |
| CREATE VIEW MPETERS_DB.SOURCE_CLONE.MYVIEW AS SELECT col1 FROM source.mytable; |
|                                                                                |
+--------------------------------------------------------------------------------+
Copy

Se você pretende apontar uma exibição para tabelas com os mesmos nomes em outros bancos de dados ou esquemas, sugerimos criar uma nova exibição em vez de clonar uma exibição existente. Esta orientação também se refere a outros objetos que fazem referência a objetos em sua definição.

Nota

  • Certas limitações se aplicam às operações de clonagem. Por exemplo, instruções DDL que afetam o objeto de origem durante uma operação de clonagem podem alterar o resultado ou causar erros.

  • A clonagem não é instantânea, especialmente em grandes objetos (bancos de dados, esquemas, tabelas), e não bloqueia o objeto a ser clonado. Como tal, um clone não reflete nenhuma instrução DML aplicada aos dados da tabela, se aplicável, enquanto a operação de clonagem ainda estiver em andamento.

Para obter mais informações sobre este e outros casos de uso que possam afetar suas operações de clonagem, consulte Considerações sobre clonagem.

Notas sobre colonagem com Time Travel (somente bancos de dados, esquemas e tabelas)

  • A cláusula AT | BEFORE clona um banco de dados, esquema ou tabela a partir de uma hora especificada no passado ou com base em uma instrução SQL especificada:

    • A palavra-chave AT especifica que a solicitação inclui quaisquer alterações feitas por uma instrução ou transação com um carimbo de data/hora igual ao parâmetro especificado.

    • A palavra-chave BEFORE especifica que o pedido se refere a um ponto imediatamente anterior ao parâmetro especificado.

  • A clonagem usando STATEMENT é equivalente a usar TIMESTAMP com um valor igual ao tempo de execução registrado da instrução SQL (ou da transação que a envolve), conforme identificado pela ID da instrução especificada.

  • Um erro é devolvido se:

    • O objeto sendo clonado não existia no ponto no passado especificado na cláusula AT | BEFORE.

    • Os dados históricos necessários para clonar o objeto ou qualquer um de seus objetos secundários (por exemplo, tabelas em esquemas clonados ou banco de dados) foram purgados.

  • Se qualquer objeto filho em um banco de dados ou esquema clonado não existia no ponto no passado especificado na cláusula AT | BEFORE, o objeto filho não será clonado.

Para obter mais informações, consulte Compreensão e uso do Time Travel.

Exemplos

Clonar um banco de dados e todos os objetos dentro do banco de dados em seu estado atual:

CREATE DATABASE mytestdb_clone CLONE mytestdb;
Copy

Clonar um esquema e todos os objetos dentro do esquema em seu estado atual:

CREATE SCHEMA mytestschema_clone CLONE testschema;
Copy

Clonar uma tabela em seu estado atual:

CREATE TABLE orders_clone CLONE orders;
Copy

Clonar um esquema como ele existia antes da data e hora no carimbo de data/hora especificado:

CREATE SCHEMA mytestschema_clone_restore CLONE testschema BEFORE (TIMESTAMP => TO_TIMESTAMP(40*365*86400));
Copy

Clonar uma tabela como ela existia exatamente na data e na hora do carimbo de data/hora especificado:

CREATE TABLE orders_clone_restore CLONE orders AT (TIMESTAMP => TO_TIMESTAMP_TZ('04/05/2013 01:02:03', 'mm/dd/yyyy hh24:mi:ss'));
Copy

Clonar uma tabela como ela existia imediatamente antes da execução da instrução especificada (isto é, ID da consulta):

CREATE TABLE orders_clone_restore CLONE orders BEFORE (STATEMENT => '8e5d0ca9-005e-44e6-b858-a8f5b37c5726');
Copy