Aurora PostgreSQL 查询计划管理的函数参考 - Amazon Aurora
copy_outlinedelete_planevolve_plan_baselinesget_explain_planplan_last_usedreloadset_plan_enabledset_plan_statusupdate_plans_last_usedvalidate_plans

Aurora PostgreSQL 查询计划管理的函数参考

apg_plan_mgmt 扩展提供以下函数。

apg_plan_mgmt.copy_outline

将给定的 SQL 计划哈希和计划大纲复制到目标 SQL 计划哈希和大纲，从而覆盖目标的计划哈希和大纲。此功能在 apg_plan_mgmt 2.3 及更高版本中可用。

语法

apg_plan_mgmt.copy_outline(
    source_sql_hash,
    source_plan_hash,
    target_sql_hash,
    target_plan_hash,
    force_update_target_plan_hash
)
返回值

复制成功时返回 0。对于无效输入引发异常。

参数

参数 描述
source_sql_hash 要复制到目标查询的与 plan_hash 关联的 sql_hash ID。
source_plan_hash 要复制到目标查询的 plan_hash ID。
target_sql_hash 要使用源计划哈希和大纲更新的查询的 sql_hash ID。
target_plan_hash 要使用源计划哈希和大纲更新的查询的 plan_hash ID。
force_update_target_plan_hash （可选）即使源计划对 target_sql_hash 不可重现，查询的 target_plan_hash ID 也会更新。设置为 True 时，该函数可用于在关系名称和列一致的架构之间复制计划。

使用说明

此函数允许您将使用提示的计划哈希和计划大纲复制到其他类似语句，从而无需在目标语句中每次出现时都使用内联提示语句。如果更新的目标查询导致计划无效，则此函数会引发错误并回滚尝试的更新。

apg_plan_mgmt.delete_plan

删除托管计划。

语法

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

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

语法

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 语句文本。

语法

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 语句提供的选项列表连接在一起。

apg_plan_mgmt.plan_last_used

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

注意

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

语法

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 视图重新加载到共享内存中。

语法

apg_plan_mgmt.reload()

返回值

无。

参数

无。

使用说明

对于以下情况，调用 reload：

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

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

apg_plan_mgmt.set_plan_enabled

启用或禁用托管计划。

语法

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。

语法

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中的 Aurora PostgreSQL 兼容版的 apg_plan_mgmt.dba_plans 视图参考。

apg_plan_mgmt.update_plans_last_used

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

语法

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 函数来删除或禁用无效计划。

语法

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 指定的托管语句的所有托管计划。