Hologres：Compaction

表級參數使用限制

1. 僅Hologres V4.0及以上版本支援本章節所述的表級Compaction參數。低於V4.0的執行個體設定這些參數不會生效，請先升級執行個體。

2. 本章節所述參數僅對列存表和行列共存表生效，其中行列共存表僅列存部分受這些參數控制。對行存表設定這些參數不會產生效果。

3. 絕大多數情境下自動Compaction無需人工幹預。除核心參數online_config_compaction_semaphore外，其餘進階參數與並發參數存在耦合，建議在支援人員指導下用於特定問題的定向處置，處置完成後恢複預設值。

參數設定方式

表級Compaction參數通過SET_TABLE_PROPERTY設定，參數名統一帶online_config_首碼，值統一為字串。設定後對後續調度的Compaction任務生效，運行中的任務不受影響，無需重啟執行個體或重建表。

-- 文法
CALL SET_TABLE_PROPERTY('<SCHEMA_NAME>.<TABLE_NAME>', 'online_config_<PROPERTY_NAME>', '<VALUE>');

-- 樣本：將表public.orders的Compaction並發臨時設定為0（暫停調度新任務）
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '0');

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', 'reset');

SELECT property_key, property_value
FROM hologres.hg_table_properties
WHERE table_namespace = '<SCHEMA_NAME>'
  AND table_name = '<TABLE_NAME>'
  AND property_key LIKE 'online_config_%';

核心參數

online_config_compaction_semaphore

該參數是日常調優的首選參數，控製表的每個資料分區（Tablet）的Compaction並發上限，而不是整張表的總並發。每個資料分區即Compaction的一個調度單元，兩者在本文中指同一對象。一張表在每個Shard上通常有一個或多個分區，例如行列共存表的行存、列存部分是各自獨立的分區，因此整表理論並發上限約為分區總數 × 該參數值，實際還會受Worker級總並發和資源餘量限制。

設定為0的確切語義

• 阻止該表新的Compaction任務執行。

• 不會取消已經在啟動並執行任務，已運行任務會自然執行完畢。

• 該表已被選出、等待執行的任務仍會佔用Worker級總並發額度，因此同時對大量表設定為0會擠占其他表的合并並發。

• 從0恢複為大於0的值後，已在排隊的任務會繼續執行，但尚未被調度的積壓檔案不一定會自動重新觸發合并，尤其是沒有新寫入時，建議恢複後手動執行一次VACUUM（VACUUM的確切語義請參見使用樣本）。

從0恢複並觸發積壓檔案合并的樣本如下：

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '2');
VACUUM public.orders;

邏輯分區表說明

邏輯分區表會根據當前活躍分區數適當調大並發，單個調度單元的並發上限為min(online_config_partition_table_compaction_semaphore_max, active_partition_count × online_config_compaction_semaphore)，預設封頂為8。其中active_partition_count為當前活躍分區數，由系統在運行時統計得出，不是可設定的表屬性。

風險提示

• 不要長期保持為0：檔案數和被刪除資料會持續積壓，查詢效能和儲存空間都會惡化，且積壓越久恢複後的合并壓力越大。

• 不要批量對大量表設定為0或批量調大：所有表共用Worker級總並發，大量設定為0會讓被暫停表的排隊任務佔住全域並發額度，批量調大則容易造成全域排隊和資源衝擊。

• 建議一次只調一張表、一個參數，步長儘可能小，觀察一個業務周期後再進行下一步。

進階參數

以下參數影響Compaction的檔案選擇策略和觸發頻率，與並發參數存在耦合，建議在支援人員指導下使用，處置完成後恢複預設值。

使用樣本

樣本一：大大量匯入前暫停Compaction，匯入後恢複

-- 1. 記錄原狀態（結果為空白表示原本無覆蓋值）
SELECT property_key, property_value FROM hologres.hg_table_properties
WHERE table_namespace = 'public' AND table_name = 'orders'
  AND property_key = 'online_config_compaction_semaphore';

-- 2. 暫停新的Compaction任務
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '0');

-- 3. 執行大量匯入（期間觀察CPU、IO與匯入速度）

-- 4. 恢複：以下兩條二選一，按步驟1的查詢結果選擇
-- 4a. 步驟1結果為空白（原本無覆蓋值）時執行：
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', 'reset');
-- 4b. 步驟1查到原值時，寫回原值（把<ORIGINAL_VALUE>替換為步驟1的property_value）：
-- CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '<ORIGINAL_VALUE>');

-- 5. 觸發積壓檔案合并（建議低峰執行）
VACUUM public.orders;

以下樣本二、樣本三涉及進階參數，建議在支援人員指導下執行，處置完成後恢複預設值。

樣本二：長尾小檔案清理

適用於每層檔案數都小於觸發閾值，合計幾十個小檔案無法合并的情境。

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_ignore_level_compaction', 'true');
VACUUM public.orders;
-- 檔案數收斂後務必改回，否則長期寫入的表會放大Compaction頻率和CPU、IO佔用
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_ignore_level_compaction', 'reset');

樣本三：單分區資料量大、檔案數多，希望合并成更大的檔案

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_orc_max_total_size_to_merge_mb', '512');
VACUUM public.orders;
-- 檔案數收斂後恢複預設值
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_orc_max_total_size_to_merge_mb', 'reset');

注意事項

1. 參數名拼字不做校正：online_config_首碼後接任意名字都能設定成功，SQL不會報錯；寫錯參數名時系統匹配不到對應配置，將靜默無效。因此：

   • 參數名請從本文表格中複製，不要手動輸入。

   • 設定後應通過hologres.hg_table_properties查詢確認已寫入。

   • 應通過觀測手段（如hologres.hg_table_file_status返回的檔案數與檔案大小變化）確認行為確實發生了變化，不要僅憑SQL返回成功判斷生效。

2. 物理分區表：對分區父表執行SET_TABLE_PROPERTY不會作用於已存在的分區子表，屬性唯寫入父表自身，而父表不持有資料，因此對存量分區的Compaction行為無實際效果。父表屬性只會被之後建立的分區子表在建立時一次性拷貝（含動態分區自動建立的子表），父表後續再修改也不會同步到已建子表。調整分區表的Compaction行為時，應直接對目標資料分割子表執行SET_TABLE_PROPERTY並逐個核對子表屬性；若希望未來新分區預設帶上該配置，可同時在父表上設定。

3. 觀測與驗收：調優應有觀測閉環。可通過SELECT * FROM hologres.hg_table_file_status('<SCHEMA_NAME>.<TABLE_NAME>'::regclass);即時查看錶級檔案數與檔案大小（邏輯分區表可使用hologres.hg_partition_file_status按分區查看），通過hologres.hg_table_info（每日產出一次）複盤趨勢。調優驗收的核心判據為：檔案總數下降且平均檔案大小上升。合并過程中舊檔案延遲清理可能造成儲存量短時上升，屬正常現象。

遠端Compaction使用限制

1. 僅Hologres V5.0及以上版本支援遠端Compaction功能。

2. 行存表、列存表和行列共存表均支援配置遠端Compaction，但部分內部Compaction策略不支援卸載，這類Compaction任務仍會在本地執行。

3. 遠端Compaction僅負責Compaction的檔案合并階段，資料讀取和寫入仍在主Warehouse執行。

4. 遠端Compaction執行失敗時，預設不回退到本地執行，Compaction任務直接失敗並由後台調度自動重試。如需開啟失敗回退本地的行為，請設定全域參數enable_compaction_offload_fallback為true。

配置compaction_resource

通過表屬性compaction_resource指定單張表的Compaction任務使用的目標Warehouse。設定後立即生效，無需重啟執行個體。

文法

-- 將表的Compaction卸載到指定Warehouse
CALL SET_TABLE_PROPERTY('<SCHEMA_NAME>.<TABLE_NAME>', 'compaction_resource', '<WAREHOUSE_NAME>');

-- 恢複為本Warehouse執行（預設）
CALL SET_TABLE_PROPERTY('<SCHEMA_NAME>.<TABLE_NAME>', 'compaction_resource', 'local');

使用樣本

-- 將public.orders表的Compaction卸載到名為readonly的Warehouse
CALL SET_TABLE_PROPERTY('public.orders', 'compaction_resource', 'readonly');

-- 查詢當前配置
SELECT property_key, property_value
FROM hologres.hg_table_properties
WHERE table_namespace = 'public'
  AND table_name = 'orders'
  AND property_key = 'compaction_resource';

查詢結果為空白或值為local表示該表使用本地Compaction。

查看Compaction運行狀態

您可以通過hologres.hg_show_compactions()函數查看當前正在運行和已完成的Compaction任務記錄，包括遠端執行的記錄。

-- 查看所有Compaction記錄
SELECT * FROM hologres.hg_show_compactions();

-- 查看遠端執行的Compaction記錄
SELECT table_name, status, compaction_reason, execution_location,
       warehouse_name, start_time, end_time, extended_cost, last_error
FROM hologres.hg_show_compactions()
WHERE execution_location = 'warehouse'
ORDER BY start_time DESC;

返回欄位說明如下。

遠端Compaction使用樣本

以下樣本展示如何將表的Compaction卸載到遠端Warehouse並手動觸發Full Compaction。

-- 1. 確保目標Warehouse已建立
--    （通過控制台或API建立Warehouse，例如名為readonly的Warehouse）

-- 2. 配置表使用遠端Compaction
CALL SET_TABLE_PROPERTY('public.lineitem', 'compaction_resource', 'readonly');

-- 3. 手動觸發Full Compaction（合并階段將在readonly Warehouse上執行）
SELECT hologres.hg_full_compact_table('public.lineitem');

-- 4. 等待Compaction完成
SELECT hologres.hg_wait_table_full_compact('public.lineitem');

-- 5. 查看遠端Compaction執行記錄
SELECT table_name, status, compaction_reason, execution_location,
       warehouse_name, start_time, end_time, extended_cost,
       extended_stats, last_error
FROM hologres.hg_show_compactions()
WHERE table_name = 'lineitem'
  AND execution_location = 'warehouse'
ORDER BY start_time DESC;