更新时间:2025-05-29 GMT+08:00

SPM计划管理函数

GS_SPM_EVOLUTE_PLAN(sql_hash, plan_hash)

描述:GS_SPM_EVOLUTE_PLAN属于DBE_SQL_UTIL schema,是SPM特性用于计划演进的接口函数。只要该计划基线相关的表存在,就可以对该计划基线进行演进。

参数:表1所示。

表1 GS_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所示。

表2 GS_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所示。

表3 GS_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所示。

表4 GS_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所示。

表5 GS_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所示。

表6 GS_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所示。

表7 GS_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所示

表8 GS_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所示。

表9 GS_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)