CREATE LOGICAL PARTITION TABLE - Hologres

Hologres自V3.1版本起支援邏輯分區表（LOGICAL PARTITION TABLE），即父表屬於物理表，而子表為邏輯概念。本文介紹CREATE LOGICAL PARTITION TABLE的用法。

使用限制

僅Hologres V3.1及以上版本的執行個體支援邏輯分區表。
邏輯分區表僅支援LIST分區，支援選擇不超過兩列的分區鍵。
邏輯分區表的分區鍵支援的類型為：INT、TEXT、VARCHAR、DATE、TIMESTAMP、TIMESTAMPTZ。
邏輯分區表的分區鍵需要設為非空（NOT NULL）屬性。
邏輯分區表的分區鍵支援產生列。
邏輯分區表單表支援的分區數量上限為5200個，資料庫支援的邏輯分區總數上限為20萬個。
由於邏輯分區表寫入資料時會自動建立對應分區，存在以下限制與建議：
- 建議最佳化資料寫入任務和資料品質，儘可能避免髒資料（如按天分區時避免有非00:00:00時刻的資料出現），以免分區數量過度膨脹。
- 建議按分區串列寫入，避免同時寫入過多分區。
- 單表的匯入任務有如下限制：
  - 大量匯入時，單個匯入任務支援匯入的分區數上限為50個，超出將報錯Bulkload partition count exceed limit, partition count is xxx, limit is xxx。
  - 通過Fixed Plan匯入時，單表同時寫入的分區數超過30時，新的寫入分區請求將觸發流控，等待若干秒後自動認可
  - 通過Fixed Plan匯入時，單表同時寫入的分區數超過100時，新的寫入分區請求將報錯mem partition count exceed reject limit。
- 執行個體/計算群組層級有如下流控機制：
  - 每分鐘建立分區數超過50時，新的建立分區請求將觸發流控，等待若干秒後自動認可。
  - 每分鐘建立分區數超過100時，新的建立分區請求將報錯mem partition count exceed reject limit。
  - 記憶體表中，通過Fixed Plan同時寫入的分區總數（單表寫入分區數 * Shard數 / Worker數，行列共存表需要再乘2，按表求和）達到500時，新的寫入分區請求將觸發流控，等待若干秒後自動認可。
  - 記憶體表中，通過Fixed Plan同時寫入的分區總數（單表寫入分區數 * Shard數 / Worker數，行列共存表需要再乘2，按表求和）達到5000時，新的寫入分區請求將報錯mem partition count exceed reject limit。

注意事項

不建議單分區資料量過小（如小於1億條），否則查詢加速效果不明顯，且更容易產生較多小檔案。可以選擇更大粒度的分區。
如果您需要經常對某分區資料進行整體替換，包括執行TRUNCATE操作或INSERT OVERWRITE操作，建議使用分區表，效果更好，且可以避免大範圍的刪除操作。
TRUNCATE操作不支援產生Binlog，您需要在Session層級執行SET hg_experimental_generate_binlog = off命令。
邏輯分區表無需手動建立分區，其分區是否存在取決於分區中是否有資料。當分區中資料均被刪除後，分區自動刪除。
說明
由於Hologres的資料清理為非同步作業，因此分區也會非同步刪除。
如需修改邏輯分區表的表屬性，建議使用REBUILD文法，後台會自動將任務進行拆分，並按分區串列執行。其中，如需對邏輯分區表執行Resharding操作（即修改表的Table Group），請勿使用原HG_MOVE_TABLE_TO_TABLE_GROUP預存程序，詳情請參見Table Group與Shard Count操作指南。

建立邏輯分區表

命令格式

說明

邏輯分區表擁有哪些分區，由表中的資料決定。因此，您無需手動建立或刪除分區。

-- 建立邏輯分區父表語句
CREATE TABLE [IF NOT EXISTS] [<schema_name>.]<table_name>  ([
  {
   <column_name> <column_type> [ <column_constraints>, [...]]
   | <table_constraints>
   [, ...]
  }
])
LOGICAL PARTITION BY LIST(<partition_column_1> [, <partition_column_2>])
[WITH(
  <property_name> = <property_value>
 [, ...]
)];

參數說明

參數名	描述
schema_name	表所在的Schema名稱。若是在同一個Schema下建立父表和子表，可以無需指定Schema名稱。若是跨Schema建立父表和子表，則需要指定Schema名稱。
table_name	需要建立的分區父表的名稱。
column_name	新表中要建立的欄位名。
column_type	欄位的資料類型。
column_constraints	列約束的名稱。
table_constraints	資料表條件約束的名稱。
partition_column	邏輯分區表的分區鍵，支援設定1或2個。
property_name	需要對邏輯分區表設定的表屬性名稱。
property_value	表屬性設定的值。

表屬性說明

邏輯分區父表支援如下表屬性。

說明

由於邏輯分區表的父表為物理表，分區僅為邏輯概念，因此不支援為分區單獨設定下列表屬性。

表屬性	說明
partition_expiration_time	分區到期時間長度，到期後分區資料會非同步清理。預設無到期時間長度，資料不自動清理。可設`'30 day'`、`'12 month'`等，建議該參數時間單位與分區鍵單位一致。說明僅支援單個分區鍵，且僅對時間類型的分區鍵生效。
partition_keep_hot_window	分區資料保持熱存的時間長度，到期後分區資料會非同步轉為冷存。冷存及熱存詳情請參見資料階層式存放區。預設資料全為熱儲存，不自動轉冷。可設`'30 day'`、`'12 month'`等，建議該參數時間單位與分區鍵單位一致。說明僅支援單個分區鍵，且僅對時間類型的分區鍵生效。
partition_require_filter	查詢父表時是否需要分區過濾條件。取值如下： `TRUE`：要求分區過濾條件，否則報錯。 `FALSE`（預設值）：不要求分區過濾條件，可以直接查詢父表。
binlog_level	父表是否開啟Binlog。Binlog功能詳情請參見訂閱Hologres Binlog。取值如下： `'none'`（預設值）：不開啟Binlog。 `'replica'`：開啟Binlog。
binlog_ttl	Binlog資料生命週期，單位為秒。預設值為2592000（即30天）。
partition_generate_binlog_window	父表資料產生Binlog的時間視窗，僅在“目前時間-該參數值”範圍內的分區資料會產生Binlog。預設不設時間視窗，即父表的全部資料都產生Binlog。可設`'3 day'`、`'12 hour'`等，建議該參數時間單位與分區鍵單位一致。說明僅支援單個分區鍵，且僅對時間類型的分區鍵生效。
索引等其他重要屬性	邏輯分區表同樣支援distribution_key、clustering_key等索引，以及orientation、time_to_live_in_seconds等其他重要屬性。屬性詳情請參見CREATE TABLE。您可參考情境化建表調優指南中列舉的情境為索引類的表屬性設定合適的值。邏輯分區表不支援原物理分區表的動態分區管理屬性，詳情請參見動態分區管理。

分區屬性說明

邏輯分區表的分區支援如下分區屬性，您可通過ALTER LOGICAL PARTITION TABLE修改分區屬性。

分區屬性	說明
keep_alive	分區是否自動清理。取值如下： TRUE：不自動清理，即不受父表的partition_expiration_time參數影響。 FALSE（預設值）：受父表的partition_expiration_time參數影響，到期自動清理。僅父表設定了partition_expiration_time參數時生效。
storage_mode	分區是否保持某種儲存類型。預設不設定，不設定時會受父表的partition_keep_hot_window參數控制。取值如下： 'hot'：分區儲存類型保持熱存，不受父表的partition_keep_hot_window參數控制。 'cold'：分區儲存類型保持冷存，不受父表的partition_keep_hot_window參數控制。
generate_binlog	分區是否產生Binlog。預設不設定，不設定時會受父表的partition_generate_binlog_window參數控制。取值如下： 'on'：分區會產生Binlog，不受父表的partition_generate_binlog_window參數控制。 'off'：分區不會產生Binlog，不受父表的partition_generate_binlog_window參數控制。

使用樣本

將普通列ds設定為分區鍵。

CREATE TABLE public.hologres_logical_parent_1 (
    a TEXT,
    b INT,
    c TIMESTAMP,
    ds DATE NOT NULL,
    PRIMARY KEY (b, ds)) 
LOGICAL PARTITION BY LIST (ds) 
WITH (
    orientation = 'column',
    distribution_key = 'b',
    partition_expiration_time = '30 day', 
    partition_keep_hot_window = '15 day', 
    partition_require_filter = TRUE,
    binlog_level = 'replica',
    partition_generate_binlog_window = '3 day'
);

將產生列ds設定為分區鍵。

CREATE TABLE public.hologres_logical_parent_2 (
    a TEXT,
    b INT,
    c TIMESTAMP,
    ds TIMESTAMP GENERATED ALWAYS AS (date_trunc('day', c)) STORED NOT NULL,
    PRIMARY KEY (b, ds)) 
LOGICAL PARTITION BY LIST (ds) 
WITH (
    orientation = 'column',
    distribution_key = 'b',
    partition_expiration_time = '30 day', 
    partition_keep_hot_window = '15 day', 
    partition_require_filter = TRUE,
    binlog_level = 'replica',
    partition_generate_binlog_window = '3 day'
);

設定兩列分區鍵。

CREATE TABLE public.hologres_logical_parent_3 (
    a TEXT,
    b INT,
    yy TEXT NOT NULL,
    mm TEXT NOT NULL)
LOGICAL PARTITION BY LIST (yy, mm) 
WITH (
    orientation = 'column',
    distribution_key = 'b',
    partition_require_filter = TRUE
);

邏輯分區表資料管理

對邏輯分區表進行資料管理時，會產生如下鎖：

指定分區大量匯入/更新、指定分區Truncate：分區鎖，不影響其他分區的資料管理。
不指定分區大量匯入/更新、不指定分區Truncate、任意Delete：表鎖，其他資料管理操作需等鎖。
通過Fixed Plan的資料寫入/更新/刪除：行鎖，會和分區或表的大量匯入/更新/刪除互相影響，不影響其他通過Fixed Plan的資料寫入/更新/刪除。

父表資料管理

針對邏輯分區表的父表，資料寫入、更新、清理等操作與普通表完全相同。Hologres儲存引擎會根據分區資料情況自動新增或清理對應分區。

寫入資料至父表。

INSERT INTO public.hologres_logical_parent_2 
VALUES 
    ('a', 1, '2025-03-16 10:00:00'), 
    ('b', 2, '2025-03-17 11:00:00'), 
    ('c', 3, '2025-03-18 12:00:00'), 
    ('d', 4, '2025-03-19 13:00:00'), 
    ('e', 5, '2025-03-20 14:00:00');

清理父表資料。

-- 使用DELETE命令清理
DELETE FROM public.hologres_logical_parent_2 WHERE ds = '2025-03-20';

-- 使用TRUNCATE命令清理
SET hg_experimental_generate_binlog = off;
TRUNCATE public.hologres_logical_parent_2;

分區資料管理

邏輯分區表也支援指定分區進行資料管理操作。

匯入資料至邏輯分區。如果待匯入的資料與指定的分區不匹配，則忽略不符合指定分區的資料。

-- 指定分區並匯入
INSERT INTO public.hologres_logical_parent_1 
PARTITION (ds = '2025-03-16')
VALUES 
    ('a', 1, '2025-03-16 10:00:00', '2025-03-16');

-- 資料與分區不匹配時，不符合指定分區的資料不寫入，不產生報錯
INSERT INTO public.hologres_logical_parent_1 
PARTITION (ds = '2025-03-16')
VALUES 
    ('a', 3, '2025-03-16 10:00:00', '2025-03-16'), 
    ('b', 2, '2025-03-17 11:00:00', '2025-03-17');

清理分區資料。

計算群組DML自動路由功能暫不支援自動路由指定分區的TRUNCATE，需要使用主（Leader）計算群組執行。

-- 使用DELETE命令清理
DELETE FROM public.hologres_logical_parent_1 WHERE ds = '2025-03-16' or ds = '2025-03-17';

-- 使用TRUNCATE命令清理
SET hg_experimental_generate_binlog = off;
TRUNCATE public.hologres_logical_parent_1 PARTITION (ds = '2025-03-16') PARTITION (ds = '2025-03-17');

INSERT OVERWRITE覆寫分區。
Hologres V3.1版本起支援原生INSERT OVERWRITE文法，支援對邏輯分區表執行INSERT OVERWRITE操作。詳情請參見INSERT OVERWRITE。
重要
INSERT OVERWRITE任務為同步任務，若同時指定多個邏輯分區，則多個分區的INSERT OVERWRITE任務會平行處理，導致CPU和記憶體壓力大。如果需要指定多個邏輯分區進行INSERT OVERWRITE操作，建議按分區拆成多個任務，並進行串列處理。

邏輯分區表查詢

與物理分區表不同的是，邏輯分區表支援配置partition_require_filter屬性，如果該屬性配置為TRUE，則該邏輯分區表在查詢時，查詢語句必須包含分區過濾條件。

包含分區過濾條件的邏輯分區表查詢。

SELECT * FROM public.hologres_logical_parent_1 WHERE ds = '2025-03-16';

不含分區過濾條件的邏輯分區表查詢，要求父表的partition_require_filter屬性為FALSE。
```
SELECT * FROM public.hologres_logical_parent_1;
```

其他動作

Hologres提供如下系統資料表或系統函數，用於查詢邏輯分區表的中繼資料資訊。

hologres.hg_list_logical_partition('<table_name>')：列出邏輯分區表的所有分區。
hologres.hg_logical_partitioned_table_properties：當前執行個體下的所有邏輯分區及對應分區屬性配置。
hologres.hg_partition_file_status('<table_name>')：Hologres V3.1.4版本起，支援查詢邏輯分區表中所有分區的熱存及冷存的儲存量。

使用樣本：

查看錶的所有邏輯分區。

SELECT * FROM hologres.hg_list_logical_partition ('<schema_name>.<table_name>');

查看錶的所有邏輯分區屬性配置。

注意：此處僅顯示子分區和父表不一致的配置，如果返回結果為空白，表示子分區沒有特殊配置

SELECT
    *
FROM
    hologres.hg_logical_partitioned_table_properties
WHERE 
    table_namespace = '<schema_name>'
    AND table_name = '<table_name>'
ORDER BY partition DESC;

查看錶中所有邏輯分區當前的冷熱儲存量。

SELECT * FROM hologres.hg_partition_file_status ('<schema_name>.<table_name>');

除上述系統資料表外，邏輯分區作為物理表，也可相容其他Hologres系統資料表，相容普通表的中繼資料查詢方式。使用樣本如下：

查看邏輯分區表的DDL。

SELECT hg_dump_script('<schema_name>.<table_name>');

查看邏輯分區表的父表屬性。

SELECT
    *
FROM
    hologres.hg_table_properties
WHERE 
    table_namespace = '<schema_name>'
    AND table_name = '<table_name>';

查看邏輯分區表的最大分區。
說明
由於邏輯分區表的資料清理和分區清理為非同步作業，因此如果您的最大分區資料需要被清空，推薦使用INSERT OVERWRITE進行資料刪除操作，否則可能導致MAX_PT函數的結果不正確。
```
SELECT MAX_PT('<schema_name>.<table_name>');
```

Hologres：CREATE LOGICAL PARTITION TABLE