CREATE <objet> … CLONE¶

Cloner des objets en utilisant Time Travel¶

Pour les bases de données, les schémas et les tables (hors tables temporaires), CLONE prend en charge une clause AT | BEFORE supplémentaire pour le clonage en utilisant Time Travel.

Pour les bases de données et les schémas :

• CLONE prend en charge le paramètre IGNORE TABLES WITH INSUFFICIENT DATA RETENTION pour ignorer toutes les tables qui ont été purgées de Time Travel (par exemple, les tables transitoires avec une période de conservation des données d’un jour).

• CLONE prend en charge le paramètre IGNORE HYBRID TABLES pour ignorer les tables hybrides.

Syntaxe¶

CREATE [ OR REPLACE ] { DATABASE | SCHEMA } [ IF NOT EXISTS ] <object_name>
  CLONE <source_object_name>
    [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ]
    [ IGNORE TABLES WITH INSUFFICIENT DATA RETENTION ]
    [ IGNORE HYBRID TABLES ]
  ...

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

CREATE [ OR REPLACE ] DYNAMIC TABLE <name>
  CLONE <source_dynamic_table>
    [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ]
  [
    TARGET_LAG = { '<num> { seconds | minutes | hours | days }' | DOWNSTREAM }
    WAREHOUSE = <warehouse_name>
  ]

CREATE [ OR REPLACE ] EVENT TABLE <name>
  CLONE <source_event_table>
    [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ]

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <name>
  CLONE <source_iceberg_table>
    [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ]
    [ COPY GRANTS ]
    ...

CREATE [ OR REPLACE ] DATABASE ROLE [ IF NOT EXISTS ] <database_role_name>
  CLONE <source_database_role_name>

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

Paramètres de Time Travel¶

{ AT | BEFORE } ( { TIMESTAMP => timestamp | OFFSET => time_difference | STATEMENT => id } )

La clause AT | BEFORE accepte l’un des paramètres suivants :

TIMESTAMP => timestamp

Spécifie une date et une heure exactes à utiliser pour Time Travel. La valeur doit être explicitement convertie en type de données TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ ou TIMESTAMP_TZ.

Si aucune conversion explicite n’est spécifiée, l’horodatage dans la clause AT est traité comme un horodatage avec le fuseau horaire UTC (équivalent à TIMESTAMP_NTZ). Utiliser le type de données TIMESTAMP pour une conversion explicite peut également entraîner le traitement de la valeur comme une valeur TIMESTAMP_NTZ. Pour plus de détails, voir Types de données de date et heure.

OFFSET => time_difference

Spécifie la différence en secondes par rapport au temps actuel à utiliser pour Time Travel, sous la forme -N où N peut être un entier ou une expression arithmétique (par exemple, -120 correspond à 120 secondes, -30*60 correspond à 1800 secondes ou 30 minutes).

STATEMENT => id

Spécifie l’ID d’une requête à utiliser comme point de référence pour Time Travel. Ce paramètre prend en charge toute instruction de l’un des types suivants :

• DML (par ex. INSERT, UPDATE, DELETE)

• TCL (transaction BEGIN, COMMIT)

• SELECT

L’ID de requête doit faire référence à une requête qui a été exécutée au cours des 14 derniers jours. Si l’ID de requête fait référence à une requête datant de plus de 14 jours, l’erreur suivante est renvoyée :

Error: statement <query_id> not found

Pour contourner cette limitation, utilisez l’horodatage de la requête référencée.

IGNORE TABLES WITH INSUFFICIENT DATA RETENTION

Ignorez les tables qui n’ont plus de données historiques disponibles dans Time Travel à cloner. Si le moment dans le passé spécifié dans la clause AT | BEFORE dépasse la période de conservation des données pour toute table enfant dans une base de données ou un schéma, ignorez l’opération de clonage pour la table enfant. Pour plus d’informations, voir Objets enfants et durée de conservation des données.

IGNORE HYBRID TABLES

Ignorez les tables hybrides, qui ne seront pas clonées. Utilisez cette option pour cloner une base de données ou un schéma contenant des tables hybrides. La base de données ou le schéma cloné inclut d’autres objets mais ignore les tables hybrides.

Si vous n’utilisez pas cette option et que votre base de données ou schéma contient une ou plusieurs tables hybrides, la commande ignore silencieusement les tables hybrides. Cependant, le traitement des erreurs pour les bases de données et les schémas contenant des tables hybrides changera dans une prochaine version ; par conséquent, vous souhaiterez peut-être ajouter ce paramètre à vos commandes de manière préventive.

Exigences en matière de contrôle d’accès¶

Pour créer un clone, votre rôle actuel doit avoir les privilèges suivants sur l’objet source :

Bases de données:

USAGE sur la base de données.

Rôles de base de données:

OWNERSHIP sur le rôle de base de données et le privilège CREATE DATABASE ROLE sur la base de données cible.

Schémas:

Si vous spécifiez la clause WITH MANAGED ACCESS, les privilèges requis dépendent du fait que le schéma source est un schéma géré ou non géré. Pour plus de détails, voir les privilèges CREATE SCHEMA.

Tables:

SELECT

Alertes, canaux, flux, tâches:

OWNERSHIP

Autres objets:

USAGE

En outre, pour cloner un schéma ou un objet au sein d’un schéma, votre rôle actuel doit avoir les privilèges requis sur les objets du conteneur pour la source et le clone.

Notes générales sur l’utilisation¶

• Un clone est accessible en écriture et est indépendant de sa source. Les modifications apportées à la source ou au clone ne sont pas répercutées dans l’autre objet.

• Les paramètres qui sont explicitement définis sur une base de données, un schéma ou une table source sont conservés dans tous les clones créés à partir du conteneur source ou des objets enfants.

• Pour les rôles de base de données :

  • Un rôle de base de données est cloné lorsque vous exécutez la commande CREATE DATABASE … CLONE pour cloner une base de données. Toutefois, si vous clonez d’autres objets de base de données tels qu’un schéma ou une table, les rôles de base de données de la base de données ne sont pas clonés avec le schéma ou la table.

  • Si le rôle de base de données est déjà cloné dans la base de données cible, la commande échoue. Si cela se produit, supprimez le rôle de base de données de la base de données cible et réessayez la commande CLONE.

• Pour les bases de données et les schémas, le clonage est récursif :

  • Le clonage d’une base de données clone tous les schémas et autres objets dans la base de données.

  • Le clonage d’un schéma clone tous les objets contenus dans le schéma.

  Cependant, les types d’objets suivants ne sont pas clonés :

  • Tables externes

  • Zones de préparation internes (c.-à-d. Snowflake)

• Pour les bases de données, les schémas et les tables, un clone ne contribue pas au stockage global des données de l’objet jusqu’à ce que des opérations soient effectuées sur le clone qui modifient les données existantes ou ajoutent de nouvelles données, telles que :

  • Ajouter, supprimer ou modifier des lignes dans une table clonée.

  • Créer une nouvelle table remplie dans un schéma cloné.

• Le clonage d’une table reproduit la structure, les données et certaines autres propriétés (par exemple STAGE FILE FORMAT) de la table source.

  Cependant :

  • Une table clonée n’inclut pas l’historique de chargement de la table source. Une conséquence de ceci est que les fichiers de données qui ont été chargés dans une table source peuvent être chargés à nouveau dans ses clones.

  • Bien qu’une table clonée réplique les clés de clustering de la table source, la nouvelle table démarre avec le clustering automatique suspendu, même si le clustering automatique n’est pas suspendu pour la table source.

• Le paramètre COPY GRANTS affecte un nouveau clone de table de la façon suivante :

  • Si le paramètre COPY GRANTS est utilisé, alors le nouvel objet hérite des privilèges d’accès explicites accordés sur la table d’origine, mais n’hérite pas des autorisations futures définies pour le type d’objet dans le schéma.

  • Si le paramètre COPY GRANTS n’est pas utilisé, alors le nouveau clone d’objet n’hérite pas des privilèges d’accès explicites accordés sur la table d’origine, mais hérite des autorisations futures définies pour le type d’objet dans le schéma (en utilisant la syntaxe GRANT <privilèges> … ON FUTURE).

  Note

  Si l’instruction remplace une table existante du même nom, les autorisations sont copiées à partir de la table à remplacer. S’il n’existe aucune table de ce nom, les autorisations sont copiées à partir de la table source en cours de clonage.

• Pour Tables Apache Iceberg™, le clonage est actuellement pris en charge uniquement pour les tables gérées par Snowflake. Pour plus d’informations, voir Clonage et tables Apache Iceberg™.

• Concernant les métadonnées :

  Attention

  Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

• Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

Règles supplémentaires qui s’appliquent aux clonage d’objets¶

Métadonnées:

Un clone d’objet hérite de la structure et du nom de l’objet source actuel au moment de l’exécution de l’instruction CREATE <objet> CLONE ou à l’heure/au point spécifié dans le passé à l’aide de Time Travel. Un clone d’objet hérite de toutes les autres métadonnées, telles que les commentaires ou les clés de clustering de table, qui sont actuels dans l’objet source au moment de l’exécution de l’instruction, que l’on utilise ou non Time Travel.

Objets enfants:

Une base de données ou un schéma clone comprend tous les objets enfants actifs au moment de l’exécution de l’instruction ou à l’heure/au point spécifié dans le passé. Un instantané des données de la table représente l’état des données sources lorsque l’instruction est exécutée ou à l’heure/au point spécifié dans le passé. Les objets enfants héritent du nom et de la structure des objets enfants sources au moment de l’exécution de l’instruction.

Non cloné:

Le clonage d’une base de données ou d’un schéma ne clone pas d’objets des types suivants dans la base de données ou le schéma :

• Tables externes

• Zones de préparation internes (c.-à-d. Snowflake)

Canaux:

Une base de données ou un schéma clone incluent uniquement des objets de canal faisant référence à des zones de préparation externes (Amazon S3, Google Cloud Storage ou Microsoft Azure) ; les canaux internes (Snowflake) ne sont pas clonés.

L’état par défaut d’un clone de canal est le suivant :

• Lorsque AUTO_INGEST = FALSE, un canal cloné est suspendu par défaut.

• Lorsque AUTO_INGEST = TRUE, un canal cloné est défini sur l’état STOPPED_CLONED. Dans cet état, les canaux n’accumulent pas de notifications d’événements à la suite de nouveaux fichiers mis en zone de préparation. Lorsqu’un canal est explicitement repris, il ne traite que les fichiers de données déclenchés à la suite de nouvelles notifications d’événements.

Un canal clone dans l’un ou l’autre état peut être repris en exécutant une instruction ALTER PIPE … RESUME.

Balises:

Le clonage d’une base de données ou d’un schéma affecte les balises de cette base de données ou de ce schéma comme suit :

• Les associations de balises dans l’objet source (par ex. des tables) sont maintenues dans les objets clonés.

• Pour une base de données ou un schéma :

  Les balises stockées dans cette base de données ou ce schéma sont également clonées.

  Lorsqu’une base de données ou un schéma est cloné, les balises qui résident dans ce schéma ou cette base de données sont également clonées.

  Si une table ou une vue existe dans le schéma/la base de données source et a des références à des balises dans le même schéma ou la même base de données, la table ou la vue clonée est mappée sur la balise clonée correspondante (dans le schéma ou la base de données cible) au lieu de la balise dans le schéma ou la base de données source.

UDF Java:

Une UDF Java peut être clonée lorsque la base de données ou le schéma contenant l’UDF Java est cloné(e). Pour être clonée, l’UDF Java doit remplir certaines conditions. Pour plus d’informations, voir Limites du clonage.

Fonctions de métrique des données:

Le clonage n’entraîne pas d’affectations de DMF sur l’objet cible. Si vous clonez une base de données ou un schéma contenant des DMFs, les DMFs sont clonés dans la base de données ou le schéma cible.

Données de table:

Lors du clonage d’une base de données, d’un schéma ou d’une table, un instantané des données de chaque table est pris et mis à la disposition du clone. L’instantané représente l’état des données sources au moment de l’exécution de l’instruction ou à l’heure/au point spécifié dans le passé (à l’aide de la fonction Time Travel).

Références de l’objet:

Les objets tels que les vues, les flux et les tâches incluent des références d’objets dans leur définition. Par exemple :

• Une vue contient une requête stockée qui comprend des références de table.

• Un flux pointe vers une table source.

• Une tâche ou une alerte appelle une procédure stockée ou exécute une instruction SQL qui fait référence à d’autres objets.

Lorsqu’un de ces objets est cloné, soit dans une base de données ou un schéma cloné, soit en tant qu’objet individuel, pour les types d’objets qui prennent en charge le clonage, le clone hérite des références aux autres objets de la définition de l’objet source. Par exemple, un clone d’une vue hérite de la requête stockée de la vue source, y compris les références de la table dans la requête.

Soyez attentif à ce que les noms d’objets dans la définition d’un objet source soient entièrement ou partiellement qualifiés. Un nom pleinement qualifié comprend les noms de la base de données et des schémas. Tout clone de l’objet source inclut ces parties dans sa propre définition.

Par exemple :

-- 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);

Copy

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

Copy

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

Si vous avez l’intention de pointer une vue vers des tables portant le même nom dans d”autres bases de données ou schémas, nous vous suggérons de créer une nouvelle vue plutôt que de cloner une vue existante. Cette orientation concerne également les autres objets qui font référence à des objets dans leur définition.

Notes pour le clonage avec Time Travel¶

• La clause AT | BEFORE clone une base de données, un schéma ou une table à partir d’une date spécifiée dans le passé ou sur la base d’une instruction SQL spécifiée :

  • Le mot clé AT spécifie que la requête inclut tous les changements apportés par une instruction ou une transaction dont l’horodatage est égal au paramètre spécifié.

  • Le mot clé BEFORE spécifie que la requête se réfère à un point précédant immédiatement le paramètre spécifié.

• Cloner en utilisant STATEMENT équivaut à utiliser TIMESTAMP avec une valeur égale au temps d’exécution enregistré de l’instruction SQL (ou de la transaction qui l’accompagne), identifiée par l’ID de l’instruction spécifiée.

• Une erreur est renvoyée si :

  • L’objet cloné n’existait pas au moment précisé dans la clause AT | BEFORE.

  • Les données historiques nécessaires au clonage de l’objet ou de l’un de ses objets enfants (par exemple, les tables dans les schémas ou bases de données clonés) ont été supprimées.

    En guise de solution de contournement pour les objets enfants qui ont été purgés de Time Travel, utilisez le paramètre IGNORE TABLES WITH INSUFFICIENT DATA RETENTION de la commande CREATE <objet> … CLONE. Pour plus d’informations, voir Objets enfants et durée de conservation des données.

• Si un objet enfant d’une base de données ou d’un schéma cloné n’existait pas au moment spécifié dans la clause AT | BEFORE, l’objet enfant n’est pas cloné.

Pour plus d’informations, voir Compréhension et utilisation de la fonction Time Travel.

000707 (02000): Time travel data is not available for <object_type>
<object_name>. The requested time is either beyond the allowed time
travel period or before the object creation time.

... AT(TIMESTAMP => '2023-12-31 12:00:00')               -- fails
... AT(TIMESTAMP => '2023-12-31 12:00:00'::TIMESTAMP)    -- succeeds

Exemples¶

Cloner une base de données et tous les objets de la base de données dans son état actuel :

CREATE DATABASE mytestdb_clone CLONE mytestdb;

Cloner un schéma et tous les objets du schéma dans son état actuel :

CREATE SCHEMA mytestschema_clone CLONE testschema;

Cloner une table dans son état actuel :

CREATE TABLE orders_clone CLONE orders;

Cloner un schéma tel qu’il existait avant la date et l’heure dans l’horodatage spécifié :

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

Cloner une table telle qu’elle existait exactement à la date et à l’heure de l’horodatage spécifié :

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

Cloner une table telle qu’elle existait immédiatement avant l’exécution de l’instruction spécifiée. Remplacer l’ID de requête pour le paramètre STATEMENT dans l’exemple et exécutez l’instruction CREATE TABLE suivante :

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

Clonez une base de données et tous ses objets tels qu’ils existaient il y a quatre jours et ignorez toutes les tables dont la période de conservation des données est inférieure à quatre jours :

CREATE DATABASE restored_db CLONE my_db
  AT (TIMESTAMP => DATEADD(days, -4, current_timestamp)::timestamp_tz)
  IGNORE TABLES WITH INSUFFICIENT DATA RETENTION;

Cloner un schéma contenant un mélange de tables standard et de tables hybrides :

CREATE OR REPLACE SCHEMA clone_ht_schema CLONE ht_schema
  IGNORE HYBRID TABLES;

Le nouveau schéma contiendra uniquement les tables standard du schéma d’origine.