REBUILD による Hologres テーブルストレージプロパティの変更 - Hologres - Alibaba Cloud - Hologres

構文

ステートメント形式

ASYNC REBUILD TABLE [ IF EXISTS ] <table_name>
    [ WITH ( <rebuild_parameter> [= <value>] [, ... ] )]  
    <action> [, ... ];
WHERE action IS ONE OF:
    ADD [ COLUMN ] <column_name> <data_type> [ column_constraint [ ... ] ]
    ALTER [ COLUMN ] <column_name> [ SET DATA ] TYPE <data_type> [ USING <expression> ]
    ALTER [ COLUMN ] <column_name> SET DEFAULT <expression>
    ALTER [ COLUMN ] <column_name> DROP DEFAULT
    ALTER [ COLUMN ] <column_name> { SET | DROP } NOT NULL
    ALTER PRIMARY KEY (<column_name> [, ...])
    TO [LOGICAL] PARTITION [BY LIST(<column_name> [, <column_name>])]
    SET ( <parameter> [= <value>] [, ... ] )
WHERE rebuild_parameter IS ONE OF:
    keep_source
    binlog_mode
    rebuild_guc_<guc_name> = '<guc_value>'

パラメーター

パラメーター	サブ項目	説明
ASYNC		このステートメントは、REBUILD タスクを非同期で実行することを指定します。タスクの実行後に `query_id` が返されます。`query_id` を使用して、タスクの実行ステータスを監視できます。現在、同期実行はサポートされていません。
table_name		再構築するテーブルの名前です。
column_name		対象テーブルの列名です。
data_type		列のデータ型です。
action	ADD COLUMN	列を追加します。NOT NULL 列の追加やデフォルト値の設定が可能です。
	ALTER COLUMN TYPE	列のデータ型を変更します。
	ALTER COLUMN SET/DROP DEFAULT	列のデフォルト値を設定または削除します。既存データ内の NULL 値は変更されません。
	ALTER COLUMN SET/DROP NOT NULL	列に対する NOT NULL 制約を設定または削除します。
	ALTER PRIMARY KEY	テーブルのプライマリキーを変更します。新しいプライマリキーとデータが競合する場合、非同期実行中にエラーが報告されます。タスクの実行ステータスを速やかに監視する必要があります。
	TO [LOGICAL] PARTITION	テーブルを論理パーティションテーブルまたは物理パーティションテーブルに変換します。以下のシナリオをサポートします。標準テーブルを物理パーティションテーブルに変換します。パーティションキーを指定する必要があります。標準テーブルを論理パーティションテーブルに変換します。パーティションキーを指定する必要があります。物理パーティションテーブルのパーティションキーを変更します。物理パーティションテーブルを論理パーティションテーブルに変換します。パーティションキーの変更は任意です。論理パーティションテーブルを物理パーティションテーブルに変換することはできません。
	SET ( <parameter> [= <value>])	テーブルプロパティを変更します。一般的なシナリオ：分散キー (`distribution_key`) を変更します。セグメントキー (`event_time_column`) を変更します。クラスター化インデックス (`clustering_key`) を変更します。テーブルのストレージ形式 (`orientation`) を変更します。行指向ストレージ、列指向ストレージ、行列ハイブリッドストレージ間で変換できます。テーブルが所属する `table_group` を変更します。その他のすべてのテーブルプロパティも変更可能です。ビットマップインデックス (`bitmap_columns`) または辞書エンコーディング列 (`dictionary_encoding_columns`) を変更する場合は、ALTER TABLE ステートメントを使用してください。REBUILD は不要です。
WITH (<rebuild_parameter> [= <value>])		REBUILD タスク関連のパラメーターを設定します。主なパラメーター： keep_source：値を指定する必要はありません。指定した場合、元のテーブルは削除されず、代わりに `tmp_rebuild_old_<query_id>_<unique_id>_<table_name>` にリネームされます。 binlog_mode：値を指定する必要はありません。Binlog が有効なテーブルを再構築できます。Binlog データの損失を防ぐため、例セクションの手順に従う必要があります。 `rebuild_guc_hg_computing_resource='serverless'`：Serverless リソースを使用して REBUILD タスクを実行します。これによりインスタンスリソースの消費を回避し、タスクの安定性を向上させます。 `rebuild_guc_<guc_name>='<guc_value>'`：他の GUC パラメーターをここで設定できます。詳細については、「GUC パラメーター」をご参照ください。

注意事項

非同期実行 (ASYNC) のみがサポートされており、接続を長時間占有する必要はありません。
REBUILD タスクを送信すると、ステートメントは query_id を返します。この query_id を使用して、REBUILD タスクの実行ステータスを確認できます。送信後すぐに query_id が返されない場合、インスタンス上で多数の非同期タスクが実行中である可能性があります。query_id が返されるのを待ってから、タスクのステータスを確認することを推奨します。
REBUILD 機能を使用してテーブルパラメーターを変更すると、内部でデータが再分散され、コンピューティングリソースを消費します。そのため、業務の安定性を確保するため、業務のオフピーク時間帯に REBUILD タスクを実行するか、Serverless のコンピューティングリソースを使用して実行することを推奨します。
REBUILD タスクの実行中、テーブルは一時的に読み取り専用状態に設定され、書き込みがブロックされます。Hologres V4.1 以降では、REBUILD は増分更新のために Dynamic Table テクノロジーを使用し、読み取り専用期間を大幅に短縮できます。この最適化は、テーブルが次の条件を満たす場合にのみ適用されます。満たさない場合、タスクの実行中はテーブルがタスクの全期間にわたって読み取り専用のままです。
- 再構築前に対象テーブルにプライマリキーが存在し、新しいプライマリキーには元のプライマリキーのすべての列が含まれている必要があります。
- 再構築前に、対象テーブルが列指向ストレージまたは行列ハイブリッドストレージを使用している必要があります。
- 再構築後、対象テーブルに生成列が含まれていてはなりません。
- 再構築前に対象テーブルが物理パーティションテーブルである場合、再構築後もパーティションキーは変更してはなりません。
- 再構築後に対象テーブルが論理パーティションテーブルになる場合、パーティションキーは 1 つのみ指定できます。
オーバーヘッドを抑えるため、複数の変更を 1 つの REBUILD タスクにまとめて実行してください。
物理パーティションテーブルを再構築した後、動的パーティション管理のプロパティは継承されません。タスク完了後に再設定する必要があります。対象となるプロパティは次のとおりです：
- 親パーティションテーブルの auto_partitioning プロパティ。
- keep_alive など、子パーティションのプロパティ。
- 物理パーティションテーブルを再構築した後、子パーティションに個別設定されていたプロパティは継承されません。子パーティションは、bitmap_columns や dictionary_encoding_columns など、親テーブルのすべてのプロパティを継承します。
以下の種類のテーブルでは REBUILD はサポートされません：
- 特定の列プロパティ (JSONB 列の列指向ストレージ最適化など) または列制約 (ベクター列など) を持つテーブル。
- フルテキストインデックスまたはグローバルセカンダリインデックスを持つテーブル。
- Serial または Bigserial データ型の列を含むテーブル。
- Dynamic Table またはマテリアライズドビューに依存するテーブル。標準ビューに依存するテーブルはサポートされています。

例

Binlog がないテーブルの再構築

-- テーブルを作成し、データをインポートします。
CREATE TABLE rebuild_test (
    a TEXT,
    b TEXT,
    ds TEXT
);
INSERT INTO rebuild_test VALUES ('1', '1', '2025-04-01'), ('2', '2', '2025-04-02'), ('3', '3', '2025-04-03');
-- デフォルト値付きの NOT NULL 列を追加します。
ASYNC REBUILD TABLE rebuild_test ADD COLUMN c text NOT NULL DEFAULT 'a';
-- プライマリキーを列 a に変更します。
ASYNC REBUILD TABLE rebuild_test ALTER PRIMARY KEY (a);
-- Serverless リソースを使用して REBUILD タスクを実行し、distribution_key と clustering_key を設定して、行列ハイブリッドストレージに変更します。
ASYNC REBUILD TABLE rebuild_test 
WITH (
    rebuild_guc_hg_computing_resource = 'serverless'
)
SET (
    distribution_key = 'a',
    clustering_key = 'a',
    orientation = 'row,column'
);
-- 非パーティション化テーブルを論理パーティションテーブルに変換し、パーティションキーを ds に設定して、ds 列に NOT NULL 制約を追加します。
ASYNC REBUILD TABLE rebuild_test 
    ALTER COLUMN ds SET NOT NULL,
    TO LOGICAL PARTITION BY LIST(ds);

Binlog があるテーブルの再構築

REBUILD ステートメントは履歴 Binlog データを保持しません。そのため、デフォルトでは Binlog が有効なテーブルに対して REBUILD を実行できません。binlog_mode パラメーターを指定し、以下の手順に従って、ダウンストリームコンシューマーが既存の Binlog データをすべて消費したことを確認する必要があります。

REBUILD ステートメントを実行します。

ASYNC REBUILD TABLE rebuild_test 
WITH (
  binlog_mode
)
<YOUR_ACTION>;

binlog_mode パラメーターを指定した REBUILD タスクの場合、set_readonly ステップの完了後にタスクが自動的に一時停止します。以下の SQL ステートメントを使用して進捗を確認できます。この時点でテーブルは読み取り専用のため、これ以上データを書き込めず、新しい Binlog データも生成されません。

postgres=# SELECT step, status, progress FROM hologres.rebuild_progress('<query_id>');
             step              | status | progress 
-------------------------------+--------+----------
 prepare                       | done   | 1/1
 create_tmp_table              | done   | 1/1
 get_src_table_snapshot        | done   | 1/1
 insert                        | done   | 1/1
 set_readonly                  | done   | 1/1
 check_snapshot                |        | 0/1
 re-insert                     |        | -
 check_additional_child_table  |        | -
 create_additional_child_table |        | -
 insert_additional_child_table |        | -
 swap                          |        | 0/1
(11 rows)

ダウンストリームクライアントが既存の Binlog データの消費を完了するのを待ち、これらのコンシューマータスクを停止します。その後、以下の SQL ステートメントを手動で実行して REBUILD タスクを再開します。
```
RESUME '<query_id>';
```
REBUILD タスクの完了後、新しいテーブルに対して Binlog が自動的に有効化されます。ダウンストリームの Binlog 消費タスクをステートレスに再起動し、新しいテーブルの Binlog を lsn = 0 から消費する必要があります。

通常テーブルからリキッドテーブルへの変換

Hologres V4.2 以降では、REBUILD を使用して通常テーブルをリキッドテーブルに変換することや、リキッドテーブルを通常テーブルに戻すことができます。

--- 通常テーブルをリキッドテーブルに変換します。
ASYNC REBUILD TABLE normal_table 
SET (
  liquid_table = 'true'
);

--- リキッドテーブルを通常テーブルに変換します。
ASYNC REBUILD TABLE liquid_table 
SET (
  liquid_table = 'false'
);

監視と運用

REBUILD タスクの実行ステータスの確認

REBUILD タスクは非同期で実行されます。タスクが正常に送信されると、ステートメントは成功ステータスと query_id を返します。非同期サブタスクのステータスを監視するには、hologres.rebuild_progress システムビューを照会します。すべてのサブタスクが成功した場合にのみ、REBUILD 操作は完了します。以下のコマンドを実行します。

SELECT * FROM hologres.rebuild_progress('<rebuild_query_id>');

次の表では、システムテーブルの列について説明します。

列名	説明
job_name	REBUILD タスクの query_id です。
step_id	ステップ ID です。REBUILD のサブタスクは、step ID の順に実行されます。
step	ステップ名： prepare：タスクの準備を行います。 create_tmp_table：一時テーブルを作成します。 get_src_table_snapshot：元のテーブルのデータスナップショットを取得します。 insert：履歴データを一時テーブルにインポートします。 set_readonly：再構築対象のテーブルを読み取り専用に設定します。これによりデータ書き込みが停止します。 check_snapshot：現在のデータスナップショットが get_src_table_snapshot ステップのスナップショットと一致するかを確認します。一致しない場合は `re-insert` ステップが実行されます。 re-insert：増分データをインポートします。 check_additional_child_table：REBUILD の開始から現在までの間にユーザーが新しい子テーブルを作成したかどうかを確認します。このステップは物理パーティションテーブルにのみ適用されます。 create_additional_child_table：新たに追加された可能性のある子テーブルを、一時テーブル用に作成します。このステップは物理パーティションテーブルにのみ適用されます。 insert_additional_child_table：新しい一時子テーブルに履歴データをインポートします。このステップは物理パーティションテーブルにのみ適用されます。 swap：元のテーブルを一時テーブルに置き換えます。
status	サブタスクのステータスです： done：完了。 doing：実行中。 NULL：このステップの実行が不要である、または現時点では実行が必要かどうかを判定できません。 error：実行に失敗しました。message フィールドのエラーメッセージを確認してください。
progress	サブタスクの進捗です。`m/n` 形式で表示され、m は完了したサブステップ数、n は総数です。総数 (n) は、テーブルパーティション数に対応することが多いです。
start_time	サブタスクの開始時刻です。
end_time	サブタスクの終了時刻です。
queryid	サブタスクの query_id です。
pid	サービスプロセス ID です。
message	サブタスクのメッセージです。サブタスクでエラーが発生した場合、このフィールドにエラーメッセージが記録されます。

REBUILD タスクの停止と再開

REBUILD の非同期タスクを一時停止します。
```
SUSPEND '<query_id>';
```
CANCEL とマークされた非同期タスクを再開します。
```
RESUME '<query_id>';
```

REBUILD タスクの例外処理

REBUILD タスクがエラーで中断された場合、または手動で一時停止した場合は、RESUME コマンドで再開するか、タスクを終了して以下の手順でクリーンアップできます。

以下のコマンドを実行し、REBUILD プロセス中に作成された一時テーブルをクリーンアップします。
```
CALL hg_clean_rebuild_tmp_tables('<query_id>');
```
テーブルが読み取り専用に設定されている場合は、適切なコマンドを実行して書き込みアクセスを復元します。
- Hologres V4.1 より前のバージョンの場合は、以下のコマンドを実行します。
```
ALTER TABLE <table_name> SET (readonly = false);
```
- Hologres V4.1 以降の場合は、以下のコマンドを実行します。
```
ALTER TABLE <table_name> RESET (ddl_options,write_options);
```