# Aurora PostgreSQL 查询计划管理的函数参考
<a name="AuroraPostgreSQL.Optimize.Functions"></a>

`apg_plan_mgmt` 扩展提供以下函数。

**Topics**
+ [

## apg\$1plan\$1mgmt.copy\$1outline
](#AuroraPostgreSQL.Optimize.Functions.copy_outline)
+ [

## apg\$1plan\$1mgmt.delete\$1plan
](#AuroraPostgreSQL.Optimize.Functions.delete_plan)
+ [

## apg\$1plan\$1mgmt.evolve\$1plan\$1baselines
](#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines)
+ [

## apg\$1plan\$1mgmt.get\$1explain\$1plan
](#AuroraPostgreSQL.Optimize.Functions.get_explain_plan)
+ [

## apg\$1plan\$1mgmt.plan\$1last\$1used
](#AuroraPostgreSQL.Optimize.Functions.plan_last_used)
+ [

## apg\$1plan\$1mgmt.reload
](#AuroraPostgreSQL.Optimize.Functions.reload)
+ [

## apg\$1plan\$1mgmt.set\$1plan\$1enabled
](#AuroraPostgreSQL.Optimize.Functions.set_plan_enabled)
+ [

## apg\$1plan\$1mgmt.set\$1plan\$1status
](#AuroraPostgreSQL.Optimize.Functions.set_plan_status)
+ [

## apg\$1plan\$1mgmt.update\$1plans\$1last\$1used
](#AuroraPostgreSQL.Optimize.Functions.update_plans_last_used)
+ [

## apg\$1plan\$1mgmt.validate\$1plans
](#AuroraPostgreSQL.Optimize.Functions.validate_plans)

## apg\$1plan\$1mgmt.copy\$1outline
<a name="AuroraPostgreSQL.Optimize.Functions.copy_outline"></a>

将给定的 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\$1sql\$1hash  | 要复制到目标查询的与 plan\$1hash 关联的 sql\$1hash ID。 | 
| source\$1plan\$1hash  | 要复制到目标查询的 plan\$1hash ID。 | 
| target\$1sql\$1hash | 要使用源计划哈希和大纲更新的查询的 sql\$1hash ID。 | 
| target\$1plan\$1hash | 要使用源计划哈希和大纲更新的查询的 plan\$1hash ID。 | 
| force\$1update\$1target\$1plan\$1hash | （可选）即使源计划对 target\$1sql\$1hash 不可重现，查询的 target\$1plan\$1hash ID 也会更新。设置为 True 时，该函数可用于在关系名称和列一致的架构之间复制计划。 | 

**使用说明**：

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

## apg\$1plan\$1mgmt.delete\$1plan
<a name="AuroraPostgreSQL.Optimize.Functions.delete_plan"></a>

删除托管计划。

**语法**

```
apg_plan_mgmt.delete_plan(
    sql_hash,
    plan_hash
)
```

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

**参数**


****  

| 参数 | 描述 | 
| --- | --- | 
| sql\$1hash  | 计划的托管 SQL 语句的 sql\$1hash ID。 | 
| plan\$1hash | 托管计划的 plan\$1hash ID。 | 

 

## apg\$1plan\$1mgmt.evolve\$1plan\$1baselines
<a name="AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines"></a>

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

**语法**

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

**返回值**

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

**参数**


****  

| 参数 | 描述 | 
| --- | --- | 
| sql\$1hash | 计划的托管 SQL 语句的 sql\$1hash ID。 | 
| plan\$1hash | 托管计划的 plan\$1hash ID。使用 NULL 表示所有计划具有相同的 sql\$1hash ID 值。 | 
| min\$1speedup\$1factor |  *最低加速系数*可能是计划必须比已经批准的最佳计划要快的倍数，达到此数字才能批准计划。或者，此系数可以是比计划必须达到才能拒绝或禁用它的速度慢的倍数。 这是正浮点数值。  | 
| action |  函数执行的操作。包括下列有效值。大小写没有影响。 [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html)  | 

**使用说明**

根据规划加上执行时间是否比最佳已批准计划速度快（达到您设置的系数），将特定计划设置为已批准、已拒绝或已禁用。操作参数可以设置为 `'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\$1plan\$1mgmt.get\$1explain\$1plan
<a name="AuroraPostgreSQL.Optimize.Functions.get_explain_plan"></a>

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

**语法**

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

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

**参数**


****  

| 参数 | 描述 | 
| --- | --- | 
| sql\$1hash  | 计划的托管 SQL 语句的 sql\$1hash ID。 | 
| plan\$1hash | 托管计划的 plan\$1hash ID。 | 
| explainOptionList | 逗号分隔的解释选项列表。有效值包括 `'analyze'`、`'verbose'`、`'buffers'`、`'hashes'` 和 `'format json'`。如果 `explainOptionList` 列表为 NULL 或空字符串 ('')，此函数会生成 `EXPLAIN` 语句，不带任何统计数据。  | 

 

**使用说明**

对于 `explainOptionList`，您可以使用与 `EXPLAIN` 语句一起使用的任何相同选项。Aurora PostgreSQL 优化程序将您为 `EXPLAIN` 语句提供的选项列表连接在一起。

## apg\$1plan\$1mgmt.plan\$1last\$1used
<a name="AuroraPostgreSQL.Optimize.Functions.plan_last_used"></a>

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

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

**语法**

```
apg_plan_mgmt.plan_last_used(
    sql_hash,
    plan_hash
)
```

**返回值**  
返回 `last_used` 日期。

**参数**


****  

| 参数 | 描述 | 
| --- | --- | 
| sql\$1hash  | 计划的托管 SQL 语句的 sql\$1hash ID。 | 
| plan\$1hash | 托管计划的 plan\$1hash ID。 | 

 

## apg\$1plan\$1mgmt.reload
<a name="AuroraPostgreSQL.Optimize.Functions.reload"></a>

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

**语法**

```
apg_plan_mgmt.reload()
```

**返回值**

无。

**参数**

无。

**使用说明**

对于以下情况，调用 `reload`：
+ 使用它来立即刷新只读副本的共享内存，而不是等待新计划传播到副本。
+ 在导入托管计划后使用它。



## apg\$1plan\$1mgmt.set\$1plan\$1enabled
<a name="AuroraPostgreSQL.Optimize.Functions.set_plan_enabled"></a>

启用或禁用托管计划。

**语法**

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

**返回值**

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

**参数**


****  

| 参数 | 描述 | 
| --- | --- | 
| sql\$1hash | 计划的托管 SQL 语句的 sql\$1hash ID。 | 
| plan\$1hash | 托管计划的 plan\$1hash ID。 | 
| enabled |  布尔值 true 或 false： [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html)  | 

 

## apg\$1plan\$1mgmt.set\$1plan\$1status
<a name="AuroraPostgreSQL.Optimize.Functions.set_plan_status"></a>

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

**语法**

```
apg_plan_mgmt.set_plan_status(
    sql_hash, 
    plan_hash, 
    status
)
```

**返回值**

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

**参数**


****  

| 参数 | 描述 | 
| --- | --- | 
| sql\$1hash | 计划的托管 SQL 语句的 sql\$1hash ID。 | 
| plan\$1hash | 托管计划的 plan\$1hash ID。 | 
| status |  具有以下值之一的字符串： [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) 您使用的大小写并不重要，但 `apg_plan_mgmt.dba_plans` 视图中的状态值设置为首字母大写。有关这些值的更多信息，请参阅 `status`中的 [Aurora PostgreSQL 兼容版的 apg\$1plan\$1mgmt.dba\$1plans 视图参考](AuroraPostgreSQL.Optimize.dba_plans_view_Reference.md)。  | 

 

## apg\$1plan\$1mgmt.update\$1plans\$1last\$1used
<a name="AuroraPostgreSQL.Optimize.Functions.update_plans_last_used"></a>

立即使用存储在共享内存中的 `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\$1plan\$1mgmt.validate\$1plans
<a name="AuroraPostgreSQL.Optimize.Functions.validate_plans"></a>

验证优化程序仍可重新创建计划。优化程序将验证 `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\$1hash | 计划的托管 SQL 语句的 sql\$1hash ID。 | 
| plan\$1hash | 托管计划的 plan\$1hash ID。使用 NULL 表示同一个 sql\$1hash ID 值的所有计划。 | 
| action |  函数为无效计划执行的操作。有效字符串值如下所示。大小写没有影响。 [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) 任何其他值作为空字符串处理。  | 

**使用说明**

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