Aurora PostgreSQL クエリ計画管理の関数リファレンス - Amazon Aurora
copy_outlinedelete_planevolve_plan_baselinesget_explain_planplan_last_used再ロードset_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 以降のリリースで使用できます。

[Syntax] (構文)

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_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

管理計画を削除します。

[Syntax] (構文)

apg_plan_mgmt.delete_plan(
    sql_hash,
    plan_hash
)
戻り値

削除が成功した場合は 0 を返し、削除が失敗した場合は -1 を返します。

パラメータ

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

戻り値

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

パラメータ

Parameter 説明
sql_hash 計画の管理 SQL ステートメントの sql_hash ID。
plan_hash 管理計画の plan_hash ID。同じ sql_hash ID 値を持つすべての計画を意味するために NULL を使用します。
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 関数を実行しないようにすることもできます。

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

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

パラメータ

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

注記

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

[Syntax] (構文)

apg_plan_mgmt.plan_last_used(
    sql_hash,
    plan_hash
)
戻り値

last_used の日付を返します。

パラメータ

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

パラメータ

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

パラメータ

Parameter 説明
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 の日付に即座に更新する。

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

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

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)

戻り値

無効な計画の数です。

パラメータ

Parameter 説明
sql_hash 計画の管理 SQL ステートメントの sql_hash ID。
plan_hash 管理計画の plan_hash ID。同じ sql_hash ID 値のすべての計画を意味するために NULL を使用します。
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 の形式を使用してください。