# 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 を返します。無効な入力に対して例外をレイズします。

**パラメータ**


****  

| Parameter | 説明 | 
| --- | --- | 
| 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 を返します。

**パラメータ**


****  

| Parameter | 説明 | 
| --- | --- | 
| 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
)
```

**戻り値**

最良の承認済み計画より遅かった計画の数。

**パラメータ**


****  

| Parameter | 説明 | 
| --- | --- | 
| sql\$1hash | 計画の管理 SQL ステートメントの sql\$1hash ID。 | 
| plan\$1hash | 管理計画の plan\$1hash ID。同じ sql\$1hash ID 値を持つすべての計画を意味するために NULL を使用します。 | 
| min\$1speedup\$1factor |  *最小高速化係数*は、計画を承認するために最も速い承認済みの計画よりも速い回数です。または、計画がそれを拒否または無効にするよりも遅い回数を示します。 これは正の浮動値です。  | 
| action |  関数が実行するアクション。有効な値には次のようなものがあります。大文字と小文字は区別されません。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html)  | 

**使用に関する注意事項**

計画と実行時間が、最も速い承認済計画よりも設定可能な要素だけ速いかどうかに基づき指定された計画を承認済み、拒否、または無効に設定します。パフォーマンス基準を満たす計画を自動的に承認または拒否するには、アクションパラメータを `'approve'` または `'reject'` に設定します。あるいは、パフォーマンス実験を実行してレポートを作成するために '' (空の文字列) に設定することもできますが、何も実行されません。

最近実行されたプランに対して `apg_plan_mgmt.evolve_plan_baselines` 関数を無意味に再実行するのを防ぐことができます。そのためには、計画を最近作成された未承認の計画だけに制限します。あるいは、最近の `apg_plan_mgmt.evolve_plan_baselines` タイムスタンプを持つ承認済み計画で `last_verified` 関数を実行しないようにすることもできます。

ベースライン内の他の計画に対して、各計画の計画と実行時間を比較するためのパフォーマンス実験を実行します。場合によっては 1 つのステートメントに対して 1 つの計画しかなく、その計画が承認されます。このような場合は、計画の計画および実行時間、および計画を使用していない計画および実行時間を比較します。

各計画の増分利益 (またはデメリット) は、`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` なしで使用します。

**パラメータ**


****  

| Parameter | 説明 | 
| --- | --- | 
| 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` の日付を共有メモリから返します。

**注記**  
DB クラスター内のプライマリ DB インスタンスの共有メモリ値は、常に最新です。この値は `apg_plan_mgmt.dba_plans` ビューの `last_used` 列に周期的にしかフラッシュされません。

**構文**

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

**戻り値**  
`last_used` の日付を返します。

**パラメータ**


****  

| Parameter | 説明 | 
| --- | --- | 
| 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 を返します。

**パラメータ**


****  

| Parameter | 説明 | 
| --- | --- | 
| 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/ja_jp/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 を返します。

**パラメータ**


****  

| Parameter | 説明 | 
| --- | --- | 
| 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/ja_jp/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` の日付がパフォーマンスリグレッションがスタートされた日付と一緒か、それ以降になるようにしてください。クエリは、パフォーマンスリグレッションの原因の可能性があるプランまたは一連のプランを識別します。`verbose, hashes` に設定された `explainOptionList` で `apg_plan_mgmt.get_explain_plan` を使用することができます。また `apg_plan_mgmt.evolve_plan_baselines` を使用して、より優れたパフォーマンスを得れるかもしれないプランや代行プランを分析することができます。

`update_plans_last_used` 関数は、DB クラスターのプライマリ DB インスタンスにのみ影響します。

## 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)
```

**戻り値**

無効な計画の数です。

**パラメータ**


****  

| Parameter | 説明 | 
| --- | --- | 
| sql\$1hash | 計画の管理 SQL ステートメントの sql\$1hash ID。 | 
| plan\$1hash | 管理計画の plan\$1hash ID。同じ sql\$1hash ID 値のすべての計画を意味するために NULL を使用します。 | 
| action |  関数が無効な計画に実行するアクションです。有効な文字列値は次のとおりです。大文字と小文字は区別されません。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/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` の形式を使用してください。