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

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

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 ] 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 TIMESTAMP.

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.

Notes générales sur l’utilisation¶

• Un clone est inscriptible et est indépendant de sa source (c’est-à-dire que les modifications apportées à la source ou au clone ne se reflètent pas 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 créer un clone, votre rôle actuel doit avoir les privilèges suivants sur l’objet source :

  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.

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

  • Un rôle de base de données n’est pas cloné lorsque vous exécutez la commande CREATE CLONE pour cloner une base de données ou d’autres objets contenus dans la base de données. Vous devez utiliser la commande CREATE DATABASE ROLE … CLONE pour cloner un rôle de base de données dans la base de données cible.

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

• La syntaxe CREATE TABLE … CLONE et CREATE EVENT TABLE … CLONE comprend les mots-clés COPY GRANTS, qui affectent un nouveau clone de table comme suit :

  • Si les mots-clés COPY GRANTS sont utilisés, 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 les mots-clés COPY GRANTS ne sont pas utilisés, 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.

• 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 objets clonés¶

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.

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

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

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 (bases de données, schémas, tables et tables d’événements uniquement)¶

• 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 Comprendre et utiliser 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;

Copy

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

CREATE SCHEMA mytestschema_clone CLONE testschema;

Copy

Cloner une table dans son état actuel :

CREATE TABLE orders_clone CLONE orders;

Copy

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

Copy

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

Copy

Cloner une table telle qu’elle existait immédiatement avant l’exécution de l’instruction spécifiée (c’est-à-dire l’ID de requête) :

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

Copy

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;

Copy