CREATE <オブジェクト> ... CLONE¶
システム内にある既存のオブジェクトのコピーを作成します。このコマンドは主に、データベース、スキーマ、およびテーブルの ゼロコピークローン を作成するために使用されます。ただし、外部ステージ、ファイル形式、シーケンス、データベースロールなど、その他のスキーマオブジェクトのクローンをすばやく/簡単に作成するためにも使用できます。
このコマンドは、 CLONE キーワードが追加されたオブジェクト固有の CREATE <オブジェクト> コマンドのバリエーションです。
Time Travelを使ってオブジェクトをクローンする¶
データベース、スキーマ、および非仮テーブルの場合、 CLONE は Time Travel を使用したクローン作成のための追加の AT | BEFORE 句をサポートします。
データベースとスキーマの場合、 CLONE はTime Travelからパージされたテーブルをスキップする IGNORE TABLES WITH INSUFFICIENT DATA RETENTION パラメーターをサポートします（例えば、 データ保持期間が1日の一時テーブル）。
構文¶
データベース、スキーマ¶
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>
...
Time Travelパラメーター¶
{ AT | BEFORE } ( { TIMESTAMP => timestamp | OFFSET => time_difference | STATEMENT => id } )AT | BEFORE 句は、次のいずれかのパラメーターを受け付けます。
TIMESTAMP => timestampTime Travelに使用する正確な日付と時刻を指定します。値は明示的に TIMESTAMP にキャストする必要があります。
OFFSET => time_differenceTime Travelに使用する現在の時刻との差を秒単位で
-Nの形式で指定します。Nは整数または数式です（例：-120は120秒、-30*60は1800秒または30分）。STATEMENT => idTime Travelの参照ポイントとして使用するステートメントのクエリ ID を指定します。このパラメーターは、次のいずれかのタイプのステートメントをサポートします。
DML （例： INSERT、 UPDATE、 DELETE）
TCL （BEGIN、 COMMIT トランザクション）
SELECT
クエリ ID は、過去14日以内に実行されたクエリを参照する必要があります。クエリ ID が14日以上経過したクエリを参照している場合は、次のエラーが返されます。
Error: statement <query_id> not foundこの制限を回避するには、参照されるクエリのタイムスタンプを使用します。
IGNORE TABLES WITH INSUFFICIENT DATA RETENTIONTime Travelでクローンに利用可能な履歴データがなくなったテーブルを無視します。AT | BEFORE 句で指定された過去の時間が、データベースまたはスキーマ内の子テーブルのデータ保持期間を超えている場合は、子テーブルのクローン作成操作をスキップします。詳細については、 子オブジェクトとデータ保持時間 をご参照ください。
一般的な使用上の注意¶
クローンは書き込み可能で、そのソースから独立しています（つまり、ソースまたはクローンに加えられた変更は、他のオブジェクトには反映されません）。
ソースデータベース、スキーマ、またはテーブルに明示的に設定されたパラメーターは、ソースコンテナーまたは子オブジェクトから作成されたすべてのクローンに保持されます。
クローンを作成するには、現在のロールに、ソースオブジェクトに対する次の権限が必要となります。
- データベースロール:
データベースロールの OWNERSHIP、およびターゲットデータベースの CREATE DATABASE ROLE 権限。
- スキーマ:
WITH MANAGED ACCESS 句を指定した場合、必要な権限はソーススキーマが管理スキーマか非管理スキーマかによって異なります。詳細については、 CREATE SCHEMA 権限 をご参照ください。
- テーブル:
SELECT
- アラート、パイプ、ストリーム、タスク:
OWNERSHIP
- その他のオブジェクト:
USAGE
さらに、スキーマまたはスキーマ内のオブジェクトをクローンするには、現在のロールに、ソースとクローンの両方のコンテナーオブジェクトに対する必要な権限を有していなければなりません。
データベースロールの場合:
CREATE CLONE コマンドを実行してデータベースやデータベースに含まれる他のオブジェクトをクローンしても、データベースロールはクローンされません。CREATE DATABASE ROLE ... CLONE コマンドを使用して、ターゲットデータベースにデータベースロールのクローンを作成する必要があります。
データベースロールがすでにターゲットデータベースにクローンされている場合、コマンドは失敗します。この問題が発生した場合は、対象のデータベースからデータベースロールをドロップし、 CLONE コマンドを再度実行してください。
データベースとスキーマの場合、クローンは再帰的です。
データベースのクローンを作成すると、データベース内のスキーマおよび他のオブジェクトすべてをクローンします。
スキーマのクローンを作成すると、スキーマに含まれるオブジェクトすべてをクローンします。
ただし、次のオブジェクトタイプはクローン されません。
外部テーブル
内部（Snowflake）ステージ
データベース、スキーマ、およびテーブルの場合、クローンは、既存のデータを変更する、または新しいデータを追加する操作がクローンで実行されるまで、オブジェクトのデータストレージ全体に寄与 しません 。
クローンテーブルの行を追加、削除、または変更します。
クローンされたスキーマに新しいデータを入力したテーブルを作成します。
テーブルのクローンを作成すると、ソーステーブルの構造、データ、およびその他の特定のプロパティ（例
STAGE FILE FORMAT）がクローンされます。ただし、
クローンテーブルには、ソーステーブルのロード履歴が 含まれません 。この結果の1つとして、ソーステーブルにロードされたデータファイルは、クローンに再度ロードできるようになります。
クローンテーブルはソーステーブルのクラスタリングキーを複製しますが、新しいテーブルは、ソーステーブルの自動クラスタリングが中断されていない場合でも、自動クラスタリングが中断された状態で開始されます。
CREATE TABLE ... CLONE と CREATE EVENT TABLE ... CLONE 構文には、次のように新しいテーブルクローンに影響する COPY GRANTS キーワードが含まれています。
COPY GRANTS キーワードを使用すると、新しいオブジェクトのクローンは、元のテーブルに付与された明示的なアクセス権限を継承しますが、スキーマ内のオブジェクト型で定義された将来の付与は継承 しません。
COPY GRANTS キーワードを使用 しない 場合、新しいオブジェクトのクローンは、元のテーブルに付与された明示的なアクセス権限を継承しませんが、スキーマ内のオブジェクト型で定義された将来の付与は継承します（GRANT <権限> ... ON FUTURE 構文を使用）。
注釈
ステートメントにより同じ名前の既存のテーブルを置き換える場合、権限は置き換えられるテーブルからコピーされます。その名前の既存のテーブルがない場合、権限はクローンされるソーステーブルからコピーされます。
メタデータについて。
注意
Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。
CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。
オブジェクトのクローンに適用される追加の規則¶
- メタデータ:
オブジェクトクローンは、 Time Travel を使用して、CREATE <オブジェクト> CLONE ステートメントの実行時または過去の指定された時間/ポイントの 名前 および 構造 を継承します。オブジェクトクローンは、Time Travelが使用されているかどうかに関係なく、ステートメントの実行時にソースオブジェクトで現在使用されているコメントやテーブルクラスタリングキーなどの他のメタデータを継承します。
- 子オブジェクト:
データベースまたはスキーマのクローンには、ステートメントの実行時または過去の指定された時間/ポイントでアクティブなすべての子オブジェクトが含まれます。テーブルデータのスナップショットは、ステートメントが実行されたとき、または過去の指定された時間/ポイントでソースデータの状態を表します。子オブジェクトは、ステートメントの実行時にソースの子オブジェクトの名前と構造を継承します。
- クローンされません:
データベースまたはスキーマのクローンを作成しても、データベースまたはスキーマ内の次のタイプのオブジェクトはクローン されません。
外部テーブル
内部（Snowflake）ステージ
- パイプ:
データベースまたはスキーマのクローンには、外部（Amazon S3、Google Cloud Storage、またはMicrosoft Azure）ステージを参照するパイプオブジェクトのみが含まれます。内部（Snowflake）パイプはクローンされません。
パイプクローンのデフォルトの状態は次のとおりです。
AUTO_INGEST = FALSEの場合、クローンされたパイプはデフォルトで一時停止します。AUTO_INGEST = TRUEの場合、クローンされたパイプはSTOPPED_CLONED状態に設定されます。この状態では、パイプは新しくステージングされたファイルの結果としてイベント通知を蓄積しません。パイプが明示的に再開されると、新しいイベント通知の結果としてトリガーされたデータファイルのみを処理します。
ALTER PIPE ... RESUME ステートメントを実行すると、どちらの状態のパイプクローンも再開できます。
- タグ:
データベースまたはスキーマのクローンを作成すると、そのデータベースまたはスキーマの タグ に次の影響が及びます。
ソースオブジェクト（例: テーブル）にあるタグの関連付けは、クローンされたオブジェクトで維持されます。
データベースまたはスキーマの場合は、
そのデータベースまたはスキーマに保存されているタグもクローンされます。
データベースまたはスキーマがクローンされると、そのスキーマまたはデータベースに存在するタグもクローンされます。
テーブルまたはビューがソーススキーマ/データベースに存在し、同じスキーマまたはデータベースにあるタグへの参照がある場合、クローンされたテーブルまたはビューは、ソーススキーマまたはデータベースにあるタグの代わりに、対応するクローンタグ（ターゲットスキーマ/データベース内）にマップされます。
- Java UDF:
Java UDF は、Java UDF を含むデータベースまたはスキーマがクローンされるときに、クローンできます。クローンを作成するには、Java UDF が特定の条件を満たす必要があります。詳細については、 クローニングの制限 をご参照ください。
- テーブルデータ:
データベース、スキーマ、またはテーブルのクローンを作成すると、各テーブルのデータのスナップショットが作成され、クローンで使用できるようになります。スナップショットは、ステートメントの実行時または過去の指定された時間/ポイント（Time Travel を使用）でのソースデータの状態を表します。
- オブジェクト参照:
ビュー、ストリーム、タスクなどのオブジェクトの定義には、オブジェクト参照が含まれています。例:
ビューにはテーブル参照を含む保存されたクエリが含まれています。
ストリームはソーステーブルをポイントします。
タスクまたはアラートは、ストアドプロシージャを呼び出すか、他のオブジェクトを参照する SQL ステートメントを実行します。
これらのオブジェクトの1つが、クローンされたデータベースまたはスキーマで、または個別のオブジェクトとしてクローンされると、クローニングをサポートするオブジェクトタイプに対して、ソースオブジェクトの定義から他のオブジェクトへの参照を継承します。たとえば、ビューのクローンは、クエリ内のテーブル参照を含め、ソースビューから保存されたクエリを継承します。
ソースオブジェクトの定義内のオブジェクト名が完全にまたは部分的に修飾されているかどうかに細心の注意を払ってください。完全修飾名には、データベース名とスキーマ名が含まれます。ソースオブジェクトのクローンでは、これらの部分が独自の定義に含まれています。
例:
-- 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; | | | +--------------------------------------------------------------------------------+
他の データベースまたはスキーマ内の同じ名前のテーブルをビューにポイントする場合は、既存のビューのクローンを作成するのではなく、新しいビューを作成することをお勧めします。このガイダンスは、定義内のオブジェクトを参照する他のオブジェクトにも関係します。
注釈
クローン操作には特定の制限が適用されます。例えば、クローン操作中にソースオブジェクトに影響を与える DDL ステートメントは、結果を変更したり、エラーの原因となったりする可能性があります。
特に大きなオブジェクト（データベース、スキーマ、テーブル）の場合、クローン作成は瞬時に行われず、クローン作成中のオブジェクトはロックされません。そのため、クローン操作がまだ実行されている間、クローンは、該当する場合、テーブルデータに適用される DML ステートメントを反映しません。
この操作およびクローン作成操作に影響する可能性のあるその他の使用例の詳細については、 クローニングに関する考慮事項 をご参照ください。
Time Travelを使用したクローニングに関する注意事項（データベース、スキーマ、テーブル、およびイベントテーブルのみ）¶
AT | BEFORE 句は、過去の指定した時点、または指定した SQL ステートメントに基づいて、データベース、スキーマ、またはテーブルをクローンします。
ATキーワードは、指定されたパラメーターに等しいタイムスタンプを持つステートメント、またはトランザクションによる変更がリクエストに含まれることを指定します。BEFOREキーワードは、リクエストが、指定されたパラメーターの直前のポイントを参照するように指定します。
STATEMENTを使用したクローンの作成は、指定されたステートメント ID で識別される、 SQL ステートメント（またはそのトランザクションを囲むトランザクション）の記録された実行時間に等しい値でTIMESTAMPを使用するのと同等です。次の場合にエラーが返されます。
クローン作成中のオブジェクトは、 AT | BEFORE 句で指定された過去の時点では存在していませんでした。
オブジェクトまたはその子オブジェクト（クローンスキーマまたはデータベース内のテーブルなど）のクローンを作成するために必要な履歴データはパージされました。
Time Travelからパージされた子オブジェクトの回避策として、 CREATE <object> ... CLONE コマンドの IGNORE TABLES WITH INSUFFICIENT DATA RETENTION パラメーターを使用します。詳細については、 子オブジェクトとデータ保持時間 をご参照ください。
AT | BEFORE 句で指定された過去の時点で、クローン化されたデータベースまたはスキーマ内の子オブジェクトが存在しなかった場合、子オブジェクトはクローン化されません。
詳細については、 Time Travelの理解と使用 をご参照ください。
Time Travelを使用したオブジェクトのクローンに関するトラブルシューティング¶
次のシナリオは、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 | BEFORE 句で指定された過去の時間がオブジェクトのデータ保持期間を超えている。 |
|---|---|
解決策 |
適切な SHOW <オブジェクト> コマンドと |
原因 |
子オブジェクトの履歴データがTime Travelの範囲外に移動した場合、データベースまたはスキーマのクローン作成操作は失敗します。 |
|---|---|
解決策 |
Time Travelで利用できる履歴データがなくなった子テーブルをスキップするには、 IGNORE TABLES WITH INSUFFICIENT DATA RETENTION パラメーターを使用してクローン作成ステートメントを実行して、これらのテーブルをスキップします。 |
原因 |
場合によっては、これはタイムスタンプが期待される場所で文字列を使用することによって引き起こされます。 |
|---|---|
解決策 |
文字列をタイムスタンプにキャストします。 ... AT(TIMESTAMP => '2023-12-31 12:00:00') -- fails
... AT(TIMESTAMP => '2023-12-31 12:00:00'::TIMESTAMP) -- succeeds
|
例¶
データベースおよびデータベース内のすべてのオブジェクトを現在の状態でクローンします。
CREATE DATABASE mytestdb_clone CLONE mytestdb;
現在の状態でスキーマとスキーマ内のすべてのオブジェクトをクローンします。
CREATE SCHEMA mytestschema_clone CLONE testschema;
現在の状態でテーブルをクローンします。
CREATE TABLE orders_clone CLONE orders;
指定されたタイムスタンプの日付と時刻の前に存在していたスキーマをクローンします。
CREATE SCHEMA mytestschema_clone_restore CLONE testschema BEFORE (TIMESTAMP => TO_TIMESTAMP(40*365*86400));
指定されたタイムスタンプの日付と時刻に正確に存在するテーブルをクローンします。
CREATE TABLE orders_clone_restore CLONE orders AT (TIMESTAMP => TO_TIMESTAMP_TZ('04/05/2013 01:02:03', 'mm/dd/yyyy hh24:mi:ss'));
指定されたステートメント（クエリ ID）の実行直前に存在していたテーブルをクローンします。
CREATE TABLE orders_clone_restore CLONE orders BEFORE (STATEMENT => '8e5d0ca9-005e-44e6-b858-a8f5b37c5726');
データベースとそのすべてのオブジェクトを4日前の状態でクローンし、データ保持期間が4日未満のテーブルはスキップします。
CREATE DATABASE restored_db CLONE my_db AT (TIMESTAMP => DATEADD(days, -4, current_timestamp)::timestamp_tz) IGNORE TABLES WITH INSUFFICIENT DATA RETENTION;