文档首页/ 云数据库 GaussDB/ 开发指南（主备版_3.x）/ SQL参考/ 函数和操作符/ 系统管理函数/ Undo系统函数

更新时间：2024-05-07 GMT+08:00

Undo系统函数

gs_undo_meta(type, zoneId, location)

描述：Undo模块元信息。

参数说明：

type(元信息类型)
- 0：表示UndoZone(Record) 对应的元信息。
- 1：表示UndoZone(Transaction Slot) 对应的元信息。
- 2：表示UndoSpace(Record) 对应的元信息。
- 3：表示UndoSpace(Transaction Slot) 对应的元信息。
zoneId(UndoZone编号)
- -1：表示所有UndoZone的元信息。
- 0-1024*1024-1：表示对应ZoneID的元信息。
location(读取位置）
- 0：表示从当前内存中读取。
- 1：表示从物理文件中读取。

返回值类型：record

表1 gs_undo_meta参数说明
参数类型	参数名	类型	描述
输出参数	zoneId	oid	Undo Zone的ID。
输出参数	persistType	oid	持久化级别。
输出参数	insert	text	下一条插入的Undo记录位置。
输出参数	discard	text	普通回收到的Undo记录位置。
输出参数	end	text	强制回收掉的Undo记录位置，小于它的Undo记录已经被回收。
输出参数	used	text	已经使用的Undo空间。
输出参数	lsn	text	修改UndoZone的LSN。
输出参数	pid	oid	UndoZone绑定的进程ID。

gs_undo_translot(location, zoneId)

描述：Undo事务槽信息。

参数说明：

location(读取位置)
- 0：表示从当前内存中读取。
- 1：表示从物理文件中读取。
zoneId(UndoZone编号)
- -1：表示所有UndoZone的元信息。
- 0-1024*1024-1：表示对应ZoneID的元信息。

返回值类型：record

表2 gs_undo_translot参数说明
参数类型	参数名	类型	描述
输出参数	groupId	oid	使用的UndoZone ID。
输出参数	xactId	text	事务ID。
输出参数	startUndoPtr	text	Transaction Slot对应事务起始插入Undo记录位置。
输出参数	endUndoPtr	text	Transaction Slot对应事务结束插入Undo记录位置。
输出参数	lsn	text	对应Transaction Slot指针。
输出参数	slot_states	oid	事务状态。 0：表示已经提交。 1：表示正在执行中。 2：表示回滚中。 3：表示回滚完成。

gs_stat_undo([bool init])

描述：Undo统计信息。

返回值类型：record

表3 gs_stat_undo参数说明
参数类型	参数名	类型	描述
输入参数	init	bool	可选参数，是否清理统计信息并重新开始统计。
输出参数	curr_used_zone_count	uint32	当前使用的UndoZone数量。
输出参数	top_used_zones	text	前三个使用量最大的UndoZone信息，格式输出为： zoneId1：使用大小。 zoneId2：使用大小。 zoneId3：使用大小。
输出参数	curr_used_undo_size	uint32	当前使用的Undo总空间大小，单位为MB。
输出参数	undo_threshold	uint32	为guc参数undo_space_limit_size * 80%计算的结果,单位为MB。
输出参数	global_recycle_xid	uint64	当前Undo空间回收到的事务xid(小于该xid事务产生的Undo记录都已经被回收)。
输出参数	oldest_xmin	uint64	最老的活跃事务。
输出参数	total_undo_chain_len	int64	所有访问过的Undo链总长度。
输出参数	max_undo_chain_len	int64	最大访问过的Undo链长度。
输出参数	create_undo_file_count	uint32	创建的Undo文件数量统计。
输出参数	discard_undo_file_count	uint32	删除的Undo文件数量统计。
输出参数	info	text	如果入参为false，输出undo_space_limit_size、undo_limit_size_per_transaction 、undo_retention_time 参数的合理化建议。如果入参为true，即需要init（清理统计信息），仅提示‘The statistics have been initialized.’。

示例1：清理undo统计信息

gaussdb=# select * from gs_stat_undo(true);
 curr_used_zone_count |   top_used_zones    | curr_used_undo_size | undo_threshold | global_recycle_xid | oldest_xmin | total_undo_chain_len | max_undo_chain_len | create_undo_file_coun
t | discard_undo_file_count |                 info
----------------------+---------------------+---------------------+----------------+--------------------+-------------+----------------------+--------------------+----------------------
--+-------------------------+--------------------------------------
                    3 | 0 : 0, 0 : 0, 0 : 0 |                   1 |         209715 |              15741 |       15741 |                    0 |                  0 |
2 |                       0 | The statistics have been initialized.
(1 row)

示例2：输出undo统计信息

gaussdb=# select * from gs_stat_undo(false);
 curr_used_zone_count |   top_used_zones    | curr_used_undo_size | undo_threshold | global_recycle_xid | oldest_xmin | total_undo_chain_len | max_undo_chain_len | create_undo_file_coun
t | discard_undo_file_count |
             info

----------------------+---------------------+---------------------+----------------+--------------------+-------------+----------------------+--------------------+----------------------
--+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
                    3 | 0 : 0, 0 : 0, 0 : 0 |                   1 |         209715 |              16253 |       16253 |                    0 |                  0 |
2 |                       0 | Based on the statistic info from last initialization, undo_space_limit_size is recommended to set >= 120953 blocks, undo_limit_size_per_transaction is
recommended to set <= 327150 blocks, undo_retention_time is recommended to set <= 259200 seconds. Since last initialization, max undo space used by a single transaction is 32715 blocks.
(1 row)

gs_undo_record(undoptr)
描述：Undo记录解析。

参数说明：
- undoptr（undo记录指针）
返回值类型：record

gs_undo_dump_parsepage_mv(relpath text, blkno bigint, reltype text, rmem boolean)

描述：解析USTORE数据表磁盘页面的页头信息，每个元组的头部信息，标识位信息以及所有可以查询到undo历史版本信息。

返回值类型：text

备注：必须是系统管理员或者运维管理人员才能执行此函数。

该接口当前仅支持USTORE数据表。

表4 gs_undo_dump_parsepage_mv参数说明
参数类型	参数名	类型	描述
输入参数	relpath	text	USTORE表数据文件相对路径，相对路径格式为：tablespace name/database oid/relfilenode，例如base/16603/16384, 表对应数据文件的相对路径查找可以通过pg_relation_filepath('tablename')查询。
输入参数	blkno	bigint	-1：解析所有block页面。 0-MaxBlocNumber：解析指定的block页面。
输入参数	reltype	text	表类型，目前仅支持USTORE数据表，取值为uheap。
输入参数	rmem	boolean	false true 目前仅支持false，从磁盘文件上解析对应的页面。
输出参数	output	text	解析结果文件的绝对路径。

gs_undo_meta_dump_zone(zone_id int, read_memory boolean)

描述：解析Undo模块中UndoZone的元信息。

返回值类型：record

表5 gs_undo_meta_dump_zone参数说明
参数类型	参数名	类型	描述
输入参数	zone_id	int	UndoZone编号： -1：查询所有UndoZone。 0-1,048,575：查询对应zone_id编号的UndoZone元信息。
输入参数	read_memory	boolean	true：从当前内存中读取。 false：从物理文件中读取。
输出参数	zone_id	int	UndoZone编号。
输出参数	persist_type	int	持久化级别： 0：普通表。 1：无日志表。 2：临时表。
输出参数	insert	text	下一条插入的Undo记录位置。
输出参数	discard	text	普通回收到的Undo记录位置。
输出参数	forcediscard	text	强制回收掉Undo记录位置，小于它的Undo记录已经被回收。
输出参数	lsn	text	修改Zone的LSN。

gs_undo_meta_dump_spaces(zone_id int, read_memory boolean)

描述：解析Undo模块中Undo记录空间、Transaction Slot空间的元信息。

返回值类型：record

表6 gs_undo_meta_dump_spaces参数说明
参数类型	参数名	类型	描述
输入参数	zone_id	int	UndoZone编号： -1：查询所有UndoZone。 0-1,048,575：查询对应zone_id编号的UndoZone元信息。
输入参数	read_memory	boolean	true：从当前内存中读取。 false：从物理文件中读取。
输出参数	zone_id	int	UndoZone编号。
输出参数	undorecord_space_tail	text	UndoRecord空间的结尾位置。
输出参数	undorecord_space_head	text	UndoRecord空间的起始位置。
输出参数	undorecord_space_lsn	text	修改UndoRecord空间LSN。
输出参数	undoslot_space_tail	text	Transaction Slot空间的结尾位置。
输出参数	undoslot_space_head	text	Transaction Slot空间的起始位置。
输出参数	undoreslot_space_lsn	text	修改Transaction Slot空间LSN。

gs_undo_meta_dump_slot(zone_id int, read_memory boolean)

描述：解析Undo模块中Transaction Slot元信息。

返回值类型：record

表7 gs_undo_meta_dump_slot参数说明
参数类型	参数名	类型	描述
输入参数	zone_id	int	Undo zone编号： -1：查询所有UndoZone。 0-1,048,575：查询对应zone_id编号的UndoZone元信息。
输入参数	read_memory	boolean	true：从当前内存中读取。 false：从物理文件中读取。
输出参数	zone_id	int	UndoZone编号。
输出参数	allocate	text	Undo Transaction Slot分配位置。
输出参数	recycle	text	Undo Transaction Slot回收位置。
输出参数	frozen_xid	text	Frozen Xid，用于可见性判断。
输出参数	global_frozen_xid	text	全局最小的Frozen Xid，小于该Xid的事务可见。
输出参数	recycle_xid	text	回收到的Xid，小于该Xid的事务被回收。
输出参数	global_recycle_xid	text	全局最小的Recycle Xid，小于该Xxid的事务被回收。

gs_undo_translot_dump_slot(zone_id int, read_memory boolean)

描述：解析UndoZone中的Transaction Slot。

返回值类型：record

表8 gs_undo_translot_dump_slot参数说明
参数类型	参数名	类型	描述
输入参数	zone_id	oid	UndoZone编号： -1：查询所有UndoZone。 0-1,048,575：查询对应zone_id编号的UndoZone元信息。
输入参数	read_memory	boolean	true：从当前内存中读取。 false：从物理文件中读取。
输出参数	zone_id	text	UndoZone编号。
输出参数	slot_xid	text	事务ID。
输出参数	start_undoptr	text	Transaction Slot对应事务起始插入Undo记录位置。
输出参数	end_undoptr	text	Transaction Slot对应事务结束插入Undo记录位置。
输出参数	slot_ptr	text	Transaction Slot对应的位置。
输出参数	slot_states	oid	事务状态： 0：已提交。 1：执行中。 2：回滚中。 3：回滚完成。

gs_undo_translot_dump_xid(slot_xid xid, read_memory boolean)

描述：根据xid解析UndoZone中对应的Transaction Slot。

返回值类型：record

表9 gs_undo_translot_dump_xid参数说明
参数类型	参数名	类型	描述
输入参数	slot_xid	xid	需要查询的事务ID。
输入参数	read_memory	boolean	true：从当前内存中读取。 false：从物理文件中读取。
输出参数	zone_id	text	UndoZ-one编号。
输出参数	slot_xid	text	事务ID。
输出参数	start_undoptr	text	Transaction Slot对应事务起始插入Undo记录位置。
输出参数	end_undoptr	text	Transaction Slot对应事务结束插入Undo记录位置。
输出参数	slot_ptr	text	Transaction Slot对应的位置。
输出参数	slot_states	oid	事务状态： 0 已提交。 1 执行中。 2 回滚中。 3 回滚完成。

gs_undo_dump_record(undoptr bigint)

描述：解析Undo记录。

返回值类型：record

**表10** gs_undo_dump_record参数说明
参数类型	参数名	类型	描述
输入参数	undoptr	bigint	需要解析的Undo记录起始位置。
输出参数	undoptr	bigint	需要解析的Undo记录起始位置。
输出参数	xactid	text	事务ID。
输出参数	cid	text	Command Id。
输出参数	reloid	text	Relation Oid。
输出参数	relfilenode	text	文件的Relfinode。
输出参数	utype	text	Undo记录类型。
输出参数	blkprev	text	同一个块前一条Undo记录的位置。
输出参数	blockno	text	块号。
输出参数	uoffset	text	Undo记录偏移。
输出参数	prevurp	text	前一条Undo记录位置。
输出参数	payloadlen	text	Undo记录数据部分长度。
输出参数	oldxactid	text	前一个事务ID。
输出参数	partitionoid	text	分区Oid。
输出参数	tablespace	text	表空间。
输出参数	alreadyread_bytes	text	读取到的Undo记录长度。
输出参数	prev_undorec_len	text	前一条Undo记录长度。
输出参数	td_id	text	Transaction Directory的ID。
输出参数	reserved	text	Undo 记录中存储的旧版本元组预留标识位。
输出参数	flag	text	Undo 记录中存储的旧版本元组状态标识。
输出参数	flag2	text	Undo 记录中存储的旧版本元组列数。
输出参数	t_hoff	text	Undo记录数据头的长度。

示例（在Undo记录没有被回收的前提下，入参undoptr可以通过gs_undo_translot_dump_slot函数的出参end_undoptr转换为10进制后进行查询）：

gaussdb=# SELECT * FROM gs_undo_dump_record('0000000000000042');
 undoptr |   xactid   | cid | reloid | relfilenode | utype |  blkprev   | blockno | uoffset | prevurp | payloadlen | oldxactid | partitionoid | tablespace | alreadyread_byt
es | prev_undorec_len | td_id | reserved | flag | flag2 | t_hoff
---------+------------+-----+--------+-------------+-------+------------+---------+---------+---------+------------+-----------+--------------+------------+----------------
---+------------------+-------+----------+------+-------+--------
      42 | 1073807360 | 0   | 0      | 108986369   | 0     | 1024786474 | 0       | 0       | 0       | 0          | 0         | 0            | 0          | 36
   | 16390            | -1    | -1       | -1   | -1    | -1
(1 row)

gs_undo_dump_xid(undo_xid xid)

描述：根据xid解析Undo记录。

返回值类型：record

**表11** gs_undo_dump_xid参数说明
参数类型	参数名	类型	描述
输入参数	undo_xid	xid	事务Xid。
输出参数	undoptr	xid	需要解析的Undo记录起始位置。
输出参数	xactid	text	事务ID。
输出参数	cid	text	Command Id。
输出参数	reloid	text	Relation Oid。
输出参数	relfilenode	text	文件的Relfinode。
输出参数	utype	text	Undo记录类型。
输出参数	blkprev	text	同一个块前一条Undo记录的位置。
输出参数	blockno	text	块号。
输出参数	uoffset	text	Undo记录偏移。
输出参数	prevurp	text	前一条Undo记录位置。
输出参数	payloadlen	text	Undo记录数据部分长度。
输出参数	oldxactid	text	前一个事务ID。
输出参数	partitionoid	text	分区Oid。
输出参数	tablespace	text	表空间。
输出参数	alreadyread_bytes	text	读取到的Undo记录长度。
输出参数	prev_undorec_len	text	前一条Undo记录长度。
输出参数	td_id	text	Transaction Directory的ID。
输出参数	reserved	text	Undo 记录中存储的旧版本元组预留标识位。
输出参数	flag	text	Undo 记录中存储的旧版本元组状态标识。
输出参数	flag2	text	Undo 记录中存储的旧版本元组列数。
输出参数	t_hoff	text	Undo记录数据头的长度。

gs_verify_undo_record(type, start_idx，end_idx, location)

描述：校验Undo记录，目前只支持磁盘校验模式。仅支持在业务非运行时执行离线校验，校验之前需要手动执行一次checkpoint落盘操作。

返回值类型：record

**表12** gs_verify_undo_record参数说明
参数类型	参数名	类型	描述
输入参数	type	text	校验类型： 'urp'：校验给定urp区间的所有Undo记录。 'zone'：校验给定Zone区间的所有Zone的所有Undo记录。
输入参数	start_idx	int64	开始位置： 'urp'时，表示起始Undo记录位置。 type为'zone'时，表示起始UndoZone编号。
输入参数	end_idx	int64	结束位置： 'urp'时，表示Undo记录结束位置。 'zone'时，表示结束UndoZone编号。
输入参数	location	bool	0：内存校验。 1：磁盘校验。目前该参数只支持输入为1。
输出参数	zone_id	int64	UndoZone编号。
输出参数	detail	text	校验出错信息。

示例1：校验urp为24的这条Undo记录：

gaussdb=# select * from gs_verify_undo_record('urp', 24, 24, 1);
zone_id | detail
--------+--------
(0 rows)

示例2：若校验urp时输入的urp是错误的，即不是Undo记录起始位置，可能会返回校验结果为空或校验失败：

gaussdb=# select * from gs_verify_undo_record('urp', 35184372173095, 35184372173095, 1);
 zone_id |                            detail
---------+---------------------------------------------------------------
       2 | verification failed: xid is invalid, urp:35184372173095.
(1 row)

示例3：从磁盘中校验zone0到zone2的所有Undo记录：

gaussdb=# select * from gs_verify_undo_record('zone', 0, 2, 1);
zone_id | detail
--------+--------
(0 rows)

调用此视图如有报错，请联系华为工程师处理。

gs_verify_undo_slot(type, start_idx，end_idx, location)

描述：校验Undo事务槽，目前只支持磁盘校验模式。仅支持在业务非运行时执行离线校验，校验之前需要手动执行一次checkpoint落盘操作。

返回值类型：record

**表13** gs_verify_undo_slot参数说明
参数类型	参数名	类型	描述
输入参数	type	text	校验类型： 'zone'：校验给定Zone区间的所有Zone的所有事务槽。
输入参数	start_idx	int64	起始UndoZone编号。
输入参数	end_idx	int64	结束UndoZone编号。
输入参数	location	bool	0：内存校验。 1：磁盘校验。目前该参数只支持输入为1。
输出参数	zone_id	int64	UndoZone编号。
输出参数	detail	text	校验出错信息。

示例：从磁盘中校验zone0到zone2的所有事务槽记录：

gaussdb=# select * from gs_verify_undo_slot('zone', 0, 2, 1);
zone_id | detail
--------+--------
(0 rows)

调用此视图如有报错，请联系华为工程师处理。

gs_verify_undo_meta(type, start_idx，end_idx, location)

描述：校验Undo元信息，目前只支持磁盘校验模式。仅支持在业务非运行时执行离线校验，校验之前需要手动执行一次checkpoint落盘操作。

返回值类型：record

**表14** gs_verify_undo_meta参数说明
参数类型	参数名	类型	描述
输入参数	type	text	校验类型，type只能设置为'all'。 'all'：校验给定Zone区间的所有Zone的所有Meta信息。
输入参数	start_idx	int64	起始UndoZone编号。
输入参数	end_idx	int64	结束UndoZone。
输入参数	location	bool	0：内存校验。 1：磁盘校验。目前该参数只支持输入为1。
输出参数	zone_id	int64	UndoZone编号。
输出参数	detail	text	校验出错信息。

示例：从磁盘中校验zone0到zone2的所有meta信息记录：

gaussdb=# select * from gs_verify_undo_meta('all', 0, 2, 1);
zone_id | detail
--------+--------
(0 rows)

调用此视图如有报错，请联系华为工程师处理。

gs_async_rollback_worker_status()

描述：活跃异步回滚线程状态监控。

返回值类型：record

**表15** gs_async_rollback_worker_status参数说明
参数类型	参数名	类型	描述
输出参数	datid	oid	数据库ID。
输出参数	pid	int64	进程ID。
输出参数	sessionid	int64	会话ID。
输出参数	usesysid	oid	发起该线程的用户ID。
输出参数	state	int32	线程当前状态： 0：未定义。 1：空闲。 2：运行中。
输出参数	rollback_start_time	timestamptz	线程启动时间戳。
输出参数	idx	uint32	异步回滚线程在数组中的下标。
输出参数	xid	uint64	正在回滚的事务Xid。
输出参数	progress	text	该事务的回滚进度（当前已回滚的Undo 记录条数/总 Undo 记录条数，以百分比形式显示）。

gs_async_rollback_xact_status()

描述：异步回滚任务哈希表监控。

返回值类型：record

**表16** gs_async_rollback_xact_status参数说明
参数类型	参数名	类型	描述
输出参数	xid	xid	需要进行异步回滚的事务Xid。
输出参数	start_undoptr	uint64	该事务起始Undo记录指针。
输出参数	end_undoptr	uint64	该事务结束Undo记录指针。
输出参数	dbid	uint32	该事务所在数据库ID。
输出参数	slot_ptr	uint64	该事务对应事务槽的指针。
输出参数	launched	bool	是否有对应的活跃的异步回滚线程。

gs_undo_recycler_status()

描述：异步回收线程状态监控。

返回值类型：record

**表17** gs_undo_recycler_status参数说明
参数类型	参数名	类型	描述
输出参数	datid	oid	数据库ID。
输出参数	pid	int64	进程ID。
输出参数	sessionid	int64	会话ID。
输出参数	usesysid	oid	发起该线程的用户ID。
输出参数	state	int32	线程当前状态： 0：未定义。 1：空闲。 2：运行中。
输出参数	backend_start	timestamptz	线程启动时间戳。
输出参数	total_recycle_time	uint64	总回收时间。
输出参数	max_recycle_time	uint64	最大回收时间。
输出参数	total_recycle_size	uint64	总回收空间。
输出参数	total_recycle_count	uint64	总回收次数。
输出参数	recycle_sleep_count	uint64	睡眠次数。
输出参数	recycle_sleep_time	uint64	睡眠总时间。
输出参数	max_recycle_sleep_time	uint64	最长睡眠时间。
输出参数	last_recycle_timestamp	uint64	上次成功回收时间戳。
输出参数	last_update_global_recycle_xid_timestamp	uint64	globalRecycleXid上次推进时间戳。

gs_undo_launcher_status()

描述：异步回滚发起线程状态监控。

返回值类型：record

**表18** gs_undo_launcher_status参数说明
参数类型	参数名	类型	描述
输出参数	datid	oid	数据库ID。
输出参数	pid	int64	进程ID。
输出参数	sessionid	int64	会话ID。
输出参数	usesysid	oid	发起该线程的用户ID。
输出参数	state	int32	线程当前状态： 0：未定义。 1：空闲。 2：运行中。
输出参数	backend_start	timestamptz	线程启动时间戳。
输出参数	total_async_rollback_task_count	uint64	本节点数据库启动后发起异步回滚任务总个数。
输出参数	average_async_rollback_time	uint64	异步回滚任务平均耗时。
输出参数	max_async_rollback_time	uint64	异步回滚任务最长耗时。
输出参数	min_async_rollback_time	uint64	异步回滚任务最短耗时。

父主题： 系统管理函数

上一篇：其它函数

下一篇：SQL限流函数

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消