文档首页/ 云数据库 GaussDB/ 参考（分布式_V2.0-10.x）/ SQL参考/ 函数和操作符/ 系统管理函数/ HTAP系统函数

更新时间：2026-10-21 GMT+08:00

HTAP系统函数

gs_global_imcv_info()

描述：该函数用于显示当前数据库内IMCV表的基本信息，例如列存数据的加载情况、内存/磁盘空间占用等。分布式下仅支持在CN节点执行，结果返回所有DN节点的IMCV表的基本信息。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员才有权限执行此函数。

表1 gs_global_imcv_info参数说明
参数	参数	类型	描述
输出参数	node_name	text	节点名。
输出参数	rel_name	name	表名。
输出参数	partition_name	name	一级分区名。
输出参数	subpartition_name	name	二级分区名。
输出参数	schema_name	name	Schema名。
输出参数	user_name	name	用户名。
输出参数	imcvnattr	smallint	加载列数量。
输出参数	imcvkey	int2vector	加载的列数组。
输出参数	priority	smallint	加载优先级（目前优先级暂不生效）。 '1'：PRIORITY_NONE无优先级。 '2'：PRIORITY_LOW低优先级。 '3'：PRIORITY_HIGH高优先级。
输出参数	rowgroup_num	integer	预期的行组数（即完全加载后应有的行组数）。
输出参数	populated_rowgroup_num	integer	实际加载的行组数（完全加载后该值应等于rowgroup_num）。
输出参数	cu_num_in_mem	integer	内存中的IMCU数量。
输出参数	cu_mem_size	bigint	IMCU占用的内存大小，单位为字节。
输出参数	cu_num_in_disk	integer	磁盘中的IMCU数量。
输出参数	cu_disk_size	bigint	IMCU占用的磁盘大小，单位为字节。

示例

htapdb=# SELECT * FROM gs_global_imcv_info();
  node_name   |         rel_name         |       partition_name        | subpartition_name | schema_name | user_name | imcvnattr |   imcvkey   | priority | rowgroup_num | populated_rowgroup_num | cu_num_in_mem | cu_mem_size | cu_num_in_disk | cu_disk_size 
--------------+--------------------------+-----------------------------+-------------------+-------------+-----------+-----------+-------------+----------+--------------+------------------------+---------------+-------------+----------------+--------------
 dn_6003_6004 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      | ***       |         6 | 1 2 3 4 5 6 |        1 |            1 |                      1 |             7 |       24228 |              0 |            0
 dn_6003_6004 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      | ***       |         6 | 1 2 3 4 5 6 |        1 |            1 |                      1 |             7 |        8048 |              0 |            0
 dn_6003_6004 | htap_flush_by_name_part1 |                             |                   | public      | ***       |         6 | 1 2 3 4 5 6 |        1 |            0 |                      0 |             0 |           0 |              0 |            0
 dn_6001_6002 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      | ***       |         6 | 1 2 3 4 5 6 |        1 |            0 |                      0 |             0 |           0 |              0 |            0
 dn_6001_6002 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      | ***       |         6 | 1 2 3 4 5 6 |        1 |            1 |                      1 |             7 |        8048 |              0 |            0
 dn_6001_6002 | htap_flush_by_name_part1 |                             |                   | public      | ***       |         6 | 1 2 3 4 5 6 |        1 |            0 |                      0 |             0 |           0 |              0 |            0
(6 rows)

gs_htap_imcv_info()

描述：该函数用于显示当前数据库内IMCV表的基本信息，例如列存数据的加载情况、内存/磁盘空间占用等。分布式下执行该函数返回当前节点的信息，查询所有节点信息可使用gs_global_imcv_info()函数。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或者运维管理人员才有权限执行此函数。

表2 gs_htap_imcv_info参数说明
参数	参数	类型	描述
输出参数	relname	name	表名。
输出参数	partition_name	name	一级分区名。
输出参数	subpartition_name	name	二级分区名。
输出参数	schema_name	name	Schema的名字。
输出参数	user_name	name	用户名。
输出参数	imcvnattr	smallint	加载列数量。
输出参数	imcvkey	int2vector	加载的列数组。
输出参数	priority	smallint	加载优先级。（目前优先级暂不生效） '1'：PRIORITY_NONE无优先级。 '2'：PRIORITY_LOW低优先级。 '3'：PRIORITY_HIGH高优先级。
输出参数	rowgroup_num	integer	预期的行组数（即完全加载后应有的行组数）。
输出参数	populated_rowgroup_num	integer	实际加载的行组数（完全加载后该值应等于rowgroup_num）。
输出参数	cu_num_in_mem	integer	内存中的IMCU数量。
输出参数	cu_mem_size	bigint	IMCU占用的内存大小，单位为字节。
输出参数	cu_num_in_disk	integer	磁盘中的IMCU数量。
输出参数	cu_disk_size	bigint	IMCU占用的磁盘大小，单位为字节。

示例：

htapdb=# SELECT * FROM gs_htap_imcv_info();
         rel_name         |       partition_name        | subpartition_name | schema_name | user_name | imcvnattr |   imcvkey   | priority | rowgroup_num | populated_rowgroup_num | cu_num_in_mem | cu_mem_size | cu_num_in_disk | cu_disk_size 
--------------------------+-----------------------------+-------------------+-------------+-----------+-----------+-------------+----------+--------------+------------------------+---------------+-------------+----------------+--------------
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      | ***       |         6 | 1 2 3 4 5 6 |        1 |            0 |                      0 |             0 |           0 |              0 |            0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      | ***       |         6 | 1 2 3 4 5 6 |        1 |            0 |                      0 |             0 |           0 |              0 |            0
 htap_flush_by_name_part1 |                             |                   | public      | ***       |         6 | 1 2 3 4 5 6 |        1 |            0 |                      0 |             0 |           0 |              0 |            0
(3 rows)

gs_imcv_flush(reloid oid, partoid oid, parallelism integer, rebuild_mode integer)

描述：对数据库中指定的IMCV表或者分区立即进行一次重建，并显示重建的结果。重建过程将刷新IMCV表，移除旧数据并同步当前表的非活跃数据。在CN节点执行时，重建所有节点上该表的IMCV；在DN节点执行时，重建该节点上该表的IMCV。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或运维管理员才有权限执行此函数。
该函数不允许在事务块内执行。
在执行并行加载/重建时，每个worker都会额外占用内存、CPU和I/O（开启落盘）等资源，请根据实际硬件资源、系统负载谨慎控制加载或重建的并行度。

表3 gs_imcv_flush参数说明
参数类型	参数名	类型	描述
输入参数	reloid	oid	表oid。
输入参数	partoid	oid	分区oid。当查询分区表所有分区或非分区表时，该值可传入0。
输入参数	parallelism	integer	并行度。即加载/重建任务利用的bgworker数量。取值范围为1~256。实际后台bgworker数量不足时，使用实际能够拉起的bgworker执行重建任务。
输入参数	rebuild_mode	integer	重建模式。取值范围： 0：表示非强制重建，仅当列存数据未同步到行存时会触发重建。 1：表示强制重建，即无论列存数据是否为最新状态，都会触发重建。
输出参数	total	integer	实际处理的行组数。
输出参数	success	integer	成功处理的行组数。
输出参数	error	integer	处理失败的行组数，例如因为内存不足，未实际发生加载或者重建操作。
输出参数	skip	integer	跳过处理的行组数，例如数据足够新鲜，未发生重建操作。

示例：

htapdb=# SELECT * FROM gs_imcv_flush(20834, 20838,1,1);
 total | success | error | skip 
-------+---------+-------+------
 1     | 1       | 0     | 0
(1 row)

gs_imcv_flush(relname text, partname text, parallelism integer, rebuild_mode integer)

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或运维管理员才有权限执行此函数。
该函数不允许在事务块内执行。
在执行并行加载/重建时，每个worker都会额外占用内存、CPU和I/O（开启落盘）等资源，请根据实际硬件资源、系统负载谨慎控制加载或重建的并行度。

表4 gs_imcv_flush参数说明
参数类型	参数名	类型	描述
输入参数	relname	text	表名。
输入参数	partname	text	分区名。查询分区表所有分区或非分区表时，该值可传入NULL或者''。可缺省，缺省时如果表包含分区，则处理所有分区。
输入参数	parallelism	integer	并行度。即加载/重建任务利用的bgworker数量。取值范围为1~256。实际后台bgworker数量不足时，使用实际能够拉起的bgworker执行重建任务。可缺省，缺省时默认并行度为1，即无并行。
输入参数	rebuild_mode	integer	重建模式。取值范围： 0：表示非强制重建，仅当列存数据未同步到行存时会触发重建。 1：表示强制重建，即列存数据是否新鲜都会触发重建。可缺省，缺省时代表非强制重建。
输出参数	total	integer	实际处理的行组数。
输出参数	success	integer	成功处理的行组数。
输出参数	error	integer	处理失败的行组数，例如因为内存不足，未实际发生加载或者重建操作。
输出参数	skip	integer	跳过处理的行组数，例如数据足够新鲜，未发生重建操作。

示例：

--缺省partname、parallelism、rebuild_mode。
htapdb=# SELECT * FROM gs_imcv_flush('htap_flush_by_name_part1');
 total | success | error | skip 
-------+---------+-------+------
 2     | 2       | 0     | 0
(1 row)
--缺省parallelism、rebuild_mode。
htapdb=# SELECT * FROM gs_imcv_flush('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p1');
 total | success | error | skip 
-------+---------+-------+------
 1     | 0       | 0     | 1
(1 row)
--缺省rebuild_mode。
htapdb=# SELECT * FROM gs_imcv_flush('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p1',1);
 total | success | error | skip 
-------+---------+-------+------
 1     | 0       | 0     | 1
(1 row)
htapdb=# SELECT * FROM gs_imcv_flush('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p1',1,1);
 total | success | error | skip 
-------+---------+-------+------
 1     | 1       | 0     | 0
(1 row)

gs_global_htap_tmu_data(relname text, partname text, rowgroup_id integer)

描述：查看实时事务单元TMU中的活跃事务数据，只能在分布式CN下执行，返回所有DN节点的信息。当rowgroup_id为0时，返回表中所有活跃事务数据；当rowgroup_id>0时，返回表中指定行组中的活跃事务数据。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员才有权限执行此函数。

表5 gs_global_htap_tmu_data参数说明
参数类型	参数名	类型	描述
输入参数	relname	text	表名。如果查询跨Schema的表信息，支持传入'schema.relname'形式。
输入参数	partname	text	分区名。查询分区表所有分区或非分区表时，该值可传入NULL或者''。
输入参数	rowgroup_id	integer	行组唯一标识。
输出参数	node_name	text	节点名。
输出参数	rel_name	name	表名。
输出参数	partition_name	name	一级分区名，如果非一级分区，该字段为空。
输出参数	subpartition_name	name	二级分区名，如果非二级分区，该字段为空。
输出参数	schema_name	name	Schema名。
输出参数	rel_oid	oid	表oid。
输出参数	rowgroup_id	integer	行组唯一标识。
输出参数	page_id	integer	所查行组中页面id。
输出参数	flag	smallint	0代表非脏页，1代表脏页。
输出参数	xid	xid	操作该数据的事务id。

示例：

htapdb=# SELECT * FROM gs_global_htap_tmu_data('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p1', 0);
 node_name |         rel_name         |       partition_name        | subpartition_name | schema_name | rel_oid | rowgroup_id | page_id | flag |  xid   
-----------+--------------------------+-----------------------------+-------------------+-------------+---------+-------------+---------+------+--------
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      |   16389 |           1 |       0 |    0 | 203236
(1 row)

gs_htap_tmu_data(relname text, partname text, rowgroup_id integer)

描述：查看实时事务单元TMU中的活跃事务数据，返回当前节点表中活跃事务数据。当rowgroup_id为0时，返回表中所有活跃事务数据；当rowgroup_id>0时，返回表中指定行组的活跃事务数据。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或运维管理员才有权限执行此函数。

表6 gs_htap_tmu_data参数说明
参数类型	参数名	类型	描述
输入参数	relname	text	表名。如果查询跨Schema的表信息，支持传入'schema.relname'形式。
输入参数	partname	text	分区名。查询分区表所有分区或非分区表时，该值可传入NULL或者''。
输入参数	rowgroup_id	integer	行组唯一标识。
输出参数	rel_name	name	表名。
输出参数	partition_name	name	一级分区名，如果非一级分区，该字段为空。
输出参数	subpartition_name	name	二级分区名，如果非二级分区，该字段为空。
输出参数	schema_name	name	Schema名。
输出参数	rel_oid	oid	表oid。
输出参数	rowgroup_id	integer	行组唯一标识。
输出参数	page_id	integer	所查行组中页面id。
输出参数	flag	smallint	0代表非脏页，1代表脏页。
输出参数	xid	xid	操作该数据的事务id。

示例：

htapdb=# SELECT * FROM gs_htap_tmu_data('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p2',0);
         rel_name         |       partition_name        | subpartition_name | schema_name | rel_oid | rowgroup_id | page_id | flag | xid 
--------------------------+-----------------------------+-------------------+-------------+---------+-------------+---------+------+-----
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |   16390 |           1 |       0 |    0 |   0
(1 row)

gs_global_htap_tmu_chunk_meta(relname name, partname name, rowgroup_id integer)

描述：查看实时事务单元TMU元数据信息，只能在分布式CN下执行，返回所有DN节点的信息。当rowgroup_id为0时，返回所有行组中的实时事务单元TMU数据信息；当rowgroup_id>0时，返回表中指定行组中的实时事务单元TMU数据信息；当rowgroup_id为-1时，统计所有行组中的实时事务单元TMU数据后以单条返回。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员才有权限执行此函数。

表7 gs_global_htap_tmu_chunk_meta参数说明
参数类型	参数名	类型	描述
输入参数	relname	text	表名。如果查询跨Schema的表信息，支持传入'schema.relname'形式。
输入参数	partname	text	分区名。查询分区表所有分区或非分区表时，该值可传入NULL或者''。
输入参数	rowgroup_id	integer	行组唯一标识。
输出参数	node_name	text	数据库节点名。
输出参数	rel_name	name	表名。
输出参数	partition_name	name	一级分区名，如果非一级分区，该字段为空。
输出参数	subpartition_name	name	二级分区名，如果非二级分区，该字段为空。
输出参数	schema_name	name	Schema名。
输出参数	rel_oid	oid	表oid。
输出参数	rowgroup_id	integer	行组唯一标识。
输出参数	page_count	bigint unsigned	所查行组中页面数量。
输出参数	dirty_page_count	bigint unsigned	所查行组中脏页面数量。
输出参数	clean_page_count	bigint unsigned	所查行组中非脏页面数量。
输出参数	dirty_ratio	real	所查行组中脏页占全部页面数量比例。

示例：

htapdb=# SELECT * FROM gs_global_htap_tmu_chunk_meta('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p2', 0);
 node_name |         rel_name         |       partition_name        | subpartition_name | schema_name | rel_oid | rowgroup_id | page_count | dirty_page_count | clean_page_count | dirty_ratio 
-----------+--------------------------+-----------------------------+-------------------+-------------+---------+-------------+------------+------------------+------------------+-------------
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |   16390 |           1 |          1 |                0 |                1 |           0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |   16390 |           1 |          1 |                0 |                1 |           0
(2 rows)

gs_htap_tmu_chunk_meta(relname text, partname text, rowgroup_id integer)

描述：查看实时事务单元TMU元数据信息，分布式下执行返回当前节点的信息。当rowgroup_id为0时，返回所有行组中的实时事务单元TMU数据信息；当rowgroup_id>0时，返回表中指定行组中的实时事务单元TMU数据信息；当rowgroup_id为-1时，统计所有行组中的实时事务单元TMU数据后以单条返回。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或者运维管理人员才有权限执行此函数。

表8 gs_htap_tmu_chunk_meta参数说明
参数类型	参数名	类型	描述
输入参数	relname	text	表名。如果查询跨Schema的表信息，支持传入'schema.relname'形式。
输入参数	partname	text	分区名。查询分区表所有分区或非分区表时，该值可传入NULL或者''。
输入参数	rowgroup_id	integer	行组唯一标识。
输出参数	rel_name	name	表名。
输出参数	partition_name	name	一级分区名，如果非一级分区，该字段为空。
输出参数	subpartition_name	name	二级分区名，如果非二级分区，该字段为空。
输出参数	schema_name	name	Schema名。
输出参数	rel_oid	oid	表oid。
输出参数	rowgroup_id	integer	行组唯一标识。
输出参数	page_count	bigint unsigned	所查行组中页面数量。
输出参数	dirty_page_count	bigint unsigned	所查行组中脏页面数量。
输出参数	clean_page_count	bigint unsigned	所查行组中非脏页面数量。
输出参数	dirty_ratio	real	所查行组中脏页占全部页面数量比例。

示例：

htapdb=# SELECT * FROM gs_htap_tmu_chunk_meta('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p2', 0);
         rel_name         |       partition_name        | subpartition_name | schema_name | rel_oid | rowgroup_id | page_count | dirty_page_count | clean_page_count | dirty_ratio 
--------------------------+-----------------------------+-------------------+-------------+---------+-------------+------------+------------------+------------------+-------------
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |   16390 |           1 | 1          | 0                | 1                |           0
(1 row)

gs_global_imcv_bgworker_status()

描述：显示执行IMCV表重建的bgworker的状态信息，分布式下仅支持在CN节点执行，结果返回所有DN节点的信息。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员才有权限执行此函数。

表9 gs_global_imcv_bgworker_status参数说明
参数类型	参数名	类型	描述
输出参数	node_name	text	数据库节点名。
输出参数	worker_pid	bigint	线程号。
输出参数	database_id	oid	数据库id。
输出参数	relation_id	oid	正在处理的IMCV表的oid。
输出参数	rowgroup_id	integer	行组唯一标识。
输出参数	worker_status	text	表示init（初始化）、running（进行中）、ready（空闲）三种线程工作状态。
输出参数	worker_type	text	任务类型，包含以下五种： background_invalid_worker：无任务在执行。 background_unknown_worker：未知任务。 background_rowgroup_rebuild_worker：重建行组。 background_async_populate_worker：异步加载。 background_cache_worker：缓存区任务。
输出参数	start_time	timestamp with time zone	线程启动的时间戳。

示例：

htapdb=# SELECT * FROM gs_global_imcv_bgworker_status();
 node_name |   worker_pid    | database_id | relation_id | rowgroup_id | worker_status |        worker_type        |          start_time           
-----------+-----------------+-------------+-------------+-------------+---------------+---------------------------+-------------------------------
 datanode1 | 140067573069568 |       16384 |           0 |           0 | ready         | background_invalid_worker | 2025-12-02 21:10:16.282394+08
 datanode1 | 140067645421312 |       16384 |           0 |           0 | ready         | background_invalid_worker | 2025-12-02 21:10:12.267694+08
 datanode1 | 140067608721152 |           0 |           0 |           0 | ready         | background_invalid_worker | 2025-12-02 21:10:12.332674+08
 datanode2 | 139803070822144 |       16384 |           0 |           0 | ready         | background_invalid_worker | 2025-12-02 21:10:16.274911+08
 datanode2 | 139803270051584 |       16384 |           0 |           0 | ready         | background_invalid_worker | 2025-12-02 21:10:16.284832+08
 datanode2 | 139803153659648 |           0 |           0 |           0 | ready         | background_invalid_worker | 2025-12-02 21:10:12.374876+08
(6 rows)

gs_imcv_bgworker_status()

描述：显示执行IMCV表重建的bgworker的状态信息，分布式下执行返回当前节点的信息。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或者运维管理人员才有权限执行此函数。

**表10** gs_imcv_bgworker_status参数说明
参数类型	参数名	类型	描述
输出参数	worker_pid	bigint	线程号。
输出参数	database_id	oid	数据库id。
输出参数	relation_id	oid	正在处理的IMCV表的oid。
输出参数	rowgroup_id	integer	行组唯一标识。
输出参数	worker_status	cstring	表示init（初始化）、running（进行中）、ready（空闲）三种线程工作状态。
输出参数	worker_type	cstring	任务类型，包含background_invalid_worker（无任务在执行）、background_unknown_worker（未知任务）、background_rowgroup_rebuild_worker（重建行组）、background_async_populate_worker（异步加载）、background_cache_worker（缓存区任务）五种任务类型。
输出参数	start_time	timestamp with time zone	线程启动的时间戳。

示例：

htapdb=# SELECT * FROM gs_imcv_bgworker_status();
   worker_pid    | database_id | relation_id | rowgroup_id | worker_status |        worker_type        |          start_time           
-----------------+-------------+-------------+-------------+---------------+---------------------------+-------------------------------
 140067573069568 |       16384 |           0 |           0 | ready         | background_invalid_worker | 2025-12-02 21:10:16.282394+08
 140067645421312 |       16384 |           0 |           0 | ready         | background_invalid_worker | 2025-12-02 21:10:12.267694+08
 140067608721152 |           0 |           0 |           0 | ready         | background_invalid_worker | 2025-12-02 21:10:12.332674+08
(3 rows)

gs_global_imcu_meta(rel_name text, partname text)

描述：用于显示当前数据库下指定rel_name的IMCV表下的IMCU元信息，分布式下仅支持在CN节点执行，结果返回所有DN节点的信息。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员才有权限执行此函数。

**表11** gs_global_imcu_meta参数说明
参数类型	参数	类型	描述
输入参数	relname	text	IMCV表名。如果查询跨Schema的表信息，支持传入'schema.relname'形式。
输入参数	partname	text	IMCV分区名。查询分区表所有分区或非分区表时，该值可传入NULL或者''。
输出参数	node_name	text	数据库节点名字。
输出参数	rel_name	name	IMCV表名。
输出参数	partition_name	name	IMCV一级分区名。
输出参数	subpartition_name	name	IMCV二级分区名。
输出参数	schema_name	name	Schema名。
输出参数	rowgroup_id	integer	IMCU所在行组id。
输出参数	row_count	integer	IMCU行数。
输出参数	imcu_size	integer	IMCU大小，单位字节。
输出参数	imcu_data_size	integer	IMCU数据大小（不包含IMCU元信息），单位字节。
输出参数	compressed_data_size	integer	IMCU数据压缩后的大小。
输出参数	compressed_ratio	real	IMCU数据的压缩比。
输出参数	compressed_type	text	IMCU的压缩算法： none：无IMCU数据，无法压缩。 uncompressed：未进行压缩。 delta_plus_rle：IMCU数据采用delta_plus_rle压缩算法进行压缩。 lz4_compressed：IMCU数据采用lz4压缩算法进行压缩。 dict_compressed：IMCU数据采用dict压缩算法进行压缩。
输出参数	imcu_mode	integer	IMCU加载列数据特征： 1：普通。 2：全部为空。 3：相同值。 4：无最大最小值。 8：有空行。 16：无求和值。
输出参数	magic	integer	生成IMCU数据时的事务xid值，用于校验IMCU数据是否有效。
输出参数	attnum	smallint	IMCU加载列对应的attnum。
输出参数	scan_cnt	bigint	扫描IMCU的总次数。
输出参数	hit_cnt	bigint	命中内存态IMCU的次数。
输出参数	data_location	smallint	标记IMCU位于内存中、位于磁盘中或处于escape状态。 0：内存。 1：磁盘。 2：escape状态，因内存不足，仅创建元数据，查询这部分数据时会回行存读取。

示例：

htapdb=# SELECT * FROM gs_global_imcu_meta('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p2');
 node_name |         rel_name         |       partition_name        | subpartition_name | schema_name | rowgroup_id | row_count | imcu_size | imcu_data_size | compressed_data_size | compressed_ratio | compressed_type | imcu_mode | magic | attnum | scan_cnt | hit_cnt | data_location 
-----------+--------------------------+-----------------------------+-------------------+-------------+-------------+-----------+-----------+----------------+----------------------+------------------+-----------------+-----------+-------+--------+----------+---------+---------------
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |      4016 |             16 |                   16 |                1 | uncompressed    |         1 |     0 |      0 |        0 |       0 |             0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      1 |        0 |       0 |             0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      2 |        0 |       0 |             0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      3 |        0 |       0 |             0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      4 |        0 |       0 |             0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |      4032 |             24 |                   24 |                1 | uncompressed    |         4 |     0 |      5 |        0 |       0 |             0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      6 |        0 |       0 |             0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |      4016 |             16 |                   16 |                1 | uncompressed    |         1 |     0 |      0 |        0 |       0 |             0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      1 |        0 |       0 |             0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      2 |        0 |       0 |             0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      3 |        0 |       0 |             0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      4 |        0 |       0 |             0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |      4032 |             24 |                   24 |                1 | uncompressed    |         4 |     0 |      5 |        0 |       0 |             0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      6 |        0 |       0 |             0
(14 rows)

备注：该示例每一行代表一个IMCU（其中attnum为0的列为CTID列）。

gs_imcu_meta(rel_name text, partname text)

描述：用于显示当前数据库下指定rel_name的IMCV表下的IMCU元信息，分布式下执行返回当前节点的信息。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或者运维管理人员才有权限执行此函数。

**表12** gs_imcu_meta参数说明
参数类型	参数	类型	描述
输入参数	relname	text	IMCV表名。如果查询跨Schema的表信息，支持传入'schema.relname'形式。
输入参数	partname	text	IMCV分区名。查询分区表所有分区或非分区表时，该值可传入NULL或者''。
输出参数	rel_name	name	IMCV表名。
输出参数	partition_name	name	IMCV一级分区名。
输出参数	subpartition_name	name	IMCV二级分区名。
输出参数	schema_name	name	Schema名。
输出参数	rowgroup_id	integer	IMCU所在行组id。
输出参数	row_count	integer	IMCU行数。
输出参数	imcu_size	integer	IMCU大小，单位字节。
输出参数	imcu_data_size	integer	IMCU数据大小（不包含IMCU元信息），单位字节。
输出参数	compressed_data_size	integer	IMCU数据压缩后的大小。
输出参数	compressed_ratio	real	IMCU数据的压缩比。
输出参数	compressed_type	text	IMCU的压缩算法： none：无IMCU数据，无法压缩。 uncompressed：未进行压缩。 delta_plus_rle：IMCU数据采用delta_plus_rle压缩算法进行压缩。 lz4_compressed：IMCU数据采用lz4压缩算法进行压缩。 dict_compressed：IMCU数据采用dict压缩算法进行压缩。
输出参数	imcu_mode	integer	IMCU加载列数据特征： 1：普通。 2：全部为空。 3：相同值。 4：无最大最小值。 8：有空行。 16：无求和值。
输出参数	magic	integer	生成IMCU数据时的事务xid值，用于校验IMCU数据是否有效。
输出参数	attnum	smallint	IMCU加载列对应的attnum。
输出参数	scan_cnt	bigint unsigned	扫描IMCU的总次数。
输出参数	hit_cnt	bigint unsigned	命中内存态IMCU的次数。
输出参数	data_location	smallint	标记IMCU位于内存中、位于磁盘中或处于escape状态。 0：内存。 1：磁盘。 2：escape状态，因内存不足，仅创建元数据，查询这部分数据时会回行存读取。

示例：

htapdb=# SELECT * FROM gs_imcu_meta('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p2');
         rel_name         |       partition_name        | subpartition_name | schema_name | rowgroup_id | row_count | imcu_size | imcu_data_size | compressed_data_size | compressed_ratio | compressed_type | imcu_mode | magic | attnum | scan_cnt | hit_cnt | data_location 
--------------------------+-----------------------------+-------------------+-------------+-------------+-----------+-----------+----------------+----------------------+------------------+-----------------+-----------+-------+--------+----------+---------+---------------
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |      4016 |             16 |                   16 |                1 | uncompressed    |         1 |     0 |      0 | 0        | 0       |             0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      1 | 0        | 0       |             0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      2 | 0        | 0       |             0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      3 | 0        | 0       |             0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      4 | 0        | 0       |             0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |      4032 |             24 |                   24 |                1 | uncompressed    |         4 |     0 |      5 | 0        | 0       |             0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |           1 |         1 |         0 |              0 |                    0 |                0 | none            |         3 |     0 |      6 | 0        | 0       |             0
(7 rows)

备注：该示例每一行代表一个IMCU（其中attnum为0的列为CTID列）。

gs_global_htap_file_status(db_name text)

描述：查看HTAP列存IMCU落盘文件的使用信息，分布式下仅支持在CN节点执行，结果返回所有DN节点的信息。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员才有权限执行此函数。

**表13** gs_global_htap_file_status参数说明
参数类型	参数	类型	描述
输入参数	db_name	text	数据库名字，输入为''或NULL表示查询所有数据库。
输出参数	node_name	text	数据库节点名字。
输出参数	db_oid	integer	数据库id。
输出参数	file_name	text	数据文件名。
输出参数	file_id	integer	数据文件标识，当前版本返回值只有2。
输出参数	extent_size	integer	数据文件的扩展大小。
输出参数	allocated_blocks	bigint	数据文件已分配给IMCU使用的页面数。
输出参数	total_blocks	bigint	数据文件在磁盘上的总物理页面数。
输出参数	high_water_mark	bigint	数据文件使用页数的高水位线。
输出参数	utilization	real	使用的block数占总block数的百分比。
输出参数	ext	text	扩展字段，当前版本为NULL。

示例：

htapdb=# SELECT * FROM gs_global_htap_file_status('htapdb');
 node_name | db_oid |        file_name         | file_id | extent_size | allocated_blocks | total_blocks | high_water_mark | utilization | ext 
-----------+--------+--------------------------+---------+-------------+------------------+--------------+-----------------+-------------+-----
 datanode1 |  16384 | global/imcu/16384/2_imcu |       2 |           4 |                0 |            0 |               0 |           1 | 
 datanode2 |  16384 | global/imcu/16384/2_imcu |       2 |           4 |                0 |            0 |               0 |           1 | 
(2 rows)

gs_htap_file_status(db_name text)

描述：查看HTAP列存IMCU落盘文件的使用信息，分布式下执行返回当前节点的信息。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或者运维管理人员才有权限执行此函数。

**表14** gs_htap_file_status参数说明
参数类型	参数	类型	描述
输入参数	db_name	text	数据库名字，输入为''或NULL表示查询当前节点下所有数据库。
输出参数	db_oid	oid	数据库id。
输出参数	file_name	text	数据文件名。
输出参数	file_id	integer	数据文件标识，当前版本返回值只有2。
输出参数	extent_size	integer	数据文件的扩展大小。
输出参数	allocated_blocks	bigint	数据文件已分配给IMCU使用的页面数。
输出参数	total_blocks	bigint	数据文件在磁盘上的总物理页面数。
输出参数	high_water_mark	bigint	数据文件使用页数的高水位线。
输出参数	utilization	real	使用的block数占总block数的百分比。
输出参数	ext	text	扩展字段，当前版本为NULL。

示例：

htapdb=# SELECT * FROM gs_htap_file_status('htapdb');
 db_oid |        file_name         | file_id | extent_size | allocated_blocks | total_blocks | high_water_mark | utilization | ext 
--------+--------------------------+---------+-------------+------------------+--------------+-----------------+-------------+-----
  16384 | global/imcu/16384/2_imcu |       2 |           4 |                0 |            0 |               0 |           1 | 
(1 row)

gs_global_htap_scan_hit_status(relname text, partname text)

描述：用于查询表粒度的IMCU命中率信息，分布式下仅支持在CN节点执行，结果返回所有DN节点的信息。当reloid为0时，返回当前数据库下所有IMCV表的命中率信息；当reloid非0时，返回指定表中的命中率信息。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员才有权限执行此函数。

**表15** gs_global_htap_scan_hit_status参数说明
参数类型	参数	类型	描述
输入参数	relname	text	表名。如果查询跨Schema的表信息，支持传入'schema.relname'形式。
输入参数	partname	text	分区名。查询分区表所有分区或非分区表时，该值可传入NULL或者''。
输出参数	node_name	text	数据库节点名。
输出参数	rel_name	name	表名。
输出参数	partition_name	name	分区名。
输出参数	subpartition_name	name	二级分区名。
输出参数	schema_name	name	Schema名。
输出参数	column_number	integer	列序号。
输出参数	column_name	name	列名。
输出参数	imcu_in_cache_cnt	bigint unsigned	该列存放于缓存区的IMCU数。
输出参数	imcu_ave_scan_cnt	bigint unsigned	该列平均每个IMCU的使用次数。
输出参数	imcu_total_scan_cnt	bigint unsigned	该列IMCU总的使用次数。
输出参数	imcu_ave_hit_cnt	bigint unsigned	该列平均每个IMCU的缓存命中数。
输出参数	imcu_total_hit_cnt	bigint unsigned	该列IMCU总的缓存命中数。
输出参数	total_hit_percentage	real	该列IMCU总的缓存命中率。

示例：

htapdb=# SELECT * FROM gs_global_htap_scan_hit_status('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p2');
 node_name |         rel_name         |       partition_name        | subpartition_name | schema_name | column_number | column_name | imcu_in_cache_cnt | imcu_ave_scan_cnt | imcu_total_scan_cnt | imcu_ave_hit_cnt | imcu_total_hit_cnt | total_hit_percentage 
-----------+--------------------------+-----------------------------+-------------------+-------------+---------------+-------------+-------------------+-------------------+---------------------+------------------+--------------------+----------------------
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             0 | ctid        | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             1 | c1          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             2 | c2          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             3 | c3          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             4 | c4          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             5 | c5          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode1 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             6 | c6          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             0 | ctid        | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             1 | c1          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             2 | c2          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             3 | c3          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             4 | c4          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             5 | c5          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
 datanode2 | htap_flush_by_name_part1 | htap_flush_by_name_part1_p2 |                   | public      |             6 | c6          | 1                 | 0                 | 0                   | 0                | 0                  |                    0
(14 rows)

gs_htap_scan_hit_status(relname text, partname text)

描述：用于查询表粒度的IMCU命中率信息，分布式下执行返回当前节点的信息。当relname与partname均为null或空时，返回当前节点下所有IMCV表的命中率信息；其他情况返回指定表或指定分区的命中率信息。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或者运维管理人员才有权限执行此函数。

**表16** gs_htap_scan_hit_status参数说明
参数类型	参数	类型	描述
输入参数	relname	text	表名。如果查询跨Schema的表信息，支持传入'schema.relname'形式。
输入参数	partname	text	分区名，查询分区表所有分区或非分区表时，该值可传入NULL或者''。
输出参数	rel_name	name	表名。
输出参数	partition_name	name	分区名。
输出参数	subpartition_name	name	二级分区名。
输出参数	schema_name	name	Schema名。
输出参数	column_number	integer	列序号。
输出参数	column_name	name	列名。
输出参数	imcu_in_cache_cnt	bigint unsigned	该列存放于缓存区的IMCU数。
输出参数	imcu_total_cnt	bigint unsigned	该列总的IMCU数。
输出参数	imcu_ave_scan_cnt	bigint unsigned	该列平均每个IMCU的使用次数。
输出参数	imcu_total_scan_cnt	bigint unsigned	该列IMCU总的使用次数。
输出参数	imcu_ave_hit_cnt	bigint unsigned	该列平均每个IMCU的缓存命中数。
输出参数	imcu_total_hit_cnt	bigint unsigned	该列IMCU总的缓存命中数。
输出参数	total_hit_percentage	real	该列IMCU总的缓存命中率。

示例：

gaussdb=# SELECT * FROM gs_htap_scan_hit_status('htap_flush_by_name_part1', 'htap_flush_by_name_part1_p1');
         rel_name         |       partition_name        | subpartition_name | schema_name | column_number | column_name | imcu_in_cache_cnt | imcu_total_cnt | imcu_ave_scan_cnt | imcu_total_scan_cnt | imcu_ave_hit_cnt | imcu_total_hit_cnt | tot
al_hit_percentage 
--------------------------+-----------------------------+-------------------+-------------+---------------+-------------+-------------------+----------------+-------------------+---------------------+------------------+--------------------+----
------------------
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      |             0 | ctid        | 1                 | 1              | 0                 | 0                   | 0                | 0                  |    
                0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      |             1 | c1          | 1                 | 1              | 0                 | 0                   | 0                | 0                  |    
                0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      |             2 | c2          | 1                 | 1              | 0                 | 0                   | 0                | 0                  |    
                0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      |             3 | c3          | 1                 | 1              | 0                 | 0                   | 0                | 0                  |    
                0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      |             4 | c4          | 1                 | 1              | 0                 | 0                   | 0                | 0                  |    
                0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      |             5 | c5          | 1                 | 1              | 0                 | 0                   | 0                | 0                  |    
                0
 htap_flush_by_name_part1 | htap_flush_by_name_part1_p1 |                   | public      |             6 | c6          | 1                 | 1              | 0                 | 0                   | 0                | 0                  |    
                0
(7 rows)

gs_imcu_size_estimation(relname text, partname text, colnum_name_array text[])

描述：该函数返回该表指定分区指定列创建IMCV列存数据预估的内存使用值，DN节点执行时返回当前节点预估值，CN节点执行返回各个节点预估值。

返回值类型：record

仅参数enable_htap=on时可用。
仅系统管理员或者运维管理人员才有权限执行此函数。
不支持备机执行。该函数约束与HTAP DDL保持一致，相关报错信息与实际执行DDL报错信息一致。

**表17** gs_imcu_size_estimation参数说明
参数类型	参数名	类型	描述
输入参数	relname	text	表名。如果查询跨Schema的表信息，支持传入'schema.relname'形式。
输入参数	partname	text	分区名。查询分区表所有分区或非分区表时，该值可传入NULL或者''。
输入参数	colnum_name_array	text[]	列名数组。
输出参数	node_name	name	节点名。
输出参数	estimated_size	bigint unsigned	预估内存使用值，单位字节。

示例：

htapdb=# SELECT * FROM gs_imcu_size_estimation('estimate_htap', '', ARRAY['id']);
 node_name | estimated_size 
-----------+----------------
 datanode1 | 28411
 datanode2 | 28089
(2 rows)

gs_htap_data_maintenance(rel_oid oid, type integer)

描述：列存数据的维护接口，提供两项能力（1）卸载列存数据（清理内存和磁盘空间）;（2）所有列存数据落盘的逃生手段。

返回值类型：text

该接口会直接卸载IMCV保护行存TP业务，会导致已经使用IMCV Scan的业务报错，使用前需充分确认影响。仅供因配置或其他原因导致IMCV内存等资源使用过量，集群又无法停机时，紧急逃生使用。

仅参数enable_htap=on时可用。
仅系统管理员或者运维管理人员才有权限执行此函数。
该函数不允许在事务内执行。
分布式下该函数只能在DN执行，不支持在CN执行。

**表18** gs_htap_data_maintenance参数说明
参数类型	参数	类型	描述
输入参数	rel_oid	oid	行存表oid，0表示处理当前DN节点的数据库下所有表。
输入参数	type	integer	处理类型，取值范围： 0：表示卸载对应表的所有IMCV数据，包括内存和落盘数据文件，仅保留元数据，gs_imcv系统表还存在信息，通过gs_imcv_status视图查询状态为'E'。入参rel_oid为0时，卸载所有表IMCV数据，落盘文件会被清理，磁盘空间也会释放。使用该接口卸载IMCV后，IMCV状态为'E'，此时无法使用HTAP相关功能，需要重新创建IMCV或执行VACUUM FULL将基表与对应分区的IMCV状态转为'F' 。 1：该参数已废弃。 2：表示将对应表的IMCV数据全部落盘。

示例：

htapdb=# SELECT * FROM gs_htap_data_maintenance(16824,0);
 gs_htap_data_maintenance 
--------------------------
 Maintenance finish.
(1 row)
htapdb=# SELECT * FROM gs_htap_data_maintenance(16824,2);
 gs_htap_data_maintenance 
--------------------------
 Maintenance finish.
(1 row)

父主题： 系统管理函数

上一篇：Undo系统函数

下一篇：其它函数

HTAP系统函数

相关文档

您对此文档页面的整体评价？