Help Center/ GaussDB/ Developer Guide(Centralized_V2.0-8.x)/ SQL Reference/ Functions and Operators/ System Administration Functions/ HTAP System Functions

Updated on 2025-09-22 GMT+08:00

View PDF

HTAP System Functions

gs_htap_tmu_data(rel_oid oid, rowgroup_id integer)

Description: Views active transaction statistics in the real-time transaction unit TMU. If rowgroup_id is set to 0, all active transaction statistics in the table are returned. If rowgroup_id is set to a non-zero value, the active transaction statistics in the specified row group in the table are returned.

Return type: record

Note: Only SYSADMIN or OPRADMIN can execute this function.

This function affects OLTP services, and it is used only as an O&M API. You are advised not to run this function frequently.

**Table 1** gs_htap_tmu_data parameters
Category	Parameter	Type	Description
Input parameter	rel_oid	oid	OID of the row-store table.
Input parameter	rowgroup_id	integer unsigned	Identifies a row group.
Output parameter	rel_oid	oid	OID of the row-store table.
Output parameter	rowgroup_id	integer unsigned	Identifies a row group.
Output parameter	xid	xid	ID of the transaction that operates the data.
Output parameter	ctid	cstring	Location of the data on the page.
Output parameter	flag	smallint unsigned	Binary flag bit. Each bit indicates an operation attribute recorded by the TMU. The details are as follows: If the fourth digit is 1, an update operation is recorded. If the third digit is 1, a delete operation is recorded. If the second digit is 1, an insert operation is recorded.

Example:

When enable_htap is set to off:

gaussdb=#select * from gs_htap_tmu_data(16796,0);
ERROR:  Query failed due to ENABLE_HTAP is not enabled.

When enable_htap is set to on:

gaussdb=#select * from gs_htap_tmu_data(16796,0);
 rel_oid | rowgroup_id |  xid  | ctid  | flag
---------+-------------+-------+-------+-------
   16796 | 1           | 78437 | (0,1) | 16385
   16796 | 1           | 78437 | (0,2) | 16385
   16796 | 1           | 78439 | (0,1) | 4097
   16796 | 1           | 78439 | (0,2) | 4097
(4 rows)

gs_htap_tmu_chunk_meta(rel_oid oid, rowgroup_id integer)

Description: Views the metadata of the real-time transaction unit TMU. If rowgroup_id is set to 0, the data of real-time transaction unit TMU in all row groups is returned. If rowgroup_id is set to a non-zero value, the data of real-time transaction unit TMU in a specified row group in the table is returned.

Return type: record

Note: Only SYSADMIN or OPRADMIN can execute this function.

**Table 2** gs_htap_tmu_chunk_meta parameters
Category	Parameter	Type	Description
Input parameter	rel_oid	oid	OID of the row-store table.
Input parameter	rowgroup_id	integer unsigned	Identifies a row group.
Output parameter	rel_oid	oid	OID of the row-store table.
Output parameter	rowgroup_id	integer unsigned	Identifies a row group.
Output parameter	status	smallint unsigned	TMU status. The value 1 indicates that the TMU has not been cleared. The value 2 indicates that the TMU has been cleared.
Output parameter	row_count	integer unsigned	Number of rows in the table.
Output parameter	buffer_count	integer unsigned	Number of contained buffers.
Output parameter	mem_usage	bigint	Size of the allocated memory
Output parameter	inprogress	cstring	The percentage of active TMU data insertion transactions.
Output parameter	completed	cstring	The percentage of committed or rolled back TMU data insertion transactions.

Example:

When enable_htap is set to off:

gaussdb=#select * from gs_htap_tmu_chunk_meta(16796,0);
ERROR:  Query failed due to ENABLE_HTAP is not enabled.

When enable_htap is set to on:

gaussdb=#select * from gs_htap_tmu_chunk_meta(16796,0);
 rel_oid | rowgroup_id | status | row_count | buffer_count | mem_usage | inprogress | completed
---------+-------------+--------+-----------+--------------+-----------+------------+-----------
   16796 | 1           | 1      | 4         | 1            |     65536 | 0.00%      | 100.00%
(1 row)

gs_imcv_bgworker_status()

Description: Displays the status of the bgworker rebuilt by IMCV tables.

Return type: record

Note: Only SYSADMIN or OPRADMIN can execute this function.

**Table 3** gs_imcv_bgworker_status parameters
Category	Parameter	Type	Description
Output parameter	worker_pid	bigint	Thread ID
Output parameter	relation_id	oid	OID of the IMCV table that is being processed.
Output parameter	worker_status	cstring	Indicates three working states of the thread: idle, running, and finished.
Output parameter	start_time	timestamp with time zone	Timestamp when rebuild starts.

Example:

When enable_htap is set to off:

gaussdb=#select * from gs_imcv_bgworker_status();
ERROR:  Query failed due to ENABLE_HTAP is not enabled.

When enable_htap is set to on:

gaussdb=#select * from gs_imcv_bgworker_status();
 worker_pid | relation_id | worker_status | start_time
------------+-------------+---------------+------------
          0 |           0 | finished      |
          0 |           0 | idle          |
          0 |           0 | idle          |
(3 rows)

gs_imcv_flush(reloid oid)

Description: Immediately rebuilds a specified IMCV table in the database and displays the rebuild result. During the rebuild, the IMCV table is refreshed, old data is removed, and inactive data in the current table is synchronized.

Return type: text

Note: Only SYSADMIN or OPRADMIN can execute this function.

When the data in an IMCV table is fresh enough, rebuild may be skipped. This function affects OLTP services, and it is used only as an O&M API. You are advised not to run this function frequently.

**Table 4** gs_imcv_flush parameters
Category	Parameter	Type	Description
Input parameter	reloid	oid	OID of the row-store table.
Output parameter	output	text	Indicates the rebuild result. The number of row groups that are successfully rebuilt and the number of row groups that are skipped are displayed.

Example:

When enable_htap is set to off:

gaussdb=#select * from gs_imcv_flush(16796);
ERROR:  Manual row group rebuilding failed due to ENABLE_HTAP is not enabled.

When enable_htap is set to on:

gaussdb=#select * from gs_imcv_flush(16796);
                 gs_imcv_flush
------------------------------------------------
 2 row groups rebuilt successfully, 1 skipped.
(1 row)

gs_imcv_taskbuffer_view()

Description: Displays the usage of a rebuilt task queue in the HTAP service. The input parameter is empty.

Return type: record

Note: Only SYSADMIN or OPRADMIN can execute this function.

**Table 5** gs_imcv_taskbuffer_view parameters
Category	Parameter	Type	Description
Output parameter	buffer_is_empty	boolean	Specifies whether the task queue is empty. The default value is t.
Output parameter	buffer_is_full	boolean	Specifies whether the task queue is full. The default value is f.
Output parameter	buffer_used_space	integer	Used space of the task. The default value is 0.
Output parameter	buffer_free_space	integer	Remaining space of the task. The default value is 999.

Example:

When enable_htap is set to off:

gaussdb=#select * from gs_imcv_taskbuffer_view();
ERROR:  Query failed due to ENABLE_HTAP is not enabled.

When enable_htap is set to on:

gaussdb=#select * from gs_imcv_taskbuffer_view();
 buffer_is_empty | buffer_is_full | buffer_used_space | buffer_free_space
-----------------+----------------+-------------------+-------------------
 t               | f              |                 0 |               999
(1 row)

gs_imcu_meta(rel_name)

Description: gs_imcu_meta is used to display the IMCU metadata information in the IMCV table with the specified rel_name.

Return type: record

**Table 6** gs_imcu_meta parameters
Category	Parameter	Type	Description
Input parameter	relname	text	IMCV table name.
Output parameter	reloid	oid	Table ID.
Output parameter	relname	text	Table name.
Output parameter	imcu_xmin	xid	Reserved.
Output parameter	imcu_id	integer	IMCU ID.
Output parameter	row_count	integer	Number of rows of the IMCU.
Output parameter	imcu_size	integer	IMCU size, in bytes.
Output parameter	imcu_mode	integer	Characteristics of column data loaded by the IMCU: Common. All of the data is empty. The data has a same value. There is no maximum/minimum value. There is an empty row.
Output parameter	imcu_pointer	bigint	Reserved.
Output parameter	magic	integer	magic verified by IMCU.
Output parameter	attnum	smallint	attnum corresponding to the column loaded by IMCU.

Example:

gaussdb=#SELECT * FROM gs_imcu_meta('test2');
I reloid | relname | imcu_xmin | imcu_id | row_count | imcu_size | imcu_mode | imcu_pointer | magic | attnum 
--------+---------+-----------+---------+-----------+-----------+-----------+--------------+-------+--------
 115114 | test2   |         0 |       1 |         9 |      8192 |         1 |            0 | 74802 |      0
 115114 | test2   |         0 |       1 |         9 |      8192 |         1 |            0 | 74802 |      1
 115114 | test2   |         0 |       1 |         9 |      8192 |         1 |            0 | 74802 |      2
 115114 | test2   |         0 |       1 |         9 |      8192 |         1 |            0 | 74802 |      3
 115114 | test2   |         0 |       1 |         9 |      8192 |         0 |            0 | 74802 |      4
 115114 | test2   |         0 |       1 |         9 |      8192 |         0 |            0 | 74802 |      5
(6 rows)

Note: This example indicates that there is one row group (imcu_id is 1), each row represents a CU (the column whose attnum is 0 is the ctid column), and each CU has nine rows.

gs_imcv_status()

Description: gs_imcv_status displays the status of all IMCV tables.

Return type: record

**Table 7** gs_imcv_status parameters
Parameter	Parameter	Type	Description
Output parameter	reloid	oid	Table ID.
Output parameter	relname	name	Table name.
Output parameter	dbname	name	Database name.
Output parameter	username	name	Username.
Output parameter	parentoid	oid	Parent table ID.
Output parameter	imcvstatus	char	IMCV table status: I: POPULATE_STAT_INIT (initiate) L: POPULATE_STAT_LOAD_START (start loading) M: POPULATE_STAT_LOAD_META_DONE (load metadata) F: POPULATE_STAT_LOAD_FINISH (loading completed) D: POPULATE_STAT_DROP (deleted) E: POPULATE_STAT_ERROR (abnormal)
Output parameter	imcvnattr	smallint	Number of loaded columns.
Output parameter	imcvkey	int2vector	Array of loaded columns.
Output parameter	priority	smallint	Loading priority.
Output parameter	rowgroup_num	integer	Number of row groups.
Output parameter	cu_num_in_mem	integer	Number of IMCUs in the memory.
Output parameter	cu_mem_size	bigint	Memory occupied by IMCU, in bytes.
Output parameter	cu_num_in_disk	integer	Not supported. The value is 0.
Output parameter	cu_disk_size	bigint	Not supported. The value is 0.

Example:

gaussdb=#SELECT * FROM gs_imcv_status();
 reloid | relname |  dbname  | username | parentoid | imcvstatus | imcvnattr |  imcvkey  | priority | rowgroup_num | cu_num_in_mem | cu_mem_size | cu_num_in_disk | cu_disk_size 
--------+---------+----------+----------+-----------+------------+-----------+-----------+----------+--------------+---------------+-------------+----------------+--------------
 115114 | test2   | postgres | lqy      |         0 | F          |         5 | 1 2 3 4 5 |        1 |            1 |             6 |       49152 |              0 |            0
(1 row)

gs_imcu_slot_status()

Description: gs_imcu_slot_status records the cache slot information of the IMCU in the IMCV table.

Return type: record

**Table 8** gs_imcu_slot_status parameters
Category	Parameter	Type	Description
Output parameter	reloid	oid	Table ID.
Output parameter	cu_id	integer	IMCU ID.
Output parameter	col_id	integer	Column ID of the IMCU.
Output parameter	slot_id	integer	Slot ID of the cache.
Output parameter	block_size	integer	IMCU size, in bytes.
Output parameter	flag	char	Cache block flag.

Example (The value of flag is \x01, indicating that the cache slot contains valid data):

gaussdb=#SELECT * FROM gs_imcu_slot_status();
 reloid | cu_id | col_id | slot_id | block_size | flag 
--------+-------+--------+---------+------------+------
 115114 |     1 |      1 |       0 |       8192 | \x01
 115114 |     1 |      2 |       1 |       8192 | \x01
 115114 |     1 |      3 |       2 |       8192 | \x01
 115114 |     1 |      4 |       3 |       8192 | \x01
 115114 |     1 |      5 |       4 |       8192 | \x01
 115114 |     1 |      0 |       5 |       8192 | \x01
(6 rows)

Parent topic: System Administration Functions

Previous topic: Row-Store Compression System Functions

Next topic: VACUUM System Functions