ATTACH

たとえばデータベースを別のサーバーに移行する際などに、テーブルまたは Dictionary をアタッチします。構文

ATTACH TABLE|DICTIONARY|DATABASE [IF NOT EXISTS] [db.]name [ON CLUSTER cluster] ...

このクエリはディスク上にデータを作成しません。データはすでに適切な場所に存在していることを前提とし、指定したテーブル、Dictionary、またはデータベースに関する情報をサーバーに追加するだけです。ATTACHクエリを実行すると、サーバーはそのテーブル、Dictionary、またはデータベースの存在を認識します。テーブルが以前にデタッチされていた (DETACHクエリ) 場合、つまりその構造が既知である場合は、構造を定義せずに短縮記法を使用できます。

既存のテーブルをアタッチ

構文

ATTACH TABLE [IF NOT EXISTS] [db.]name [ON CLUSTER cluster]

このクエリは、サーバーの起動時に使用されます。サーバーはテーブルのメタデータを ATTACH クエリを含むファイルとして保存しており、起動時にそれらをそのまま実行します (ただし一部のシステムテーブルは例外で、サーバー上で明示的に作成されます) 。テーブルが恒久的にデタッチされている場合、サーバーの起動時に再アタッチされることはないため、ATTACH クエリを明示的に実行する必要があります。

新しいテーブルを作成してデータをアタッチする

テーブルデータへのパスを指定する場合

このクエリは、指定した構造で新しいテーブルを作成し、user_files 内の指定したディレクトリにあるテーブルデータをアタッチします。このクエリを実行するには、ユーザーに READ ON FILE および WRITE ON FILE 権限が必要です。ディレクトリを読み取り、それを新しいテーブルのデータパスに移動するためです。構文

ATTACH TABLE name FROM 'path/to/data/' (col1 Type1, ...)

例

Query

DROP TABLE IF EXISTS test;
INSERT INTO TABLE FUNCTION file('01188_attach/test/data.TSV', 'TSV', 's String, n UInt8') VALUES ('test', 42);
ATTACH TABLE test FROM '01188_attach/test' (s String, n UInt8) ENGINE = File(TSV);
SELECT * FROM test;

Response

┌─s────┬──n─┐
│ test │ 42 │
└──────┴────┘

指定したテーブル UUID を使用する

このクエリは、指定された構造を持つ新しいテーブルを作成し、指定した UUID を持つテーブルのデータをアタッチします。これは Atomic データベースエンジンでサポートされています。構文

ATTACH TABLE name UUID '<uuid>' (col1 Type1, ...)

MergeTree テーブルを ReplicatedMergeTree としてアタッチ

レプリケーションされていない MergeTree テーブルを ReplicatedMergeTree としてアタッチできます。ReplicatedMergeTree テーブルは、default_replica_path および default_replica_name Settings の値を使って作成されます。レプリケートされたテーブルを通常の MergeTree としてアタッチすることも可能です。この変換は、Atomic および Ordinary データベース内のテーブルでサポートされています。Ordinary データベース内のテーブルには UUID がないため、変換時に UUID が生成されます。この UUID を用いて default_replica_path が一度だけ展開され、その結果得られたパスが変換後のテーブルのエンジン引数に明示的に保存されます。このようなテーブルにレプリカを追加するには、ReplicatedMergeTree エンジンの第 1 引数にこのパスを明示的に指定してください。このパスは system.replicas の zookeeper_path カラムで確認できます。保存されたパスには {uuid} マクロが含まれないため、このようなテーブルが所有する znode は、ロードのたびにパスを default_replica_path と改めて照合することで特定されます。このテンプレートとの照合ができない場合 (たとえば {uuid} が複数回展開される場合)、変換は拒否されます。なお、default_replica_name 内での {uuid} の使用は、いずれの変換でもサポートされていません。このクエリでは、ZooKeeper 内のテーブルデータには影響しない点に注意してください。つまり、アタッチ後に SYSTEM RESTORE REPLICA を使用して ZooKeeper にメタデータを追加するか、SYSTEM DROP REPLICA ... FROM ZKPATH ... でクリアする必要があります。既存の ReplicatedMergeTree テーブルにレプリカを追加しようとしている場合は、変換後の MergeTree テーブル内のローカルデータはすべてデタッチされることに注意してください。構文

ATTACH TABLE [db.]name AS [NOT] REPLICATED

テーブルをレプリケーション対応に変換する

DETACH TABLE test;
ATTACH TABLE test AS REPLICATED;
SYSTEM RESTORE REPLICA test;

テーブルを非レプリケート化する テーブルのZooKeeperのパスとレプリカ名を取得します：

Query

SELECT replica_name, zookeeper_path FROM system.replicas WHERE table='test';

Response

┌─replica_name─┬─zookeeper_path─────────────────────────────────────────────┐
│ r1           │ /clickhouse/tables/401e6a1f-9bf2-41a3-a900-abb7e94dff98/s1 │
└──────────────┴────────────────────────────────────────────────────────────┘

テーブルをレプリケーションなしとしてアタッチし、ZooKeeper からレプリカのデータを削除します:

Query

DETACH TABLE test;
ATTACH TABLE test AS NOT REPLICATED;
SYSTEM DROP REPLICA 'r1' FROM ZKPATH '/clickhouse/tables/401e6a1f-9bf2-41a3-a900-abb7e94dff98/s1';

既存のDictionaryをアタッチ

以前にデタッチされたDictionaryをアタッチします。構文

ATTACH DICTIONARY [IF NOT EXISTS] [db.]name [ON CLUSTER cluster]

既存のデータベースをアタッチ

以前にデタッチされたデータベースをアタッチします。構文

ATTACH DATABASE [IF NOT EXISTS] name [ENGINE=<database engine>] [ON CLUSTER cluster]

SQLリファレンス

データ型

エンジン

関数

フォーマット

設定

システムテーブル

データレイク

既存のテーブルをアタッチ

新しいテーブルを作成してデータをアタッチする

テーブルデータへのパスを指定する場合

指定したテーブル UUID を使用する

MergeTree テーブルを ReplicatedMergeTree としてアタッチ

既存のDictionaryをアタッチ

既存のデータベースをアタッチ

​既存のテーブルをアタッチ

​新しいテーブルを作成してデータをアタッチする

​テーブルデータへのパスを指定する場合

​指定したテーブル UUID を使用する

​MergeTree テーブルを ReplicatedMergeTree として アタッチ

​既存のDictionaryをアタッチ

​既存のデータベースをアタッチ

既存のテーブルをアタッチ

新しいテーブルを作成してデータをアタッチする

テーブルデータへのパスを指定する場合

指定したテーブル UUID を使用する

MergeTree テーブルを ReplicatedMergeTree としてアタッチ

既存のDictionaryをアタッチ

既存のデータベースをアタッチ