# 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用户有权限调用。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - CN之间SQL PATCH不共享，要在各个CN上单独创建。 - 开启负载均衡场景或者需要指定创建的CN的场景，推荐使用[DBE_SQL_UTIL.create_remote_hint_sql_patch]接口进行创建。 - query_string传入EXECUTE语句时，系统会获取当前会话对应的PREPARE语句，并创建SQL PATCH。如果此时没有对应的PREPARE语句，则无效。 表1DBE_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用户有权限调用。 表2DBE_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用户有权限调用。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) query_string传入EXECUTE语句时，系统会获取当前会话对应的PREPARE语句，并创建SQL PATCH。如果此时没有对应的PREPARE语句，则无效。 表3DBE_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用户有权限调用。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - CN之间SQL PATCH不共享，要在各个CN上单独创建。 - 开启负载均衡场景或者需要指定创建的CN的场景，推荐使用[DBE_SQL_UTIL.create_remote_abort_sql_patch]接口进行创建。 - query_string传入EXECUTE语句时，系统会获取当前会话对应的PREPARE语句，并创建SQL PATCH。如果此时没有对应的PREPARE语句，则无效。 表4DBE_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用户有权限调用。 表5DBE_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用户有权限调用。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) query_string传入EXECUTE语句时，系统会获取当前会话对应的PREPARE语句，并创建SQL PATCH。如果此时没有对应的PREPARE语句，则无效。 表6DBE_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用户有权限调用。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - CN之间SQL PATCH不共享，要在各个CN上单独执行。 - 开启负载均衡场景或者需要指定创建的CN的场景，推荐使用[DBE_SQL_UTIL.drop_remote_sql_patch]接口进行删除操作。 表7DBE_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用户有权限调用。 表8DBE_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用户有权限调用。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - CN之间SQL PATCH不共享，要在各个CN上单独执行。 - 开启负载均衡场景或者需要指定创建的CN的场景，推荐使用[DBE_SQL_UTIL.enable_remote_sql_patch]接口进行开启操作。 表9DBE_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用户有权限调用。 表10DBE_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用户有权限调用。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - CN之间SQL PATCH不共享，要在各个CN上单独执行。 - 开启负载均衡场景或者需要指定创建的CN的场景，推荐使用[DBE_SQL_UTIL.disable_remote_sql_patch]接口进行禁用操作。 表11DBE_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用户有权限调用。 表12DBE_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用户有权限调用。 表13DBE_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用户有权限调用。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) 在打开自动参数化，即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); 表14DBE_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 表15DBE_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 | 返回结果为该函数不支持当前形态的提示信息。 |