# SPM计划管理函数 #### GS_SPM_EVOLUTE_PLAN(sql_hash, plan_hash) **描述：**GS_SPM_EVOLUTE_PLAN属于DBE_SQL_UTIL schema，是SPM特性用于计划演进的接口函数。只要该计划基线相关的表存在，就可以对该计划基线进行演进。 **参数：** 如[表1]所示。 表1GS_SPM_EVOLUTE_PLAN入参和返回值列表 | 参数 | 类型 | 描述 | 取值范围 | |:---|:---|:---|:---| | sql_hash | IN bigint | SQL文本的hash值。 | - | | plan_hash | IN bigint | SQL计划outline文本的hash值。 | - | | evolute_status | OUT boolean | 演进行为是否正常完成：t表示正常；异常会报错。 | t/f | **返回值类型：**boolean **示例：** ``` gaussdb=# SELECT * FROM dbe_sql_util.gs_spm_evolute_plan(107760189, 2284373089); evolute_status ---------------- t (1 row) ``` #### GS_SPM_SET_PLAN_STATUS(sql_hash, plan_hash, plan_status) **描述：**GS_SPM_SET_PLAN_STATUS属于DBE_SQL_UTIL schema，它是SPM特性用于修改baseline状态的接口函数。 **参数** ：如[表2]所示。 表2GS_SPM_SET_PLAN_STATUS入参和返回值列表 | 参数 | 类型 | 描述 | 取值范围 | |:---|:---|:---|:---| | sql_hash | IN bigint | SQL文本的hash值。 | - | | plan_hash | IN bigint | SQL计划outline文本的hash值。 | - | | plan_status | IN text | 计划的状态。 | - ACC：表示已经接受的计划。 - UNACC：表示未接受的计划。 - FIXED：一种特殊的ACC状态的计划，计划的匹配优先级高于ACC状态的计划。 | | execute_status | OUT boolean | 修改计划状态行为是否正常完成：t表示正常；异常会报错。 | t/f | **返回值类型**：boolean **示例：** ``` gaussdb=# SELECT dbe_sql_util.gs_spm_set_plan_status(sql_hash, plan_hash, 'ACC') FROM gs_spm_sql_baseline where outline like '%BitmapScan%'; gs_spm_set_plan_status ------------------------ t (1 row) ``` #### GS_SPM_DISPLAY_PLANS(sql_hash) **描述：**GS_SPM_DISPLAY_PLANS属于DBE_SQL_UTIL schema，它是SPM特性用于查看单条SQL所有baseline的接口函数。 **参数：** 如[表3]所示。 表3GS_SPM_DISPLAY_PLANS入参和返回值列表 | 参数 | 类型 | 描述 | 取值范围 | |:---|:---|:---|:---| | sql_hash | IN bigint | SQL的唯一标识。 | - | | sql_hash | OUT bigint | SQL文本的hash值。 | - | | plan_hash | OUT bigint | SQL计划outline文本的hash值。 | - | | outline | OUT text | 当前计划对应outline的所有Hint的组合字符串。 | - | | cost | OUT double | 当前计划的代价。 | - | | status | OUT text | 当前计划的状态。 | - ACC：表示已经接受的计划。 - UNACC：表示未接受的计划。 - FIXED：一种特殊的ACC状态的计划，计划的匹配优先级高于ACC状态的计划。 | | gplan | OUT boolean | 当前计划是否是gplan。t表示是gplan；异常会报错。 | t/f | **返回值类型：**bigint, text, double, text, boolean **示例**： ``` select sql_hash, plan_hash, outline, status, gplan from dbe_sql_util.gs_spm_display_plans(107760189) order by status, outline; sql_hash | plan_hash | outline | status | gplan -----------+------------+------------------------------------------------+--------+------- 107760189 | 2519317082 | begin_outline_data +| ACC | f | | IndexScan(@"sel$1" tb_a@"sel$1" tb_a_idx_c1) +| | | | version("1.0.0") +| | | | end_outline_data | | 107760189 | 2686653876 | begin_outline_data +| UNACC | f | | BitmapScan(@"sel$1" tb_a@"sel$1" tb_a_idx_c1)+| | | | version("1.0.0") +| | | | end_outline_data | | 107760189 | 2284373089 | begin_outline_data +| UNACC | f | | TableScan(@"sel$1" tb_a@"sel$1") +| | | | version("1.0.0") +| | | | end_outline_data | | (3 rows) ``` #### GS_SPM_RELOAD_PLAN(sql_hash，plan_hash) **描述：**GS_SPM_RELOAD_PLAN属于DBE_SQL_UTIL schema，它是SPM特性用于加载baseline系统表中某baseline到SPM global cache中的接口函数。 **参数：** 如[表4]所示。 表4GS_SPM_RELOAD_PLAN入参和返回值列表 | 参数 | 类型 | 描述 | 取值范围 | |:---|:---|:---|:---| | sql_hash | IN bigint | SQL文本的hash值。 | - | | plan_hash | IN bigint | SQL计划outline文本的hash值。 | - | | execute_status | OUT boolean | baseline的加载行为是否正常完成：t表示正常；异常会报错。 | t/f | **返回值类型：**boolean **示例：** ``` SELECT dbe_sql_util.gs_spm_reload_plan(sql_hash, plan_hash) from gs_spm_sql_baseline where outline like '%IndexScan%'; gs_spm_reload_plan -------------------- t (1 row) ``` #### GS_SPM_VALIDATE_PLAN(sql_hash, plan_hash) **描述**：GS_SPM_VALIDATE_PLAN属于DBE_SQL_UTIL schema，它是SPM特性用于计划可用性验证的接口函数。 **参数：** 如[表5]所示。 表5GS_SPM_VALIDATE_PLAN入参和返回值列表 | 参数 | 类型 | 描 | 取值范围 | |:---|:---|:---|:---| | sql_hash | IN bigint | SQL文本的hash值。 | - | | plan_hash | IN bigint | SQL计划outline文本的hash值。 | - | | execute_status | OUT boolean | 被验证的计划是否可用： t：被验证的计划可用；f: 被验证的计划不可用 | t/f | **返回值类型**：boolean **示例：** ``` SELECT dbe_sql_util.gs_spm_validate_plan(sql_hash, plan_hash) FROM gs_spm_sql_baseline WHERE outline LIKE '%IndexScan%'; gs_spm_validate_plan ---------------------- f (1 row) ``` #### GS_SPM_DELETE_PLAN(sql_hash, plan_hash) **描述：**GS_SPM_DELETE_PLAN属于DBE_SQL_UTIL schema，它是SPM特性用于计划删除baseline的接口函数。若该函数在执行期间异常中止，可能会导致gs_spm_baseline表中记录数超出GUC参数spm_plan_capture_max_plannum指定的数量。 **参数：** 如[表6]所示。 表6GS_SPM_DELETE_PLAN入参和返回值列表 | 参数 | 类型 | 描述 | 取值范围 | |:---|:---|:---|:---| | sql_hash | IN bigint | SQL文本的hash值。 | - | | plan_hash | IN bigint | SQL计划outline文本的hash值。 | - | | execute_status | OUT boolean | 计划删除行为是否正常完成：t表示正常；异常会报错。 | t/f | **返回值类型：**boolean **示例：** ``` SELECT dbe_sql_util.gs_spm_delete_plan(sql_hash, plan_hash) FROM gs_spm_sql_baseline WHERE outline LIKE '%IndexScan%'; gs_spm_delete_plan -------------------- t (1 row) ``` #### GS_SPM_GET_PLAN_HISTORY(sql_input_hash, history_time) **描述：**GS_SPM_GET_PLAN_HISTORY属于DBE_SQL_UTIL Schema，它是SPM特性用于查看指定查询语句在某个给定历史时间点之前的所有历史计划。 **参数：** 如[表7]所示。 表7GS_SPM_GET_PLAN_HISTORY入参和返回值列表 | 参数 | 类型 | 描述 | 取值范围 | |:---|:---|:---|:---| | sql_input_hash | IN bigint | SQL文本的hash值。 | - | | history_time | IN timestamp with time zone | 指定的历史时间点。 | - | | sql_hash | OUT bigint | SQL文本的hash值。 | - | | plan_hash | OUT bigtint | SQL计划outline文本的hash值。 | - | | outline | OUT text | 当前计划对应outline的所有Hint的组合字符串。 | - | | plan_status | OUT text | 当前计划的状态。 | - ACC：表示已经接受的计划。 - UNACC：表示未接受的计划。 - FIXED：一种特殊的ACC状态的计划，计划的匹配优先级高于ACC状态的计划。 | | gplan | OUT boolean | 当前计划是否是gplan。t表示是gplan；异常会报错。 | t/f | | cost | OUT double | 当前计划的代价。 | - | | sql_text | OUT text | SQL文本。 | - | | param_num | OUT integer | SQL的参数数量。 | - | | source | OUT text | baseline的来源。 | - AUTO：表示该基线由AUTO模式捕获。 - MANUAL：表示该基线由MANUAL模式捕获。 - STORE：表示该基线由STORE模式捕获。 | | history_creation_time | OUT timestamp with time zone | 跳变历史创建的时间。 | - | | invalid | OUT boolean | 当前baseline是否无效。 | t/f | **返回值类型：**record **示例：** ``` gaussdb=# SELECT dbe_sql_util.gs_spm_get_plan_history(sql_hash, creation_time + 1) FROM pg_catalog.gs_spm_plan_history WHERE sql_hash IN (SELECT sql_hash FROM pg_catalog.gs_spm_baseline WHERE sql_namespace = get_schema_oid(CURRENT_SCHEMA::cstring)); -[ RECORD 1 ]-----------+--------------------------------------------------------------------------------------------------------------------------------------- gs_spm_get_plan_history | (812490094,1950233227," begin_outline_data | TableScan(@""sel$1"" test_spm_gplan_change_perception.test_spm_perception_t1@""sel$1"") | version(""1.0.0"") | end_outline_data",UNACC,t,180,"select * from test_spm_perception_t1 where a = $1",1,STORE,10,"Mon Jan 13 06:04:22.614726 2025 PST",f) (4 rows) ``` #### GS_SPM_ACCEPT_HISTORICAL_PLAN(sql_input_hash, history_time, plan_status) **描述：**GS_SPM_ACCEPT_HISTORICAL_PLAN属于DBE_SQL_UTIL schema，它是SPM特性用于设置执行查询语句在某个时间点之前最新一条的历史计划状态为指定状态。 **参数：** 如[表8]所示 表8GS_SPM_ACCEPT_HISTORICAL_PLAN入参和返回值列表 | 参数 | 类型 | 描述 | 取值范围 | |:---|:---|:---|:---| | sql_input_hash | IN bigint | SQL文本的hash值。 | - | | history_time | IN bigint | 指定的历史时间点。 | - | | plan_status | IN text | 计划的状态。 | - ACC：表示已经接受的计划。 - FIXED：一种特殊的ACC状态的计划，计划的匹配优先级高于ACC状态的计划。 | | plan_hash_previous | OUT bigint | 被设置的计划outline文本的hash值。 | - | **返回值类型：**bigint **示例：** ``` gaussdb=# SELECT dbe_sql_util.gs_spm_accept_historical_plan(sql_hash, creation_time + 1, 'ACC') FROM gs_spm_plan_history where sql_hash IN (SELECT sql_hash FROM pg_catalog.gs_spm_baseline WHERE sql_namespace = get_schema_oid(CURRENT_SCHEMA::cstring)); gs_spm_accept_historical_plan ------------------------------- 602237302 (1 row) ``` #### GS_SPM_DELETE_PLAN_HISTORY(sql_hash, plan_hash, plan_hash_previous, userid, creation_time) **描述：**GS_SPM_DELETE_PLAN_HISTORY属于DBE_SQL_UTIL schema，它是SPM特性用于从PG_CATALOG.GS_SPM_PLAN_HISTORY中删除指定记录。 **参数：** 如[表9]所示。 表9GS_SPM_DELETE_PLAN_HISTORY入参和返回值列表 | 参数 | 类型 | 描述 | |:---|:---|:---| | sql_hash | IN bigint | SQL文本的hash值。 | | plan_hash | IN bigint | SQL计划outline文本的hash值。 | | plan_hash_previous | IN bigint | 上一次使用的计划outline文本的hash值。 | | userid | IN oid | 用户的oid。 | | creation_time | IN timestamp with time zone | 跳变历史创建的时间。 | | delete_count | OUT bigint | 被删除历史的个数。 | **返回值类型：**bigint **示例：** ``` gaussdb=# SELECT dbe_sql_util.gs_spm_delete_plan_history(sql_hash, plan_hash, plan_hash_previous, userid, creation_time) FROM pg_catalog.gs_spm_plan_history WHERE sql_hash IN (SELECT sql_hash FROM pg_catalog.gs_spm_baseline WHERE sql_namespace = get_schema_oid(CURRENT_SCHEMA::cstring)); gs_spm_delete_plan_history ---------------------------- 1 (1 row) ```