查询计划管理的函数参考 - Amazon Aurora
delete_planevolve_plan_baselinesget_explain_planplan_last_usedreloadset_plan_enabledset_plan_statusupdate_plans_last_usedvalidate_plans
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

查询计划管理的函数参考

apg_plan_mgmt 扩展提供以下函数。

apg_plan_mgmt.delete_plan

删除托管计划。

Syntax（语法

apg_plan_mgmt.delete_plan(
    sql_hash,
    plan_hash
)

返回值

如果删除成功则返回 0，如果删除失败则返回 -1。

参数

参数 描述
sql_hash 计划的托管 SQL 语句的 sql_hash ID。
plan_hash 托管计划的 plan_hash ID。

apg_plan_mgmt.evolve_plan_baselines

验证已经批准的计划速度是否更快，或者查询优化程序确定作为最低成本计划的计划是否速度更快。

Syntax（语法

apg_plan_mgmt.evolve_plan_baselines(
    sql_hash, 
    plan_hash,
    min_speedup_factor,
    action
)

返回值

速度比最佳已批准计划要慢的计划数量。

参数

参数 描述
sql_hash 计划的托管 SQL 语句的 sql_hash ID。
plan_hash 托管计划的 plan_hash ID。使用 NULL 表示所有计划具有相同的 sql_hash ID 值。
min_speedup_factor

最低加速系数可能是计划必须比已经批准的最佳计划要快的倍数，达到此数字才能批准计划。或者，此系数可以是比计划必须达到才能拒绝或禁用它的速度慢的倍数。

这是正浮点数值。
action

函数执行的操作。包括下列有效值。大小写没有影响。

  • 'disable' – 禁用不符合最低加速系数的各个匹配计划。

  • 'approve' – 启用满足最低加速系数的各个匹配计划并将其状态设置为 approved。

  • 'reject' – 对于不满足最低加速系数的各个匹配计划，将其状态设置为 rejected。

  • NULL – 函数仅返回由于不满足最低加速系数而没有性能优势的计划数。

使用说明

根据规划加上执行时间是否比最佳已批准计划速度快（达到您设置的系数），将特定计划设置为已批准、已拒绝或已禁用。操作参数可以设置为 'approve' 或 'reject' 以自动批准或拒绝满足性能标准的计划。此外，可以将其设置为 ''（空字符串）以进行性能试验并生成报告，但不采取操作。

您可以避免无目标地为 apg_plan_mgmt.evolve_plan_baselines 函数近期在其中运行的计划重新运行此函数。要这样做，将计划限制为仅近期创建的未批准计划。此外，您可以避免在任何具有近期 apg_plan_mgmt.evolve_plan_baselines 时间戳的已批准计划上运行 last_verified 函数。

开展性能试验，以将各个计划的规划加上执行时间，相对于基线中的其他计划进行比较。部分情况下，某个语句只有一个计划并且该计划已批准。在这种情况下，将计划的规划加上执行时间，与不使用计划时的规划加上执行时间进行比较。

各个计划增加的好处（或坏处）记录在 apg_plan_mgmt.dba_plans 视图的 total_time_benefit_ms 列中。当此值为正数时，有可衡量的性能优势，可以将此计划包括在基线内。

除了收集各个候选计划的规划和执行时间之外，使用 last_verified 来更新 apg_plan_mgmt.dba_plans 视图的 current_timestamp 列。last_verified 时间戳可用于避免对某个最近已经验证了其性能的计划，再次运行此函数。

apg_plan_mgmt.get_explain_plan

为指定的 SQL 语句生成 EXPLAIN 语句文本。

Syntax（语法

apg_plan_mgmt.get_explain_plan(
    sql_hash,
    plan_hash,
    [explainOptionList]
)

返回值

返回指定 SQL 语句的运行时统计数据。使用不带 explainOptionList 以返回一个简单的 EXPLAIN 计划。

参数

参数 描述
sql_hash 计划的托管 SQL 语句的 sql_hash ID。
plan_hash 托管计划的 plan_hash ID。
explainOptionList

逗号分隔的解释选项列表。有效值包括 'analyze'、'verbose'、'buffers'、'hashes' 和 'format json'。如果 explainOptionList 列表为 NULL 或空字符串 ('')，此函数会生成 EXPLAIN 语句，不带任何统计数据。

使用说明

对于 explainOptionList，您可以使用与 EXPLAIN 语句一起使用的任何相同选项。Aurora PostgreSQL 优化器将您为 EXPLAIN 语句提供的选项列表连接在一起，因此您可以请求 EXPLAIN 支持的任何选项。

apg_plan_mgmt.plan_last_used

从共享内存返回指定计划的 last_used 日期。

注意

数据库集群中的主数据库实例上共享内存中的值始终为最新值。该值仅定期刷新到 apg_plan_mgmt.dba_plans 视图的 last_used 列中。

Syntax（语法

apg_plan_mgmt.plan_last_used(
    sql_hash,
    plan_hash
)

返回值

返回 last_used 日期。

参数

参数 描述
sql_hash 计划的托管 SQL 语句的 sql_hash ID。
plan_hash 托管计划的 plan_hash ID。

apg_plan_mgmt.reload

将计划从 apg_plan_mgmt.dba_plans 视图重新加载到共享内存中。

Syntax（语法

apg_plan_mgmt.reload()

返回值

无。

参数

无。

使用说明

对于以下情况，调用 reload：

  • 使用它来立即刷新只读副本的共享内存，而不是等待新计划传播到副本。

  • 在导入托管计划后使用它。

apg_plan_mgmt.set_plan_enabled

启用或禁用托管计划。

Syntax（语法

apg_plan_mgmt.set_plan_enabled(
    sql_hash, 
    plan_hash, 
    [true | false]
)

返回值

如果设置成功则返回 0，如果设置失败则返回 -1。

参数

参数 描述
sql_hash 计划的托管 SQL 语句的 sql_hash ID。
plan_hash 托管计划的 plan_hash ID。
enabled

布尔值 true 或 false：

  • 值为 true 启用计划。

  • 值 false 禁用计划。

apg_plan_mgmt.set_plan_status

将托管计划的状态设置为 Approved、Unapproved、Rejected 或 Preferred。

Syntax（语法

apg_plan_mgmt.set_plan_status(
    sql_hash, 
    plan_hash, 
    status
)

返回值

如果设置成功则返回 0，如果设置失败则返回 -1。

参数

参数 描述
sql_hash 计划的托管 SQL 语句的 sql_hash ID。
plan_hash 托管计划的 plan_hash ID。
status

具有以下值之一的字符串：

  • 'Approved'

  • 'Unapproved'

  • 'Rejected'

  • 'Preferred'

您使用的大小写并不重要，但 apg_plan_mgmt.dba_plans 视图中的状态值设置为首字母大写。有关这些值的更多信息，请参阅 status中的 apg_plan_mgmt.dba_plans 视图参考。

apg_plan_mgmt.update_plans_last_used

立即使用存储在共享内存中的 last_used 日期更新计划表。

Syntax（语法

apg_plan_mgmt.update_plans_last_used()

返回值

无。

参数

无。

使用说明

调用 update_plans_last_used 以确保针对 dba_plans.last_used 列的查询使用最新的信息。如果 last_used 日期不会立即更新，后台进程会使用 last_used 日期每小时更新一次计划表（预设情况下）。

例如，如果具有某个特定 sql_hash 的语句开始运行缓慢，您可以确定自性能下降开始以来为该语句执行了哪些计划。为此，首先将共享内存中的数据刷新到磁盘，使 last_used 日期保持最新，然后查询性能下降的语句的 sql_hash 的所有计划。在查询中，请确保 last_used 日期大于或等于性能下降的开始日期。该查询将标识可能对性能下降负责的计划或一组计划。您可以使用 explainOptionList 被设置为 verbose, hashes 的 apg_plan_mgmt.get_explain_plan。您还可以使用 apg_plan_mgmt.evolve_plan_baselines 分析计划以及任何可能表现更好的替代计划。

update_plans_last_used 函数仅对数据库集群的主数据库实例具有影响。

apg_plan_mgmt.validate_plans

验证优化程序仍可重新创建计划。优化程序将验证 Approved、Unapproved 和 Preferred 计划，而无论是启用还是禁用了此计划。不验证 Rejected 计划。（可选）您可以使用 apg_plan_mgmt.validate_plans 函数来删除或禁用无效计划。

Syntax（语法

apg_plan_mgmt.validate_plans(
    sql_hash, 
    plan_hash, 
    action)
            
apg_plan_mgmt.validate_plans(
    action)

返回值

无效计划的数量。

参数

参数 描述
sql_hash 计划的托管 SQL 语句的 sql_hash ID。
plan_hash 托管计划的 plan_hash ID。使用 NULL 表示同一个 sql_hash ID 值的所有计划。
action

函数为无效计划执行的操作。有效字符串值如下所示。大小写没有影响。

  • 'disable' – 禁用各个无效计划。

  • 'delete' – 删除各个无效计划。

  • 'update_plan_hash' – 更新不能准确重现的计划的 plan_hash ID。该参数还允许您通过重新编写 SQL 来修复计划。然后，您可以将更好的计划注册为初始 SQL 的 Approved 计划。

  • NULL – 函数仅返回无效计划数。不执行其他操作。

  • '' – 空字符串将生成一条消息，指示有效计划和无效计划的数量。

任何其他值作为空字符串处理。

使用说明

使用格式 validate_plans(action) 来验证整个 apg_plan_mgmt.dba_plans 视图中，所有托管语句的所有托管计划。

使用格式 validate_plans(sql_hash, plan_hash, action)，为使用 plan_hash 指定的托管语句，验证以 sql_hash 指定的托管计划。

使用格式 validate_plans(sql_hash, NULL, action) 来验证使用 sql_hash 指定的托管语句的所有托管计划。