CREATE <Objekt> … CLONE

Erstellt eine Kopie eines vorhandenen Objekts im System. Dieser Befehl wird in erster Linie zum Erstellen von Nullkopie-Klonen von Datenbanken, Schemas und Tabellen verwendet, kann aber auch zum schnellen/einfachen Erstellen von Klonen anderer Schemaobjekte, wie externe Stagingbereiche, Dateiformate und Sequenzen, sowie Datenbankrollen verwendet werden.

Der Befehl ist eine Variation der objektspezifischen CREATE <Objekt>-Befehle mit dem zusätzlichen Schlüsselwort CLONE.

Objekte mit Time Travel klonen

Bei Datenbanken, Schemas und permanenten Tabellen unterstützt CLONE eine zusätzliche AT | BEFORE-Klausel für das Klonen mit Time Travel.

Für Datenbanken und Schemas unterstützt CLONE den Parameter IGNORE TABLES WITH INSUFFICIENT DATA RETENTION, um Tabellen zu überspringen, die aus Time Travel gelöscht wurden (z. B. transiente Tabellen mit einer eintägigen Datenaufbewahrungsfrist).

Syntax

Datenbanken, Schemas

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

Tabellen

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

Dynamische Tabellen

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

Datenbankrollen

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

Andere Schemaobjekte

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

Time Travel-Parameter

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

Die AT | BEFORE-Klausel akzeptiert einen der folgenden Parameter:

TIMESTAMP => timestamp

Gibt ein genaues Datum und eine genaue Zeit für Time Travel an. Der Wert muss explizit in einen TIMESTAMP-Wert umgewandelt werden.

OFFSET => time_difference

Gibt für Time Travel die Differenz in Sekunden von der aktuellen Zeit im Format -N an, wobei N eine Ganzzahl oder ein arithmetischer Ausdruck sein kann (z. B. entspricht -120 120 Sekunden; -30*60 entspricht 1.800 Sekunden oder 30 Minuten).

STATEMENT => id

Gibt die Abfrage-ID einer Anweisung an, die als Referenzpunkt für Time Travel verwendet werden soll. Dieser Parameter unterstützt alle Anweisungen eines der folgenden Typen:

  • DML (z. B. INSERT, UPDATE, DELETE)

  • TCL (BEGIN, COMMIT-Transaktion)

  • SELECT

Die Abfrage-ID muss auf eine Abfrage verweisen, die innerhalb der letzten 14 Tage ausgeführt wurde. Wenn die Abfrage-ID auf eine Abfrage verweist, die älter als 14 Tage ist, wird der folgende Fehler zurückgegeben:

Error: statement <query_id> not found

Um diese Einschränkung zu umgehen, verwenden Sie den Zeitstempel für die referenzierte Abfrage.

IGNORE TABLES WITH INSUFFICIENT DATA RETENTION

Ignorieren Sie Tabellen, für die in Time Travel keine historischen Daten mehr zum Klonen verfügbar sind. Wenn der in der AT|BEFORE-Klausel angegebene Zeitpunkt in der Vergangenheit für eine beliebige untergeordnete Tabelle in einer Datenbank oder einem Schema außerhalb der Datenaufbewahrungsfrist liegt, wird die Klonoperation für die untergeordnete Tabelle übersprungen. Weitere Informationen dazu finden Sie unter Untergeordnete Objekte und Datenaufbewahrungsdauer.

Allgemeine Nutzungshinweise

  • Ein Klon ist beschreibbar und unabhängig von seiner Quelle (d. h. Änderungen an der Quelle oder dem Klon werden im anderen Objekt nicht berücksichtigt).

  • Parameter, die explizit für eine Quelldatenbank, ein Schema oder eine Tabelle festgelegt wurden, werden in allen Klonen beibehalten, die aus dem Quellcontainer oder untergeordneten Objekten erstellt werden.

  • Um einen Klon zu erstellen, muss Ihre aktuelle Rolle die folgenden Berechtigungen für das Quellobjekt haben:

    Datenbankrollen

    OWNERSHIP-Berechtigung für die Datenbankrolle und CREATE DATABASE ROLE-Berechtigung für die Zieldatenbank.

    Tabellen

    SELECT

    Alerts, Pipes, Streams, Aufgaben

    OWNERSHIP

    Andere Objekte

    USAGE

    Damit Ihre aktuelle Rolle eine Tabelle oder ein Schema klonen kann, muss sie über die erforderlichen Berechtigungen für die Containerobjekte von Quelle und Klon verfügen.

  • Datenbankrollen:

    • Eine Datenbankrolle wird nicht geklont, wenn Sie den Befehl CREATE CLONE ausführen, um eine Datenbank oder andere Objekte, die in der Datenbank enthalten sind, zu klonen. Sie müssen den Befehl CREATE DATABASE ROLE … CLONE verwenden, um eine Datenbankrolle in die Zieldatenbank zu klonen.

    • Wenn die Datenbankrolle bereits in die Zieldatenbank geklont wurde, schlägt der Befehl fehl. In diesem Fall löschen Sie die Datenbankrolle in der Zieldatenbank und versuchen dann, den CLONE-Befehl erneut auszuführen.

  • Für Datenbanken und Schemas ist das Klonen rekursiv:

    • Beim Klonen einer Datenbank werden alle in der Datenbank enthaltenen Schemas und anderen Objekte geklont.

    • Beim Klonen eines Schemas werden alle im Schema enthaltenen Objekte geklont.

    Die folgenden Objekttypen werden jedoch nicht geklont:

    • Externe Tabellen

    • Interne (d. h. Snowflake) Stagingbereiche

  • Bei Datenbanken, Schemas und Tabellen trägt ein Klon erst dann zum gesamten Datenspeicher für das Objekt bei, wenn Operationen am Klon durchgeführt werden, die bestehende Daten ändern oder neue Daten hinzufügen. Beispiel:

    • Hinzufügen, Löschen oder Ändern von Zeilen in einer geklonten Tabelle.

    • Erstellen einer neuen, ausgefüllten Tabelle in einem geklonten Schema.

  • Beim Klonen einer Tabelle werden die Struktur, die Daten und bestimmte andere Eigenschaften (z. B. STAGE FILE FORMAT) der Quelltabelle repliziert.

    Allerdings:

    • Eine geklonte Tabelle enthält nicht den Ladeverlauf der Quelltabelle. Eine Folge davon ist, dass Datendateien, die in eine Quelltabelle geladen wurden, wieder in ihre Klone geladen werden können.

    • Obwohl eine geklonte Tabelle die Gruppierungsschlüssel der Quelltabelle repliziert, beginnt die neue Tabelle mit angehaltenem Automatic Clustering – auch wenn Automatic Clustering für die Quelltabelle nicht angehalten wurde.

  • Die CREATE TABLE … CLONE-Syntax enthält die COPY GRANTS-Schlüsselwörter, die sich wie folgt auf einen neuen Tabellenklon auswirken:

    • Wenn die COPY GRANTS-Schlüsselwörter nicht verwendet werden, übernimmt der neue Objektklon alle expliziten Zugriffsrechte der ursprünglichen Tabelle, aber erbt keine zukünftigen Zuweisungen, die im Schema für den Objekttyp definiert sind.

    • Wenn die COPY GRANTS-Schlüsselwörter nicht verwendet werden, übernimmt der neue Objektklon keine expliziten Zugriffsrechte der ursprünglichen Tabelle, aber alle zukünftigen Zuweisungen, die im Schema für den Objekttyp definiert sind (mit der Syntax GRANT <Berechtigungen> … ON FUTURE).

    Bemerkung

    Wenn die Anweisung eine vorhandene Tabelle mit demselben Namen ersetzt, werden die Berechtigungen aus der zu ersetzenden Tabelle kopiert. Wenn keine Tabelle mit diesem Namen vorhanden ist, werden die Berechtigungen aus der zu klonenden Quelltabelle kopiert.

  • Metadaten:

    Achtung

    Kunden müssen sicherstellen, dass bei der Nutzung des Snowflake-Dienstes keine personenbezogenen Daten (außer für ein Objekt „Benutzer“), sensible Daten, exportkontrollierte Daten oder andere regulierte Daten als Metadaten eingegeben werden. Weitere Informationen dazu finden Sie unter Metadatenfelder in Snowflake.

  • CREATE OR REPLACE <Objekt>-Anweisungen sind atomar. Das heißt, wenn ein Objekt ersetzt wird, erfolgt das Löschen des alten Objekts und das Erstellen des neuen Objekts in einer einzigen Transaktion.

Zusätzliche Regeln für das Klonen von Objekten

Metadaten

Ein Objektklon erbt den Namen und die Struktur des Quellobjekts, das zum Zeitpunkt der Ausführung der CREATE <Objekt> CLONE-Anweisung oder zu einem angegebenen Time Travel-Zeitpunkt in der Vergangenheit aktuell war. Ein Objektklon erbt alle anderen Metadaten, wie z. B. Kommentare oder Tabellen-Gruppierungsschlüssel, die zum Zeitpunkt der Ausführung der Anweisung im Quellobjekt aktuell sind, unabhängig davon, ob Time Travel verwendet wird.

Untergeordnete Objekte

Ein Datenbank- oder Schemaklon enthält alle Unterobjekte, die zum Zeitpunkt der Ausführung der Anweisung oder zum angegebenen Zeitpunkt/Punkt in der Vergangenheit aktiv waren. Ein Snapshot der Tabellendaten stellt den Status der Quelldaten beim Ausführen der Anweisung oder zum angegebenen Zeitpunkt in der Vergangenheit dar. Untergeordnete Objekte erben Name und Struktur der untergeordneten Quellobjekte zum Zeitpunkt der Ausführung der Anweisung.

Nicht geklont

Durch das Klonen einer Datenbank oder eines Schemas werden keine Objekte der folgenden Typen in die Datenbank oder das Schema geklont:

  • Externe Tabellen

  • Interne (d. h. Snowflake) Stagingbereiche

Pipes

Ein Datenbank- oder Schemaklon enthält nur Pipeobjekte, die auf externe (Amazon S3, Google Cloud Storage oder Microsoft Azure) Stagingbereiche verweisen. Interne (Snowflake) Pipes werden nicht geklont.

Der Standardstatus eines Pipeklons ist wie folgt:

  • Bei AUTO_INGEST = FALSE wird eine geklonte Pipe standardmäßig angehalten.

  • Bei AUTO_INGEST = TRUE wird eine geklonte Pipe auf den Status STOPPED_CLONED gesetzt. In diesem Zustand sammeln Pipes keine Ereignisbenachrichtigungen, wenn Dateien im Stagingbereich bereitgestellt werden. Wenn eine Pipe explizit fortgesetzt wird, verarbeitet sie nur Datendateien, die aufgrund neuer Ereignisbenachrichtigungen ausgelöst wurden.

Ein Pipeklon in einem der beiden Zustände kann durch Ausführen einer ALTER PIPE … RESUME-Anweisung fortgesetzt werden:

Tags

Das Klonen einer Datenbank oder eines Schemas wirkt sich wie folgt auf die Tags in dieser Datenbank oder diesem Schema aus:

  • Tag-Zuordnungen im Quellobjekt (z. B. Tabelle) bleiben in den geklonten Objekten erhalten.

  • Für eine Datenbank oder ein Schema:

    Die in dieser Datenbank oder diesem Schema gespeicherten Tags werden ebenfalls geklont.

    Wenn eine Datenbank oder ein Schema geklont wird, werden die Tags, die sich in diesem Schema oder dieser Datenbank befinden, ebenfalls geklont.

    Wenn eine Tabelle oder Ansicht im Quellschema bzw. in der Quelldatenbank vorhanden ist und Verweise auf Tags in demselben Schema oder derselben Datenbank hat, wird die geklonte Tabelle oder Ansicht dem entsprechenden geklonten Tag (im Zielschema bzw. in der Zieldatenbank) zugeordnet und nicht dem Tag im Quellschema bzw. der Quelldatenbank.

Tabellendaten

Beim Klonen einer Datenbank, eines Schemas oder einer Tabelle wird ein Snapshot der Daten in jeder Tabelle erstellt und dem Klon zur Verfügung gestellt. Der Snapshot stellt den Status der Quelldaten entweder zum Zeitpunkt der Ausführung der Anweisung oder zum angegebenen Zeitpunkt in der Vergangenheit dar (mittels Time Travel).

Objektreferenzen

Objekte wie Ansichten, Streams und Aufgaben enthalten in ihrer Definition Objektreferenzen. Beispiel:

  • Eine Ansicht enthält eine gespeicherte Abfrage, die Tabellenreferenzen enthält.

  • Ein Stream zeigt auf eine Quelltabelle.

  • Eine Aufgabe oder ein Alert ruft eine gespeicherte Prozedur auf oder führt eine SQL-Anweisung aus, die auf andere Objekte verweist.

Wenn eines dieser Objekte geklont wird, entweder in einer geklonten Datenbank oder einem geklonten Schema oder als einzelnes Objekt für diejenigen Objekttypen, die das Klonen unterstützen, erbt der Klon Referenzen auf andere Objekte aus der Definition des Quellobjekts. Beispielsweise erbt der Klon einer Ansicht die gespeicherte Abfrage von der Quellansicht, einschließlich der Tabellenreferenzen in der Abfrage.

Achten Sie genau darauf, ob die Objektnamen in der Definition eines Quellobjekts vollständig oder teilweise qualifiziert sind. Ein vollqualifizierter Name umfasst den Datenbank- und den Schemanamen. Jeder Klon des Quellobjekts enthält diese Teile in seiner eigenen Definition.

Beispiel:

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

Wenn Sie beabsichtigen, auf eine Ansicht auf gleichnamige Tabellen in anderen Datenbanken oder Schemas zu verweisen, schlagen wir vor, eine neue Ansicht zu erstellen, anstatt eine bestehende Ansicht zu klonen. Diese Anleitung bezieht sich auch auf andere Objekte, die in ihrer Definition auf Objekte verweisen.

Bemerkung

  • Für die Klonoperation gelten bestimmte Einschränkungen. Beispielsweise können DDL-Anweisungen, die das Quellobjekt während einer Klonierungsoperation betreffen, das Ergebnis verändern oder Fehler verursachen.

  • Das Klonen erfolgt nicht sofort, insbesondere bei großen Objekten (Datenbanken, Schemas, Tabellen), und sperrt das zu klonierende Objekt nicht. Daher spiegelt ein Klon keine DML-Anweisungen wider, die gegebenenfalls auf Tabellendaten angewendet werden, während die Klonierungsoperation noch ausgeführt wird.

Weitere Informationen zu diesem und anderen Anwendungsfällen, die sich auf Ihre Klonierungsoperation auswirken können, finden Sie unter Hinweise zum Klonen.

Hinweise zum Klonen mit Time Travel (nur Datenbanken, Schemas und Tabellen)

  • Die AT | BEFORE-Klausel klont eine Datenbank, ein Schema oder eine Tabelle ab einem bestimmten Zeitpunkt in der Vergangenheit oder basierend auf einer bestimmten SQL-Anweisung:

    • Das Schlüsselwort AT gibt an, dass die Anforderung alle Änderungen beinhaltet, die durch eine Anweisung oder Transaktion mit einem Zeitstempel gleich dem angegebenen Parameter vorgenommen werden.

    • Das Schlüsselwort BEFORE gibt an, dass sich die Anforderung auf einen Zeitpunkt unmittelbar vor dem angegebenen Parameter bezieht.

  • Das Klonen mit STATEMENT entspricht dem Verwenden von TIMESTAMP mit einem Wert, der der aufgezeichneten Ausführungszeit der SQL-Anweisung (oder ihrer umschließenden Transaktion) entspricht, wie sie durch die angegebene Anweisung-ID identifiziert wird.

  • In folgenden Fällen wird ein Fehler zurückgegeben:

    • Das zu klonende Objekt existierte nicht an der in der AT | BEFORE-Klausel angegebenen Stelle in der Vergangenheit.

    • Die historischen Daten, die zum Klonen des Objekts oder eines seiner Unterobjekte benötigt werden (z. B. Tabellen in geklonten Schemas oder Datenbanken), wurden bereinigt.

      Als Problemumgehung für untergeordnete Objekte, die aus Time Travel gelöscht wurden, verwenden Sie den Parameter IGNORE TABLES WITH INSUFFICIENT DATA RETENTION des Befehls CREATE <object> … CLONE. Weitere Informationen dazu finden Sie unter Untergeordnete Objekte und Datenaufbewahrungsdauer.

  • Wenn ein untergeordnetes Objekt in einer geklonten Datenbank oder einem geklonten Schema an der in der AT | BEFORE-Klausel angegebenen Stelle in der Vergangenheit nicht vorhanden war, wird das untergeordnete Objekt nicht geklont.

Weitere Informationen finden Sie unter Verstehen und Verwenden von Time Travel.

Probleme beim Klonen von Objekten mit Time Travel beheben

Die folgenden Szenarios können Ihnen helfen, möglicherweise auftretende Probleme beim Klonen eines Objekts mit Time Travel zu beheben.

Fehler 

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.

Dieser Fehler kann aus den folgenden Gründen zurückgegeben werden:

Ursache

Der in der AT|BEFORE-Klausel angegebene Zeitpunkt in der Vergangenheit liegt außerhalb der Datenaufbewahrungsfrist für das Objekt.

Lösung

Überprüfen Sie die Datenaufbewahrungsfrist für das Objekt mit dem entsprechenden SHOW <Objekte>-Befehl und der Spalte retention_time. Aktualisieren Sie die CREATE <object> … CLONE-Anweisung, um einen Zeitpunkt in der Vergangenheit zu verwenden, der innerhalb der Datenaufbewahrungsfrist für das Objekt liegt.

Ursache

Die Klonoperation für eine Datenbank oder ein Schema schlägt fehl, wenn die historischen Daten eines untergeordneten Objekts aus Time Travel verschoben wurden.

Lösung

Um untergeordnete Tabellen zu überspringen, für die keine historischen Daten mehr in Time Travel verfügbar sind, führen Sie die Klonanweisung mit dem Parameter IGNORE TABLES WITH INSUFFICIENT DATA RETENTION aus, um diese Tabellen zu überspringen.

Ursache

In einigen Fällen wird das Problem durch Verwendung einer Zeichenfolge verursacht, bei der ein Zeitstempel erwartet wird.

Lösung

Wandeln Sie die Zeichenfolge in einen Zeitstempel um.

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

Beispiele

Klonen Sie eine Datenbank und alle Objekte innerhalb der Datenbank in ihrem aktuellen Status:

CREATE DATABASE mytestdb_clone CLONE mytestdb;
Copy

Klonen Sie ein Schema und alle Objekte innerhalb des Schemas in seinem aktuellen Status:

CREATE SCHEMA mytestschema_clone CLONE testschema;
Copy

Klonen Sie eine Tabelle in ihrem aktuellen Status:

CREATE TABLE orders_clone CLONE orders;
Copy

Klonen Sie ein Schema so, wie es vor dem Datum und der Uhrzeit im angegebenen Zeitstempel existierte:

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

Klonen Sie eine Tabelle so, wie sie genau zum Datum und zur Uhrzeit des angegebenen Zeitstempels existierte:

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

Klonen Sie eine Tabelle so, wie sie unmittelbar vor der Ausführung der angegebenen Anweisung existierte (d. h. Abfrage-ID):

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

Klonen Sie eine Datenbank und alle ihre Objekte so, wie sie vor vier Tagen existierten, und überspringen Sie alle Tabellen, die eine Datenaufbewahrungsfrist von weniger als vier Tagen haben:

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