本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 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。引發無效輸入的例外狀況。

**參數**


****  

| 參數 | Description | 
| --- | --- | 
| source\$1sql\$1hash  | 與要複製到目標查詢之 plan\$1hash 相關聯的 sql\$1hash ID。 | 
| source\$1plan\$1hash  | 要複製到目標查詢的 plan\$1hash ID。 | 
| target\$1sql\$1hash | 要使用來源計畫雜湊和大綱更新之查詢的 sql\$1hash 識別符。 | 
| target\$1plan\$1hash | 要使用來源計畫雜湊和大綱更新之查詢的 plan\$1hash 識別符。 | 
| 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.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html)  | 

**使用須知**

根據規劃時間加上執行時間比最佳已核准計劃更快的程度是否達到一個可設定的因素，而將指定的計劃設為已核准、已拒絕或已停用。action 參數可能設為 `'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.aws.amazon.com/zh_tw/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.aws.amazon.com/zh_tw/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` 日期大於或等於效能回歸開始的日期。此查詢會識別可能負責效能回歸的計劃或計劃集。您可以使用 `apg_plan_mgmt.get_explain_plan` 與設為 `verbose, hashes` 的 `explainOptionList` 搭配。您也可以使用 `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.aws.amazon.com/zh_tw/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` 指定的受管陳述式，驗證所有受管計劃。