Updated on 2025-05-29 GMT+08:00

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)