Hologres：REBUILD

Format perintah

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

Deskripsi parameter

Jalankan REBUILD pada tabel tanpa binary logging yang diaktifkan

-- Buat tabel dan impor data
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');

-- Tambahkan kolom NOT NULL dan tetapkan nilai default
ASYNC REBUILD TABLE rebuild_test ADD COLUMN c text NOT NULL DEFAULT 'a';

-- Ubah primary key menjadi kolom a
ASYNC REBUILD TABLE rebuild_test ALTER PRIMARY KEY (a);

-- Gunakan sumber daya Serverless untuk menjalankan task Rebuild, tetapkan distribution_key dan clustering_key untuk tabel, dan ubah format penyimpanan menjadi row-column hybrid
ASYNC REBUILD TABLE rebuild_test 
WITH (
    rebuild_guc_hg_computing_resource = 'serverless'
)
SET (
    distribution_key = 'a',
    clustering_key = 'a',
    orientation = 'row,column'
);

-- Konversi tabel non-partisi menjadi tabel partisi logis, tetapkan kunci partisi ke ds, dan tambahkan properti NOT NULL ke kolom ds
ASYNC REBUILD TABLE rebuild_test 
    ALTER COLUMN ds SET NOT NULL,
    TO LOGICAL PARTITION BY LIST(ds);

Jalankan REBUILD pada tabel dengan binary logging yang diaktifkan

REBUILD tidak menyimpan data binary logging historis. Secara default, Anda tidak dapat menjalankan REBUILD pada tabel yang telah mengaktifkan binary logging. Untuk menjalankan task tersebut, Anda harus menentukan parameter binlog_mode dan mengikuti langkah-langkah berikut guna memastikan bahwa client downstream telah sepenuhnya mengonsumsi semua data binary logging historis.

1. Jalankan REBUILD.

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

2. Untuk task REBUILD dengan parameter binlog_mode yang ditetapkan, task tersebut secara otomatis berhenti setelah langkah set_readonly selesai. Anda dapat memeriksa progres menggunakan pernyataan SQL berikut. Pada titik ini, sistem telah menyetel tabel ke status read-only sehingga data tidak dapat ditulis ke tabel dan tidak ada data binary logging baru yang dihasilkan.

   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)

3. Tunggu hingga client downstream selesai mengonsumsi data binary logging yang ada. Kemudian, jalankan secara manual pernyataan SQL berikut untuk melanjutkan task REBUILD. Saat task dilanjutkan, tabel sumber tetap dalam status read-only dan tidak ada data binary logging baru yang dihasilkan.

   RESUME '<query_id>';

   Setelah task REBUILD berhasil dijalankan, binary logging secara otomatis diaktifkan untuk tabel baru. Anda kemudian dapat merestart task konsumsi binary logging downstream dan mulai mengonsumsi log biner tabel baru dari lsn = 0.

Lihat status eksekusi task REBUILD

Task REBUILD dijalankan secara asinkron. Setelah task dikirimkan, sistem mengembalikan status sukses dan query_id. Anda harus melakukan kueri pada tabel sistem hologres.rebuild_progress untuk melihat status subtask asinkron. Tabel dianggap telah direbuild hanya setelah semua subtask berhasil. Perintahnya adalah sebagai berikut:

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

Kolom pada tabel sistem dan deskripsinya adalah sebagai berikut:

Berikut adalah contoh hasilnya:

Hentikan dan mulai ulang tugas REBUILD

• Hentikan task REBUILD asinkron.

  SUSPEND '<query_id>';

• Lanjutkan task asinkron yang dibatalkan oleh CANCEL.

  RESUME '<query_id>';

Penanganan exception task REBUILD

Jika task REBUILD terganggu oleh error atau jika Anda menjalankan perintah SUSPEND secara manual untuk menjeda task, Anda dapat menjalankan perintah RESUME untuk melanjutkan task. Anda juga dapat mengikuti langkah-langkah berikut untuk mengakhiri task dan memulihkan tabel sumber.

• Jalankan perintah berikut untuk membersihkan tabel temporary yang dihasilkan selama proses REBUILD.

  CALL hg_clean_rebuild_tmp_tables('<query_id>');

• Jika tabel sumber telah diatur ke status read-only oleh task REBUILD sebelum task tersebut terganggu, jalankan perintah berikut untuk menghapus status read-only dan melanjutkan operasi tulis.

  ALTER TABLE <table_name> SET (readonly = false);