ALTER TABLE ... PARTITION

パーティションに対して、次の操作を使用できます。

• DETACH PARTITION|PART — パーティションまたはパーツを detached ディレクトリに移動し、管理対象から外します。
• DROP PARTITION|PART — パーティションまたはパーツを削除します。
• DROP DETACHED PARTITION|PART - detached からパーツ、またはパーティション内のすべてのパーツを削除します。
• FORGET PARTITION — 空の場合、ZooKeeper からパーティションのメタデータを削除します。
• ATTACH PARTITION|PART — detached ディレクトリからパーティションまたはパーツをテーブルに追加します。
• ATTACH PARTITION FROM — あるテーブルから別のテーブルへデータのパーティションをコピーして追加します。
• REPLACE PARTITION — あるテーブルから別のテーブルへデータのパーティションをコピーして置き換えます。
• MOVE PARTITION TO TABLE — データのパーティションをあるテーブルから別のテーブルへ移動します。
• CLEAR COLUMN IN PARTITION — パーティション内の指定したカラムの値をリセットします。
• CLEAR INDEX IN PARTITION — パーティション内の指定した二次索引をリセットします。
• FREEZE PARTITION — パーティションのバックアップを作成します。
• UNFREEZE PARTITION — パーティションのバックアップを削除します。
• FETCH PARTITION|PART — 別のサーバーからパーツまたはパーティションをダウンロードします。
• MOVE PARTITION|PART — パーティションまたはデータパーツを別のディスクまたはボリュームへ移動します。
• UPDATE IN PARTITION — 条件に基づいてパーティション内のデータを更新します。
• DELETE IN PARTITION — 条件に基づいてパーティション内のデータを削除します。
• REWRITE PARTS — テーブル内のパーツ (または特定のパーティション内のパーツ) を完全に書き換えます。

ALTER TABLE table_name [ON CLUSTER cluster] DETACH PARTITION|PART partition_expr

指定したパーティションのすべてのデータをdetachedディレクトリに移動します。サーバーは、デタッチされたデータパーティションを存在しないものとして扱い、認識しなくなります。ATTACHクエリを実行するまで、サーバーはこのデータを認識しません。

例:

ALTER TABLE mt DETACH PARTITION '2020-11-21';
ALTER TABLE mt DETACH PART 'all_2_2_0';

パーティション式の設定については、パーティション式の指定方法 のセクションを参照してください。

クエリの実行後は、detached ディレクトリ内のデータを自由に扱えます。ファイルシステムから削除しても、そのまま残しておいてもかまいません。

このクエリはレプリケートされるため、すべてのレプリカ上でデータが detached ディレクトリに移動されます。このクエリを実行できるのは、リーダー レプリカ上だけである点に注意してください。レプリカがリーダーかどうかを確認するには、system.replicas テーブルに対して SELECT クエリを実行します。あるいは、すべてのレプリカで DETACH クエリを実行するほうが簡単です。リーダー レプリカ以外のすべてのレプリカは例外をスローします (複数のリーダーを許可できるためです) 。

ALTER TABLE table_name [ON CLUSTER cluster] DROP PARTITION|PART partition_expr

指定したパーティションをテーブルから削除します。このクエリはパーティションを非アクティブとしてマークし、約 10 分でデータを完全に削除します。

パーティション式の設定については、パーティション式の指定方法 のセクションを参照してください。

このクエリはレプリケートされるため、すべてのレプリカ上のデータが削除されます。

例:

ALTER TABLE mt DROP PARTITION '2020-11-21';
ALTER TABLE mt DROP PART 'all_4_4_0';

ALTER TABLE table_name [ON CLUSTER cluster] DROP DETACHED PARTITION|PART ALL|partition_expr

指定したパーツ、または指定したパーティション内のすべてのパーツをdetachedから削除します。 パーティション式の設定について詳しくは、パーティション式の指定方法のセクションを参照してください。

ALTER TABLE table_name FORGET PARTITION partition_expr

空のパーティションに関するすべてのメタデータをZooKeeperから削除します。パーティションが空でない場合、または存在しない場合、クエリは失敗します。今後決して使用しないパーティションに対してのみ実行してください。

パーティション式の設定については、パーティション式の指定方法のセクションを参照してください。

例:

ALTER TABLE mt FORGET PARTITION '20201121';

ALTER TABLE table_name ATTACH PARTITION|PART partition_expr

detached ディレクトリからテーブルにデータを追加します。パーティション全体のデータ、または個々のパーツのデータを追加できます。例:

ALTER TABLE visits ATTACH PARTITION 201901;
ALTER TABLE visits ATTACH PART 201901_2_2_0;

パーティション式の設定について詳しくは、パーティション式の指定方法のセクションを参照してください。

このクエリはレプリケートされます。イニシエーターとなるレプリカは、detached ディレクトリにデータがあるかどうかを確認します。 データが存在する場合、クエリはその整合性を検証します。問題がなければ、そのデータをテーブルに追加します。

ATTACH コマンドを受け取った非イニシエーターのレプリカは、自身の detached ディレクトリ内に正しいチェックサムを持つパーツを見つけた場合、他のレプリカから取得することなくそのデータをアタッチします。 正しいチェックサムを持つパーツがない場合、データはそのパーツを持ついずれかのレプリカからダウンロードされます。

1 つのレプリカの detached ディレクトリにデータを配置し、ALTER ... ATTACH クエリを使用して、すべてのレプリカ上のテーブルに追加できます。

ALTER TABLE table2 [ON CLUSTER cluster] ATTACH PARTITION partition_expr FROM table1

このクエリは、データのパーティションを table1 から table2 にコピーします。

注意:

• table1 と table2 のどちらからもデータは削除されません。
• table1 は一時テーブルでもかまいません。

クエリを正常に実行するには、次の条件を満たす必要があります。

• 両方のテーブルの構造が同一である必要があります。
• 両方のテーブルが同じパーティションキー、同じ ORDER BY キー、同じ主キーを持っている必要があります。
• 両方のテーブルが同じストレージポリシーを持っている必要があります。
• 宛先テーブルには、コピー元テーブルのすべての索引とプロジェクションが含まれている必要があります。宛先テーブルで enforce_index_structure_match_on_partition_manipulation 設定が有効になっている場合、索引とプロジェクションは完全に一致している必要があります。そうでない場合、宛先テーブルはコピー元テーブルの索引およびプロジェクションの上位集合を持つことができます。

ALTER TABLE table2 [ON CLUSTER cluster] REPLACE PARTITION partition_expr FROM table1

このクエリは、データのパーティションを table1 から table2 にコピーし、table2 内の既存のパーティションを置き換えます。この操作はアトミックです。

次の点に注意してください。

• table1 からデータが削除されることはありません。
• table1 には一時テーブルを使用できます。

クエリを正常に実行するには、次の条件を満たす必要があります。

• 両方のテーブルが同じ構造である必要があります。
• 両方のテーブルが、同じパーティションキー、同じ ORDER BY キー、および同じ主キーを持っている必要があります。
• 両方のテーブルが同じストレージポリシーを持っている必要があります。
• 宛先テーブルには、ソーステーブルのすべての索引とプロジェクションが含まれている必要があります。宛先テーブルで enforce_index_structure_match_on_partition_manipulation 設定が有効になっている場合、索引とプロジェクションは完全に同一である必要があります。そうでない場合、宛先テーブルはソーステーブルの索引とプロジェクションの上位集合を持つことができます。

ALTER TABLE table_source [ON CLUSTER cluster] MOVE PARTITION partition_expr TO TABLE table_dest

このクエリは、table_source のデータを削除し、データパーティションを table_source から table_dest へ移動します。

このクエリを正常に実行するには、次の条件を満たしている必要があります。

• 両方のテーブルの構造が同一であること。
• 両方のテーブルが同じパーティションキー、同じ ORDER BY キー、および同じ主キーを持つこと。
• 両方のテーブルが同じストレージポリシーを持つこと。
• 両方のテーブルが同じエンジンファミリー (replicated または non-replicated) であること。
• 宛先テーブルに、ソーステーブルのすべての索引とプロジェクションが含まれていること。宛先テーブルで enforce_index_structure_match_on_partition_manipulation 設定が有効になっている場合、索引とプロジェクションは完全に一致している必要があります。そうでない場合、宛先テーブルにはソーステーブルの索引とプロジェクションの上位集合を含めることができます。

ALTER TABLE table_name [ON CLUSTER cluster] CLEAR COLUMN column_name IN PARTITION partition_expr

指定したパーティション内の指定したカラムのすべての値をリセットします。テーブル作成時に DEFAULT 句が定義されている場合、このクエリはカラムの値を指定したデフォルト値に設定します。

例:

ALTER TABLE visits CLEAR COLUMN hour in PARTITION 201902

ALTER TABLE table_name [ON CLUSTER cluster] FREEZE [PARTITION partition_expr] [WITH NAME 'backup_name']

このクエリは、指定したパーティションのローカルバックアップを作成します。PARTITION 句を省略すると、すべてのパーティションのバックアップが一度に作成されます。

旧形式のテーブルでは、パーティション名のプレフィックス (たとえば 2019) を指定できます。その場合、このクエリは対応するすべてのパーティションのバックアップを作成します。パーティション式の設定については、パーティション式の指定方法 の節を参照してください。

実行時には、データのスナップショットを取得するために、このクエリはテーブルデータへのハードリンクを作成します。ハードリンクは /var/lib/clickhouse/shadow/N/... ディレクトリに配置されます。ここで:

• /var/lib/clickhouse/ は、設定ファイルで指定された ClickHouse の作業ディレクトリです。
• N はバックアップの連番です。
• WITH NAME パラメータが指定されている場合は、連番の代わりに 'backup_name' パラメータの値が使用されます。

バックアップ内には、/var/lib/clickhouse/ 配下と同じディレクトリ構造が作成されます。このクエリはすべてのファイルに対して chmod を実行し、それらへの書き込みを禁止します。

バックアップを作成した後、/var/lib/clickhouse/shadow/ からリモートサーバーにデータをコピーし、その後ローカルサーバーから削除できます。ALTER t FREEZE PARTITION クエリはレプリケートされないことに注意してください。ローカルサーバー上にのみローカルバックアップを作成します。

このクエリはバックアップをほぼ瞬時に作成します (ただし最初に、対応するテーブルに対して現在実行中のクエリが終了するのを待ちます) 。

ALTER TABLE t FREEZE PARTITION は、テーブルのメタデータではなくデータのみをコピーします。テーブルのメタデータもバックアップするには、/var/lib/clickhouse/metadata/database/table.sql ファイルをコピーしてください。

バックアップからデータを復元するには、次の手順を実行します。

1. テーブルが存在しない場合は作成します。クエリを確認するには .sql ファイルを使用します (その中の ATTACH を CREATE に置き換えます) 。
2. バックアップ内の data/database/table/ ディレクトリから /var/lib/clickhouse/data/database/table/detached/ ディレクトリにデータをコピーします。
3. ALTER TABLE t ATTACH PARTITION クエリを実行して、データをテーブルに追加します。

バックアップからの復元では、サーバーを停止する必要はありません。

このクエリはパーツを並列に処理し、スレッド数は max_threads 設定によって制御されます。

バックアップとデータの復元について詳しくは、"ClickHouse のバックアップと復元" の節を参照してください。

ALTER TABLE table_name [ON CLUSTER cluster] UNFREEZE [PARTITION 'part_expr'] WITH NAME 'backup_name'

指定した名前のfrozenパーティションをディスクから削除します。PARTITION句を省略すると、すべてのパーティションのバックアップが一度に削除されます。

ALTER TABLE table_name [ON CLUSTER cluster] CLEAR INDEX index_name IN PARTITION partition_expr

このクエリは CLEAR COLUMN と同様に機能しますが、カラムデータではなく索引をリセットします。

ALTER TABLE table_name [ON CLUSTER cluster] FETCH PARTITION|PART partition_expr FROM 'path-in-zookeeper'

別のサーバーからパーティションをダウンロードします。このクエリは、レプリケートテーブルでのみ使用できます。

このクエリでは、次の処理が行われます。

1. 指定した分片からパーティション|パーツ をダウンロードします。'path-in-zookeeper' には、ZooKeeper 内のその分片へのパスを指定する必要があります。
2. 次に、このクエリはダウンロードしたデータを table_name テーブルの detached ディレクトリに配置します。データをテーブルに追加するには、ATTACH PARTITION|PART クエリを使用します。

例:

1. FETCH PARTITION

ALTER TABLE users FETCH PARTITION 201902 FROM '/clickhouse/tables/01-01/visits';
ALTER TABLE users ATTACH PARTITION 201902;

2. FETCH PART

ALTER TABLE users FETCH PART 201901_2_2_0 FROM '/clickhouse/tables/01-01/visits';
ALTER TABLE users ATTACH PART 201901_2_2_0;

次の点に注意してください。

• ALTER ... FETCH PARTITION|PART クエリはレプリケートされません。パーツ またはパーティションは、ローカルサーバー上の detached ディレクトリにのみ配置されます。
• ALTER TABLE ... ATTACH クエリはレプリケートされます。データはすべてのレプリカに追加されます。あるレプリカには detached ディレクトリから追加され、その他のレプリカには近隣のレプリカから追加されます。

ダウンロードの前に、システムはパーティションが存在すること、およびテーブル構造が一致していることを確認します。正常なレプリカの中から、最適なレプリカが自動的に自動選択されます。

このクエリは ALTER TABLE と呼ばれていますが、テーブル構造を変更するわけではなく、テーブルで利用可能なデータも直ちには変更しません。

MergeTree エンジンのテーブルで、パーティションまたはデータパーツを別のボリュームまたはディスクへ移動します。詳しくは、データストレージに複数のブロックデバイスを使用するを参照してください。

ALTER TABLE table_name [ON CLUSTER cluster] MOVE PARTITION|PART partition_expr TO DISK|VOLUME 'disk_name'

ALTER TABLE t MOVE クエリ:

• レプリケートされません。レプリカごとに異なるストレージポリシーを設定できるためです。
• 指定したディスクまたはボリュームが設定されていない場合は、エラーを返します。また、ストレージポリシーで指定されたデータ移動の条件を適用できない場合も、クエリはエラーを返します。
• 移動対象のデータが、バックグラウンドプロセス、同時実行の ALTER TABLE t MOVE クエリ、またはバックグラウンドでのデータマージによってすでに移動されている場合にも、エラーが返されることがあります。この場合、ユーザーが追加の操作を行う必要はありません。

例:

ALTER TABLE hits MOVE PART '20190301_14343_16206_438' TO VOLUME 'slow'
ALTER TABLE hits MOVE PARTITION '2019-09-01' TO DISK 'fast_ssd'

指定したフィルタ式に一致する、指定したパーティション内のデータを変更します。ミューテーションとして実装されています。

構文:

ALTER TABLE [db.]table [ON CLUSTER cluster] UPDATE column1 = expr1 [, ...] [IN PARTITION partition_expr] WHERE filter_expr

-- パーティション名を使用
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION 2 WHERE p = 2;

-- パーティションIDを使用
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION ID '2' WHERE p = 2;

• UPDATE

指定したフィルタ式に一致する、指定したパーティション内のデータを削除します。これはミューテーションとして実装されています。

構文:

ALTER TABLE [db.]table [ON CLUSTER cluster] DELETE [IN PARTITION partition_expr] WHERE filter_expr

-- パーティション名を使用
ALTER TABLE mt DELETE IN PARTITION 2 WHERE p = 2;

-- パーティションIDを使用
ALTER TABLE mt DELETE IN PARTITION ID '2' WHERE p = 2;

これにより、すべての新しい設定を使用してパーツが一から書き直されます。use_const_adaptive_granularity のようなテーブルレベルの設定は、デフォルトでは新たに書き込まれるパーツにしか適用されないため、これは理にかなっています。

ALTER TABLE mt REWRITE PARTS;
ALTER TABLE mt REWRITE PARTS IN PARTITION 2;

• DELETE

ALTER ... PARTITION クエリでは、パーティション式をさまざまな方法で指定できます。

• system.parts テーブルの partition カラムの値として指定します。たとえば、ALTER TABLE visits DETACH PARTITION 201901 です。
• キーワード ALL を使用します。これは DROP/DETACH/ATTACH/ATTACH FROM でのみ使用できます。たとえば、ALTER TABLE visits ATTACH PARTITION ALL です。
• テーブルのパーティションキーのタプルに (型の上で) 一致する、式または定数のタプルとして指定します。パーティションキーが単一要素の場合は、式を tuple (...) 関数で囲む必要があります。たとえば、ALTER TABLE visits DETACH PARTITION tuple(toYYYYMM(toDate('2019-01-25'))) です。
• パーティション ID を使用します。パーティション ID はパーティションの文字列識別子 (可能であれば人が読める形式) で、ファイルシステムおよび ZooKeeper 上でのパーティション名として使用されます。パーティション ID は、PARTITION ID clause で単一引用符付きで指定する必要があります。たとえば、ALTER TABLE visits DETACH PARTITION ID '201901' です。
• ALTER ATTACH PART および DROP DETACHED PART クエリでパーツ名を指定するには、system.detached_parts テーブルの name カラムの値を使った文字列リテラルを使用します。たとえば、ALTER TABLE visits ATTACH PART '201901_1_1_0' です。

パーティションを指定する際に引用符を使うかどうかは、パーティション式の型によって異なります。たとえば、String 型では名前を引用符 (') で囲んで指定する必要があります。Date 型および Int* 型では引用符は不要です。

上記のルールはすべて OPTIMIZE クエリにも当てはまります。パーティション化されていないテーブルを最適化する際に唯一のパーティションを指定する必要がある場合は、式 PARTITION tuple() を設定します。たとえば:

OPTIMIZE TABLE table_not_partitioned PARTITION tuple() FINAL;

IN PARTITION は、ALTER TABLE クエリによって UPDATE または DELETE の式が適用されるパーティションを指定します。新しいパーツは、指定したパーティションからのみ作成されます。このため、テーブルが多数のパーティションに分割されていて、データを個別に更新するだけでよい場合、IN PARTITION は負荷の軽減に役立ちます。

ALTER ... PARTITION クエリの例は、テスト 00502_custom_partitioning_local と 00502_custom_partitioning_replicated_zookeeper に示されています。