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

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

SQL工具函数

用于管理SQL PATCH的工具，包括创建、删除、开启、禁用SQL PATCH等系统函数。普通用户只有usage权限，没有CREATE、ALTER、DROP、COMMENT等权限。

具体使用请参见《SQL调优指南》中“使用SQL PATCH进行调优”章节。

DBE_SQL_UTIL.create_hint_sql_patch(patch_name, unique_sql_id, hint_string, description, enabled, query_string, is_sql_hash)

描述：create_hint_sql_patch是用于在当前建立连接的CN上创建调优SQL PATCH的接口函数，返回执行是否成功。

参数：参数介绍请参见表1。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

CN之间SQL PATCH不共享，要在各个CN上单独创建。
开启负载均衡场景或者需要指定创建的CN的场景，推荐使用DBE_SQL_UTIL.create_remote_hint_sql_patch接口进行创建。
query_string传入EXECUTE语句时，系统会获取当前会话对应的PREPARE语句，并创建SQL PATCH。如果此时没有对应的PREPARE语句，则无效。

表1 DBE_SQL_UTIL.create_hint_sql_patch入参和返回值列表
参数	类型	描述
patch_name	IN name	PATCH名称。
unique_sql_id	IN bigint	查询全局唯一id。
hint_string	IN text	Hint文本。
description	IN text	PATCH的备注，默认值为NULL。
enabled	IN bool	PATCH是否生效，默认值为true。
query_string	IN text	SQL HASH对应的原SQL，默认值为NULL。
is_sql_hash	IN bool	PATCH是否是基于SQL HASH创建的，默认值为false。
result	OUT bool	执行是否成功。

DBE_SQL_UTIL.create_hint_sql_patch(patch_name, unique_sql_id, parent_unique_sql_id, hint_string, description, enabled)

描述：create_hint_sql_patch是用于在当前建立连接的CN上创建调优SQL PATCH的接口函数，返回执行是否成功。本函数是原函数的重载函数，支持通过parent_unique_sql_id值限制hint patch的生效范围。

参数：参数介绍请参见表2。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

表2 DBE_SQL_UTIL.create_hint_sql_patch重载函数入参和返回值列表
参数	类型	描述
patch_name	IN name	PATCH名称。
unique_sql_id	IN bigint	查询全局唯一id。
parent_unique_sql_id	IN bigint	标识外层SQL语句的全局唯一id，表示SQL PATCH生效的范围。为0时：表示SQL PATCH仅在外层SQL语句中生效。为非0时：表示SQL PATCH仅在特定的存储过程中生效。
hint_string	IN text	Hint文本。
description	IN text	PATCH的备注，默认值为NULL。
enabled	IN bool	PATCH是否生效，默认值为true。
result	OUT bool	执行是否成功。

DBE_SQL_UTIL.create_remote_hint_sql_patch(node_name, patch_name, unique_sql_id, hint_string, description, enabled, query_string, is_sql_hash)

描述：create_remote_hint_sql_patch是用于指定CN创建调优SQL PATCH的接口函数，返回执行是否成功。

参数：参数介绍请参见表3。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin、monadmin用户有权限调用。

query_string传入EXECUTE语句时，系统会获取当前会话对应的PREPARE语句，并创建SQL PATCH。如果此时没有对应的PREPARE语句，则无效。

表3 DBE_SQL_UTIL.create_remote_hint_sql_patch入参和返回值列表
参数	类型	描述
node_name	IN text	目标节点名，为'ALL'时表示给所有CN节点创建SQL PATCH。
patch_name	IN name	PATCH名称。
unique_sql_id	IN bigint	查询全局唯一id。
hint_string	IN text	Hint文本。
description	IN text	PATCH的备注，默认值为NULL。
enabled	IN bool	PATCH是否生效，默认值为true。
query_string	IN text	SQL HASH对应的原SQL，默认值为NULL。
is_sql_hash	IN bool	是否是基于SQL HASH创建的PATCH，默认值为false。
result	OUT bool	执行是否成功。

DBE_SQL_UTIL.create_abort_sql_patch(patch_name, unique_sql_id, description, enabled, query_string, is_sql_hash)

描述：create_abort_sql_patch是用于在当前建立连接的CN上创建SQL异常阻断补丁的接口函数，返回执行是否成功。

参数：参数介绍请参见表4。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

CN之间SQL PATCH不共享，要在各个CN上单独创建。
开启负载均衡场景或者需要指定创建的CN的场景，推荐使用DBE_SQL_UTIL.create_remote_abort_sql_patch接口进行创建。
query_string传入EXECUTE语句时，系统会获取当前会话对应的PREPARE语句，并创建SQL PATCH。如果此时没有对应的PREPARE语句，则无效。

表4 DBE_SQL_UTIL.create_abort_sql_patch入参和返回值列表
参数	类型	描述
patch_name	IN name	PATCH名称。
unique_sql_id	IN bigint	查询全局唯一id。
description	IN text	PATCH的备注，默认值为NULL。
enabled	IN bool	PATCH是否生效，默认值为true。
query_string	IN text	SQL HASH对应的原SQL，默认值为NULL。
is_sql_hash	IN bool	PATCH是否是基于SQL HASH创建的，默认值为false。
result	OUT bool	执行是否成功。

DBE_SQL_UTIL.create_abort_sql_patch(patch_name, unique_sql_id, parent_unique_sql_id, description, enabled)

描述：create_abort_sql_patch是用于在当前建立连接的CN上创建SQL异常阻断补丁的接口函数，返回执行是否成功。本函数是原函数的重载函数，支持通过parent_unique_sql_id值限制SQL异常阻断补丁的生效范围。

参数：参数介绍请参见表5。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

表5 DBE_SQL_UTIL.create_abort_sql_patch重载函数入参和返回值列表
参数	类型	描述
patch_name	IN name	PATCH名称。
unique_sql_id	IN bigint	查询全局唯一id。
parent_unique_sql_id	IN bigint	标识外层SQL语句的全局唯一id，表示SQL PATCH生效的范围。为0时：表示SQL PATCH仅在外层SQL语句中生效。为非0时：表示SQL PATCH仅在特定的存储过程中生效。
description	IN text	PATCH的备注，默认值为NULL。
enabled	IN bool	PATCH是否生效，默认值为true。
result	OUT bool	执行是否成功。

DBE_SQL_UTIL.create_remote_abort_sql_patch(node_name, patch_name, unique_sql_id, description, enabled, query_string, is_sql_hash)

描述：create_remote_abort_sql_patch是用于指定CN创建SQL异常阻断补丁的接口函数，返回执行是否成功。

参数：参数介绍请参见表6。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

query_string传入EXECUTE语句时，系统会获取当前会话对应的PREPARE语句，并创建SQL PATCH。如果此时没有对应的PREPARE语句，则无效。

表6 DBE_SQL_UTIL.create_remote_abort_sql_patch入参和返回值列表
参数	类型	描述
node_name	IN text	目标节点名，为'ALL'时表示给所有CN节点创建SQL PATCH。
patch_name	IN name	PATCH名称。
unique_sql_id	IN bigint	查询全局唯一id。
description	IN text	PATCH的备注，默认值为NULL。
enabled	IN bool	PATCH是否生效，默认值为true。
query_string	IN text	SQL HASH对应的原SQL，默认值为NULL。
is_sql_hash	IN bool	是否是基于SQL HASH创建的PATCH，默认值为false。
result	OUT bool	执行是否成功。

DBE_SQL_UTIL.drop_sql_patch(patch_name)
描述：drop_sql_patch是用于在当前建立连接的CN上删除SQL PATCH的接口函数，返回执行是否成功。

参数：参数介绍请参见表7。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
- CN之间SQL PATCH不共享，要在各个CN上单独执行。
- 开启负载均衡场景或者需要指定创建的CN的场景，推荐使用DBE_SQL_UTIL.drop_remote_sql_patch接口进行删除操作。
表7 DBE_SQL_UTIL.drop_sql_patch入参和返回值列表

参数

类型

描述

patch_name

IN name

PATCH名称。

result

OUT bool

执行是否成功。

DBE_SQL_UTIL.drop_remote_sql_patch(node_name, patch_name)

描述：drop_remote_sql_patch是用于指定CN删除SQL PATCH的接口函数，返回执行是否成功。

参数：参数介绍请参见表8。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

表8 DBE_SQL_UTIL.drop_remote_sql_patch入参和返回值列表
参数	类型	描述
node_name	IN text	目标节点名。
patch_name	IN name	PATCH名称。
result	OUT bool	执行是否成功。

DBE_SQL_UTIL.enable_sql_patch(patch_name)
描述：enable_sql_patch是用于在当前建立连接的CN上开启SQL PATCH的接口函数，返回执行是否成功。

参数：参数介绍请参见表9。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
- CN之间SQL PATCH不共享，要在各个CN上单独执行。
- 开启负载均衡场景或者需要指定创建的CN的场景，推荐使用DBE_SQL_UTIL.enable_remote_sql_patch接口进行开启操作。
表9 DBE_SQL_UTIL.enable_sql_patch入参和返回值列表

参数

类型

描述

patch_name

IN name

PATCH名称。

result

OUT bool

执行是否成功。

DBE_SQL_UTIL.enable_remote_sql_patch(node_name, patch_name)

描述：enable_remote_sql_patch是用于指定CN开启SQL PATCH的接口函数，返回执行是否成功。

参数：参数介绍请参见表10。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

**表10** DBE_SQL_UTIL.enable_remote_sql_patch入参和返回值列表
参数	类型	描述
node_name	IN text	目标节点名。
patch_name	IN name	PATCH名称。
result	OUT bool	执行是否成功。

DBE_SQL_UTIL.disable_sql_patch(patch_name)
描述：disable_sql_patch是用于在当前建立连接的CN上禁用SQL PATCH的接口函数，返回执行是否成功。

参数：参数介绍请参见表11。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
- CN之间SQL PATCH不共享，要在各个CN上单独执行。
- 开启负载均衡场景或者需要指定创建的CN的场景，推荐使用DBE_SQL_UTIL.disable_remote_sql_patch接口进行禁用操作。
表11 DBE_SQL_UTIL.disable_sql_patch入参和返回值列表

参数

类型

描述

patch_name

IN name

PATCH名称。

result

OUT bool

执行是否成功。

DBE_SQL_UTIL.disable_remote_sql_patch(node_name, patch_name)

描述：disable_remote_sql_patch是用于指定CN禁用SQL PATCH的接口函数，返回执行是否成功。

参数：参数介绍请参见表12。

返回值类型：boolean

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

**表12** DBE_SQL_UTIL.disable_remote_sql_patch入参和返回值列表
参数	类型	描述
node_name	IN text	目标节点名。
patch_name	IN name	PATCH名称。
result	OUT bool	执行是否成功。

DBE_SQL_UTIL.show_sql_patch(patch_name, unique_sql_id, status, enabled, abort)

描述：show_sql_patch是用于显示给定patch_name所对应的SQL PATCH的接口函数，返回运行结果。

参数：参数介绍请参见表13。

返回值类型：record

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

**表13** DBE_SQL_UTIL.show_sql_patch入参和返回值列表
参数	类型	描述
patch_name	IN name	PATCH名称。
unique_sql_id	OUT bigint	查询全局唯一id。
status	OUT char	表示该PATCH是基于SQL ID还是Unique SQL HASH创建的。 'd'：表示Unique SQL ID。 'h'：表示SQL HASH。
enabled	OUT bool	PATCH是否生效。
abort	OUT bool	是否是AbortHint。
hint_str	OUT text	Hint文本。

DBE_SQL_UTIL.sqlpatch_query_hash(query_string, need_validate)

描述：sqlpatch_query_hash是一个用于获取SQL对应SQL HASH的接口函数，返回传入SQL对应的HASH值。

参数：参数介绍请参见表14。

返回值类型：int8

限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。

在打开自动参数化，即cursor_sharing参数取值为force时，SQL HASH是基于参数化后的SQL文本计算的，使用sqlpatch_query_hash应该传入参数化后的SQL文本，并传入need_validate参数为false，得到自动参数化后的SQL HASH。例如：SELECT DBE_SQL_UTIL.sqlpatch_query_hash('SELECT * FROM t WHERE a = ?', false);

**表14** DBE_SQL_UTIL.sqlpatch_query_hash函数入参和返回值列表
参数	类型	描述
query_string	IN text	SQL文本。
need_validate	IN boolean	用于控制是否进行语法校验。
result	OUT bigint	传入SQL文本对应的HASH值。

DBE_SQL_UTIL.gs_show_plan_by_hash(sql_hash, plan_hash)

描述：当前版本中，若使用gs_show_plan_by_hash函数，会返回该函数不支持当前形态的提示信息。

参数：参数介绍请参见表15。

返回值类型：text

**表15** DBE_SQL_UTIL.gs_show_plan_by_hash入参和返回值列表
参数	类型	描述
sql_hash	IN bigint	SQL文本的hash值。
plan_hash	IN bigint	SQL计划的hash值。
gs_show_plan_by_hash	OUT text	返回结果为该函数不支持当前形态的提示信息。

父主题： 函数和操作符

上一篇：SQL限流函数

下一篇：多租数据库函数

SQL工具函数

相关文档

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