# 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是用于创建调优SQL PATCH的接口函数，返回执行是否成功。
  参数：参数介绍请参见[表1]。
  返回值类型：boolean
  限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  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是用于创建调优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_abort_sql_patch(patch_name, unique_sql_id, description, enabled, query_string, is_sql_hash) 描述：create_abort_sql_patch是用于创建SQL异常阻断补丁的接口函数，返回执行是否成功。
  参数：参数介绍请参见[表3]。
  返回值类型：boolean
  限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  query_string传入EXECUTE语句时，系统会获取当前会话对应的PREPARE语句，并创建SQL PATCH。如果此时没有对应的PREPARE语句，则无效。
   表3DBE_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是用于创建SQL异常阻断补丁的接口函数，返回执行是否成功。本函数是原函数的重载函数，支持通过parent_unique_sql_id值限制SQL异常阻断补丁的生效范围。
  参数：参数介绍请参见[表4]。
  返回值类型：boolean
  限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
   表4DBE_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.drop_sql_patch(patch_name) 描述：drop_sql_patch是用于删除SQL PATCH的接口函数，返回执行是否成功。
  参数：参数介绍请参见[表5]。
  返回值类型：boolean
  限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
   表5DBE_SQL_UTIL.drop_sql_patch入参和返回值列表 
  | 参数         | 类型      | 描述         |
  |:---|:---|:---|
  | patch_name | IN name | PATCH名称。 |
  | result      | OUT bool    | 执行是否成功。  |
     
  
- DBE_SQL_UTIL.enable_sql_patch(patch_name) 描述：enable_sql_patch是用于开启SQL PATCH的接口函数，返回执行是否成功。
  参数：参数介绍请参见[表6]。
  返回值类型：boolean
  限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
   表6DBE_SQL_UTIL.enable_sql_patch入参和返回值列表 
  | 参数       | 类型       | 描述       |
  |:---|:---|:---|
  | patch_name | IN name   | PATCH名称。 |
  | result    | OUT bool | 执行是否成功。 |
     
  
- DBE_SQL_UTIL.disable_sql_patch(patch_name) 描述：disable_sql_patch是用于禁用SQL PATCH的接口函数，返回执行是否成功。
  参数：参数介绍请参见[表7]。
  返回值类型：boolean
  限制：仅初始用户、sysadmin、opradmin、monadmin用户有权限调用。
   表7DBE_SQL_UTIL.disable_sql_patch入参和返回值列表 
  | 参数        | 类型       | 描述       |
  |:---|:---|:---|
  | 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的接口函数，返回运行结果。
  参数：参数介绍请参见[表8]。
  返回值类型：record
  限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
   表8DBE_SQL_UTIL.show_sql_patch入参和返回值列表 
  | 参数            | 类型        | 描述                                                                                                                                                                                                                                                                                                                        |
  |:---|:---|:---|
  | patch_name  | IN name  | PATCH名称。                                                                                                                                                                                                                                                                                                                   |
  | unique_sql_id | OUT bigint | 查询全局唯一id。                                                                                                                                                                                                                                                                                                                   |
  | status       | OUT char  | 表示该PATCH是基于Unique SQL ID还是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值。
  参数：参数介绍请参见[表9]。
  返回值类型：int8
  限制：仅初始用户、sysadmin、opradmin和monadmin用户有权限调用。
  ![](https://support.huaweicloud.com/centralized-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);
   表9DBE_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在指定sql_hash、plan_hash和outline均合法时，可打印计划。
  参数：参数介绍请参见[表10]。
  返回值类型：text
  限制：仅sysadmin、opradmin和monadmin用户有权限调用。
  ![](https://support.huaweicloud.com/centralized-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  - 指定的sql_hash必须存在于gs_spm_sql系统表。
  
  - 指定的sql_hash和plan_hash存在于gs_spm_baseline系统表。
  
  - sql_hash对应的SQL语句可以正常执行。
  
  - 对于开启cursor_sharing的场景，仅支持对exact模式下捕获的语句进行计划还原。
  
  - 不支持对存储过程中，带变量的查询语句的计划还原。
  
  - 执行函数时，需要对指定sql_hash对应的查询语句中的对象具有访问权限。
  
  - 还原计划时，不会使用原有指定参数类型。例如，当原SQL为如下语句时：
    ```
    PREPARE p1(text) AS SELECT * FROM t1 WHERE a=$1;
    ```
    
   
   表10DBE_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  | 当前指定查询计划的文本，如果入参无效或非法调用会返回错误提示信息。 |
     
  
 
