148 DBMS_SPM

DBMS_SPMパッケージは、様々なSQL文に対して保持される、計画履歴およびSQL計画のベースラインに対する制御された操作を実行するためのインタフェースを、DBAおよびその他のユーザーに提供することによって、SQL計画管理機能をサポートします。

関連項目: 詳細は、『Oracle Database SQLチューニング・ガイド』のSQL計画管理の使用方法に関する項を参照してください。

この章では、次の項目について説明します。

• DBMS_SPMの使用方法

  • 概要

  • セキュリティ・モデル

  • 定数

  • 例

• データ構造

• DBMS_SPMサブプログラムの要約

DBMS_SPMの使用方法

• 概要

• セキュリティ・モデル

• 定数

• 例

概要

DBMS_SPMパッケージを使用すると、ユーザーはSQL計画管理を使用して、SQL実行計画を管理できます。SQL計画管理は、長期間にわたってSQL文の実行計画を記録し評価することで、SQL文の実行計画の突然の変更によってパフォーマンスが低下するのを防止し、効果的であることが判明している既存の計画セットで構成されるSQL計画ベースラインを作成します。次にSQL計画ベースラインを使用して、システムで発生する変更とは無関係に、対応するSQL文のパフォーマンスを保持します。SQL計画管理がSQLのパフォーマンスを向上または保持する一般的な使用のシナリオには次のようなものがあります。

• 新しいバージョンのオプティマイザをインストールするデータベースのアップグレードにより、通常わずかな割合のSQL文に対して計画が変更され、計画の変更のほとんどでパフォーマンスの変更も向上も発生しません。ただし、一部の計画変更はパフォーマンスの低下の原因になる場合があります。SQL計画ベースラインを使用すると、データベースのアップグレードが原因でパフォーマンスの低下が発生する可能性は大幅に減少します。

• 継続的なシステムおよびデータの変更は一部のSQL文の計画に影響を与え、パフォーマンスの低下の原因になる場合があります。SQL計画ベースラインを使用すると、パフォーマンスの低下が最小限に抑えられ、SQLのパフォーマンスが安定します。

• 新しいアプリケーション・モジュールをデプロイメントすることは、システムに新しいSQL文を導入することを意味します。アプリケーション・ソフトウェアは、新しいSQL文の標準テスト構成で開発された適切なSQL実行計画を使用できます。システムの本番構成がテスト構成と大幅に異なる場合は、パフォーマンスを向上するために時間をかけてSQL計画ベースラインを進化させることができます。

セキュリティ・モデル

このパッケージの所有者はSYSです。パッケージのプロシージャを実行するには、EXECUTEパッケージ権限が必要です。ADMINISTER SQL MANAGEMENT OBJECT権限を付与されているすべてのユーザーがDBMS_SPMパッケージを実行できます。

定数

DBMS_SPMパッケージでは、表148-1「DBMS_SPMの定数」に示す定数が使用されます。これらの定数は、EVOLVE_SQL_PLAN_BASELINEファンクションのtime_limitパラメータの標準入力として定義されます。

表148-1 DBMS_SPMの定数

定数	タイプ	値	説明
AUTO_LIMIT	INTEGER	2147483647	EVOLVE_SQL_PLAN_BASELINEファンクションにより費やされる適切な時間が判断されます。
NO_LIMIT	INTEGER	2147483647 -1	EVOLVE_SQL_PLAN_BASELINEファンクションにより費やされる時間に制限はありません。

例

詳細な例は、次のトピックの下にあります。

• ストアド・アウトラインのSQL計画ベースラインへの移行

• SQL計画管理機能を使用するためにアウトラインを移行

• ストアド・アウトライン動作を保持するためにアウトラインを移行

• ストアド・アウトラインの移行後にフォローアップ・タスクを実行

データ構造

DBMS_SPMパッケージは、TABLEタイプを定義します。

表タイプ

• NAMELIST表タイプ

NAMELIST表タイプ

このタイプでは入力パラメータとして名前のリストが使用できます。

構文

TYPE  name_list  IS TABLE OF VARCHAR2(30);

DBMS_SPMサブプログラムの要約

次の表に、このパッケージのサブプログラムをアルファベット順に示します。

表148-2 DBMS_SPMパッケージのサブプログラム

サブプログラム	説明
ACCEPT_SQL_PLAN_BASELINEプロシージャ	進化タスクのリコメンデーションに基づいて計画を受け入れます。
ALTER_SQL_PLAN_BASELINEファンクション	属性名/値の形式でSQL文と関連付けられている1つまたはすべての計画の属性を変更します。
CANCEL_EVOLVE_TASKプロシージャ	現在実行中の進化タスクを取り消します。
CONFIGUREプロシージャ	パラメータ/値の形式でSQL管理ベースの構成オプションを設定します。
CREATE_EVOLVE_TASKファンクション	アドバイザのタスクを作成し、そのパラメータを設定します。
CREATE_STGTAB_BASELINEプロシージャ	システム間でのSQL計画ベースラインの転送に使用するステージング表を作成します。
DROP_EVOLVE_TASKプロシージャ	進化したタスクを削除します。
DROP_SQL_PLAN_BASELINEファンクション	SQL文に関連付けられている1つまたはすべての計画を削除します。
EVOLVE_SQL_PLAN_BASELINEファンクション	1つ以上のSQL文に関連付けられているSQL計画ベースラインを進化させます。
EXECUTE_EVOLVE_TASKファンクション	以前に作成した進化タスクを実行します。
IMPLEMENT_EVOLVE_TASKファンクション	進化タスクのリコメンデーションに基づいて計画を実装します。
INTERRUPT_EVOLVE_TASKプロシージャ	現在実行中の進化タスクを中断します。
LOAD_PLANS_FROM_CURSOR_CACHEファンクション	SQL文のカーソル・キャッシュに存在する1つ以上の計画をロードします。
LOAD_PLANS_FROM_SQLSETファンクション	SQLチューニング・セット(STS)に保存されている計画をSQL計画ベースラインにロードします。
MIGRATE_STORED_OUTLINEファンクション	既存のストアド・アウトラインをSQL計画ベースラインに移行します。
PACK_STGTAB_BASELINEファンクション	SQL管理ベースからステージング表にSQL計画ベースラインをパック(エクスポート)します。
RESET_EVOLVE_TASKプロシージャ	進化タスクを初期状態にリセットします。
RESUME_EVOLVE_TASKプロシージャ	以前に中断したタスクを再開します。
REPORT_AUTO_EVOLVE_TASKファンクション	自動進化タスクの実行結果を表示します。
REPORT_EVOLVE_TASKファンクション	進化したタスクの結果を表示します。
SET_EVOLVE_TASK_PARAMETERプロシージャ	進化タスクのパラメータを設定します。
UNPACK_STGTAB_BASELINEファンクション	ステージング表からSQL管理ベースにSQL計画ベースラインをアンパック(インポート)します。

ACCEPT_SQL_PLAN_BASELINEプロシージャ

このプロシージャは、進化タスクのリコメンデーションに基づいて計画を受け入れます。

構文

DBMS_SPM.ACCEPT_SQL_PLAN_BASELINE  (
   task_name       IN  VARCHAR2,
   object_id       IN  NUMBER    := NULL,
   task_owner      IN  VARCHAR2  := NULL,
   force           IN  BOOLEAN   := FALSE);

パラメータ

表148-3 ACCEPT_SQL_PLAN_BASELINEプロシージャのパラメータ

パラメータ	説明
task_name	実装するタスクの識別子。
object_id	単一の計画を表すアドバイザ・フレームワーク・オブジェクトの識別子。NULLの場合、すべてのオブジェクトに対してレポートが生成されます。
task_owner	進化タスクの所有者。デフォルトは、現行のスキーマ所有者です。
force	アドバイザがそのようなアクションを推奨しなかった場合でも計画を受け入れます。デフォルトはFALSEです。検証済で、メリットの向上を十分に見込める場合にのみ計画を受け入れることを要求します。

ALTER_SQL_PLAN_BASELINEファンクション

このファンクションは、属性名/値の形式でSQL文と関連付けられている1つまたはすべての計画の属性を変更します。

構文

DBMS_SPM.ALTER_SQL_PLAN_BASELINE (
   sql_handle        IN VARCHAR2 := NULL,
   plan_name         IN VARCHAR2 := NULL,
   attribute_name    IN VARCHAR2,
   attribute_value   IN VARCHAR2)
 RETURN PLS_INTEGER;

パラメータ

表148-4 ALTER_SQL_PLAN_BASELINEファンクションのパラメータ

パラメータ	説明
sql_handle	SQL文のハンドル。属性変更のためにSQL文に関連付けられている計画を識別します。NULLの場合は、plan_nameを指定する必要があります。
plan_name	計画名。特定の計画を識別します。デフォルトのNULLにすると、sql_handleで識別されるSQL文に関連付けられているすべての計画の属性が設定されます。NULLの場合は、sql_handleを指定する必要があります。
attribute_name	設定する計画属性の名前(次の表を参照)。
attribute_value	設定する計画属性の値(次の表を参照)。

表148-5 ALTER_SQL_PLAN_BASELINEファンクションのパラメータの名前および値

名前	説明	設定可能な値
enabled	'YES'にすると、計画をオプティマイザで使用できます。これが使用されるかどうかは、acceptedステータスによって決まります。	'YES'または'NO'
fixed	'YES'にすると、時間が経過してもSQL計画ベースラインは進化しません。固定された計画は、固定されていない計画より優先されます。	'YES'または'NO'
autopurge	'YES'にすると、計画は特定の期間使用されない場合にパージされます。'NO'にすると、計画はパージされません。	'YES'または'NO'
plan_name	計画の名前。	最大30文字の文字列
description	計画の説明。	最大500バイトの文字列

戻り値

変更した計画の数。

使用上の注意

1つの計画を指定した場合は、様々なステータスの1つ、計画名または説明を変更できます。SQL文のすべての計画を指定した場合は、様々なステータスの1つまたは説明を変更できます。このファンクションは、同じ計画または他の計画で別の計画属性を設定するたびに何回もコールできます。

CANCEL_EVOLVE_TASKプロシージャ

このプロシージャは、現在実行中の進化タスクを取り消します。タスクから、すべての中間結果が削除されます。

構文

DBMS_SPM.CANCEL_EVOLVE_TASK  (
   task_name        IN  VARCHAR2);

パラメータ

表148-6 CANCEL_EVOLVE_TASKプロシージャのパラメータ

パラメータ	説明
task_name	取り消すタスクの識別子。

CONFIGUREプロシージャ

このプロシージャは、パラメータ/値の形式でSQL管理ベースの構成オプションを設定します。このファンクションは、構成オプションを設定するたびに何回もコールできます。

構文

DBMS_SPM.CONFIGURE (
   parameter_name    IN VARCHAR2,
   parameter_value   IN NUMBER);

パラメータ

表148-7 CONFIGUREプロシージャのパラメータ

パラメータ	説明
parameter_name	設定するパラメータの名前(次の表を参照)。
parameter_value	設定するパラメータの値(次の表を参照)。

表148-8 CONFIGUREプロシージャのパラメータの名前および値

名前	説明	設定可能な値	デフォルト値
space_budget_percent	SQL管理ベースに使用可能なSYSAUX領域の最大の割合。	1,2, …, 50	10
plan_retention_weeks	パージする前に未使用の計画を保持する週の数。	5,6, …, 523	53

使用上の注意

• SQL管理ベースのデフォルトの領域配分は、SYSAUX表領域のサイズの10パーセントのみです。領域配分は、最大50%に設定できます。未使用の計画のデフォルトの保存期間は1年と1週間で、すなわち計画は、1年を超えて未使用の場合に、自動的にパージされます。保存期間は、最大523週間(すなわち10年強)に設定できます。

• SQL管理ベースによって占有される領域が、定義されている領域配分の制限を超えると、週次データベース・アラートが生成されます。

CREATE_EVOLVE_TASKファンクション

このファンクションには2つのオーバーロードがあり、その両方ともでアドバイザのタスクが作成され、パラメータが設定されます。SQLハンドルを取るこのバージョンは、特定のSQL文の1つ以上の計画を進化させる進化タスクを作成します。

構文

DBMS_SPM.CREATE_EVOLVE_TASK (
   sql_handle    IN  VARCHAR2  := NULL,
   plan_name     IN  VARCHAR2  := NULL,
   time_limit    IN  NUMBER    := DBMS_SPM.AUTO_LIMIT,
   task_name     IN  VARCHAR2  := NULL,
   description   IN  VARCHAR2  := NULL)
  RETURN VARCHAR2;

DBMS_SPM.CREATE_EVOLVE_TASK (
   plan_list     IN  DBMS_SPM.NAME_LIST,
   time_limit    IN  NUMBER    := DBMS_SPM.AUTO_LIMIT,
   task_name     IN  VARCHAR2  := NULL,
   description   IN  VARCHAR2  := NULL)
  RETURN VARCHAR2;

パラメータ

表148-9 CREATE_EVOLVE_TASKファンクションのパラメータ

パラメータ	説明
sql_handle	SQL文のハンドル。デフォルトのNULLでは、未承認の計画を指定するすべてのSQL文が考慮されます。
plan_list	計画名のリスト。計画は、異なるSQL文に属している場合があります。
plan_name	計画の識別子。デフォルトのNULLでは、SQLハンドルがNULLの場合、指定されたSQLハンドルのすべての未承認の計画またはすべてのSQL文が考慮されます。
time_limit	時間制限(分)。時間制限はグローバルで、次の方法で使用されます。最初の未承認の計画の時間制限は、入力値と同じです。2番目の未承認の計画の時間制限は、入力値から最初の計画の検証で費やした時間を差し引いた値になります。それ以降の時間制限も、同様の方法で計算します。デフォルトのDBMS_SPM.AUTO_LIMITにすると、計画に対して実行する必要がある検証の数に基づいて適切な時間制限が選択されます。値DBMS_SPM.NO_LIMITは、時間制限がないことを意味します。
task_name	進化タスク名。
description	タスクの説明(最大256文字)。

戻り値

SQL進化タスクの一意の名前。

CREATE_STGTAB_BASELINEプロシージャ

このプロシージャは、システム間でのSQL計画ベースラインの転送に使用するステージング表を作成します。

構文

DBMS_SPM.CREATE_STGTAB_BASELINE (
   table_name        IN VARCHAR2,
   table_owner       IN VARCHAR2 := NULL,
   tablespace_name   IN VARCHAR2 := NULL);

パラメータ

表148-10 CREATE_STGTAB_BASELINEプロシージャのパラメータ

パラメータ	説明
table_name	SQL計画ベースラインをパックおよびアンパックする目的で作成するステージング表の名前。
table_owner	ステージング表の所有者の名前。デフォルトのNULLにすると、現行のスキーマが表の所有者になります。
tablespace_name	表領域の名前。デフォルトのNULLにすると、デフォルトの表領域にステージング表が作成されます。

使用上の注意

ステージング表の作成が最初の手順です。システム間でSQL計画ベースラインを移行するには、次の一連の手順を実行する必要があります。

1. ソース・システムにステージング表を作成します。

2. ソース・システムでSQL計画ベースラインを選択して、ステージング表にパックします。

3. Oracle EXPユーティリティまたはOracle Data Pumpを使用して、フラット・ファイルにステージング表をエクスポートします。

4. ターゲット・システムにフラット・ファイルを転送します。

5. Oracle IMPユーティリティまたはOracle Data Pumpを使用して、フラット・ファイルからステージング表をインポートします。

6. ステージング表からSQL計画ベースラインを選択して、ターゲット・システムにアンパックします。

DROP_EVOLVE_TASKプロシージャ

このプロシージャは、進化したタスクを削除します。

構文

DBMS_SPM.DROP_EVOLVE_TASK  (
   task_name        IN  VARCHAR2);

パラメータ

表148-11 DROP_EVOLVE_TASKプロシージャのパラメータ

パラメータ	説明
task_name	削除するタスクの識別子。

DROP_SQL_PLAN_BASELINEファンクション

このファンクションは、SQL文に関連付けられている1つまたはすべての計画を削除します。

構文

DBMS_SPM.DROP_SQL_PLAN_BASELINE (
   sql_handle     IN VARCHAR2 := NULL,
   plan_name      IN VARCHAR2 := NULL)
RETURN PLS_INTEGER;

パラメータ

表148-12 DROP_SQL_PLAN_BASELINEファンクションのパラメータ

パラメータ	説明
sql_handle	SQL文のハンドル。削除するSQL文に関連付けられている計画を識別します。NULLの場合は、plan_nameを指定する必要があります。
plan_name	計画名。特定の計画を識別します。デフォルトのNULLにすると、sql_handleで識別されるSQL文に関連付けられているすべての計画が削除されます。

戻り値

削除した計画の数。

EVOLVE_SQL_PLAN_BASELINEファンクション

このファンクションは、1つ以上のSQL文に関連付けられているSQL計画ベースラインを進化させます。SQL計画ベースラインは、1つ以上の承認されていない計画が承認済に変更されると進化します。ユーザーによって問合せ(パラメータverify = 'YES')が行われた場合、関連付けられているSQL計画ベースラインから選択された計画のパフォーマンスと各未承認の計画の実行パフォーマンスが比較されます。未承認の計画のパフォーマンスがSQL計画ベースラインのパフォーマンスより優れている場合、未承認の計画は承認済の計画に変更されます(ただし、ユーザーがこのようなアクションを許可している場合(パラメータcommit = 'YES')にかぎられます)。

このファンクションの2番目の形式では、計画リスト形式を使用します。

構文

DBMS_SPM.EVOLVE_SQL_PLAN_BASELINE (
   sql_handle   IN VARCHAR2 := NULL,
   plan_name    IN VARCHAR2 := NULL,
   time_limit   IN INTEGER  := DBMS_SPM.AUTO_LIMIT,
   verify       IN VARCHAR2 := 'YES',
   commit       IN VARCHAR2 := 'YES')
  RETURN CLOB;

DBMS_SPM.EVOLVE_SQL_PLAN_BASELINE (
   plan_list    IN DBMS_SPM.NAME_LIST,
   time_limit   IN INTEGER  := DBMS_SPM.AUTO_LIMIT,
   verify       IN VARCHAR2 := 'YES',
   commit       IN VARCHAR2 := 'YES')
  RETURN CLOB;

パラメータ

表148-13 EVOLVE_SQL_PLAN_BASELINEファンクションのパラメータ

パラメータ	説明
sql_handle	SQL文の識別子。plan_nameを指定しないかぎり、NULLにすると、SQL計画ベースライン内の未承認の計画を含むすべての文が考慮されます。
plan_name	計画の識別子。デフォルトのNULLにすると、識別されたSQL文、またはsql_handleがNULLの場合はすべてのSQL文のSQL計画ベースラインで未承認の計画が考慮されます。
plan_list	計画名のリスト。リストないの各計画は、同じSQL文に属するものでも、別のSQL文に属するものでもかまいません。
time_limit	時間制限(分)。これはverify = 'YES'の場合にのみ適用されます。時間制限はグローバルで、次のように使用され、たとえば最初の未承認の計画を検証する場合の時間制限は入力値と同じ値に設定され、2番目の未承認の計画を検証する場合の制限時間は(入力値 - 最初の計画の検証に要した時間)という具合に設定されます。 DBMS_SPM.AUTO_LIMIT(デフォルト)にすると、計画に対して実行する必要がある検証の数に基づいて適切な時間制限が選択されます。 DBMS_SPM.NO_LIMITにすると、時間制限は設定されません。 正の整数値は、ユーザーが指定した時間制限を表します。
verify	未承認の計画を承認済の計画に変更する前に、計画を実行し、パフォーマンスを比較するかどうかを指定します。パフォーマンスの検証では、未承認の計画および対応するSQL計画ベースラインから選択された計画が実行され、これらの計画のパフォーマンス統計が比較されます。未承認の計画でパフォーマンスが向上した場合、未承認の計画は承認済の計画に変更されます。 'YES'(デフォルト)にすると、未承認の計画を承認済の計画に変更する前に、未承認の計画でパフォーマンスが向上することが検証されます。 'NO'にすると、計画は実行されず、未承認の計画が承認済の計画に変更されるのみです。
commit	未承認の計画のACCEPTEDステータスを'NO'から'YES'に更新するかどうかを指定します。 'YES'(デフォルト): 条件を満たす未承認の計画を更新し、verify = 'YES'の場合はその更新およびパフォーマンスの検証結果を示すレポートを生成します。 'NO': 更新せずにレポートを生成します。verify = 'NO'とともにcommit = 'NO'を指定すると、操作できなくなります。

戻り値

書式設定されたテキスト・レポートが含まれているCLOB。レポートには、ACCEPTEDステータスへの変更が可能な未承認の計画が順に示されます。また、verify = 'YES'の場合は、それらの計画のパフォーマンスの検証結果も示されます。

使用上の注意

このサブプログラムを起動するには、ADMINISTER SQL MANAGEMENT OBJECT権限が必要です。

EXECUTE_EVOLVE_TASKファンクション

このファンクションは、以前に作成した進化タスクを実行します。

構文

DBMS_SPM.EXECUTE_EVOLVE_TASK  (
   task_name        IN  VARCHAR2,
   execution_name   IN  VARCHAR2  := NULL,
   execution_desc   IN  VARCHAR2  := NULL);
 RETURN VARCHAR2;

パラメータ

表148-14 EXECUTE_EVOLVE_TASKファンクションのパラメータ

パラメータ	説明
task_name	進化タスク名。
execution_name	実行を修飾して識別するための名前。指定されていない場合は、アドバイザによって生成され、ファンクションによって戻されます。
execution_desc	実行の説明(最大256文字)。

戻り値

新しい実行の名前。

IMPLEMENT_EVOLVE_TASKファンクション

このファンクションは、進化タスクによって推奨されているすべてのアクションを実装します。

構文

DBMS_SPM.IMPLEMENT_EVOLVE_TASK  (
   task_name       IN  VARCHAR2,
   task_owner      IN  VARCHAR2  := NULL,
   execution_name  IN  VARCHAR2  := NULL,
   force           IN BOOLEAN    := FALSE)
 RETURN NUMBER;

パラメータ

表148-15 IMPLEMENT_EVOLVE_TASKファンクションのパラメータ

パラメータ	説明
task_name	レポートするタスクの識別子。
task_owner	進化タスクの所有者。デフォルトは、現行のスキーマ所有者です。
execution_name	実行を修飾して識別するための名前。NULLの場合、最後のタスク実行に対してアクションが実行されます。
force	アドバイザがそのようなアクションを推奨しなかった場合でもすべての計画を受け入れます。デフォルトはFALSEです。検証済で、メリットの向上を十分に見込める場合にのみ計画を受け入れることを要求します。

戻り値

受け入れた計画の数。

INTERRUPT_EVOLVE_TASKプロシージャ

このプロシージャは、現在実行中の進化タスクを中断します。このタスクは、通常の終了時と同様に操作を終了し、ユーザーは中間結果にアクセスできます。タスクは後で再開できます。

構文

DBMS_SPM.INTERRUPT_EVOLVE_TASK  (
   task_name        IN  VARCHAR2);

パラメータ

表148-16 INTERRUPT_EVOLVE_TASKプロシージャのパラメータ

パラメータ	説明
task_name	中断するタスクの識別子。

LOAD_PLANS_FROM_CURSOR_CACHEファンクション

このファンクションは、1つまたは1組のSQL文のカーソル・キャッシュに存在する1つ以上の計画をロードします。これには、4つのオーバーロード(SQL文テキストを使用するもの、SQLハンドルを使用するもの、SQL IDを使用するもの、またはattribute_nameとattribute_valueのペアを使用するもの)があります。

構文

DBMS_SPM.LOAD_PLANS_FROM_CURSOR_CACHE (
   sql_id            IN  VARCHAR2,
   plan_hash_value   IN  NUMBER   := NULL,
   sql_text          IN  CLOB,
   fixed             IN  VARCHAR2 := 'NO',
   enabled           IN  VARCHAR2 := 'YES')
 RETURN PLS_INTEGER;

DBMS_SPM.LOAD_PLANS_FROM_CURSOR_CACHE (
   sql_id            IN  VARCHAR2,
   plan_hash_value   IN  NUMBER   := NULL,
   sql_handle        IN  VARCHAR2,
   fixed             IN  VARCHAR2 := 'NO',
   enabled           IN  VARCHAR2 := 'YES')
 RETURN PLS_INTEGER;

DBMS_SPM.LOAD_PLANS_FROM_CURSOR_CACHE (
   sql_id            IN  VARCHAR2,
   plan_hash_value   IN  NUMBER   := NULL,
   fixed             IN  VARCHAR2 := 'NO',
   enabled           IN  VARCHAR2 := 'YES')
 RETURN PLS_INTEGER;

DBMS_SPM.LOAD_PLANS_FROM_CURSOR_CACHE (
   attribute_name   IN VARCHAR2,
   attribute_value  IN VARCHAR2,
   fixed            IN VARCHAR2 := 'NO',
   enabled          IN VARCHAR2 := 'YES')
  RETURN PLS_INTEGER;

パラメータ

表148-17 LOAD_PLANS_FROM_CURSOR_CACHEファンクションのパラメータ

パラメータ	説明
sql_id	SQL文の識別子。カーソル・キャッシュ内のSQL文を識別します。注意: 3番目のオーバーロードでは、識別されたSQL文のテキストがカーソル・キャッシュから抽出され、計画のロード先となるSQL計画ベースラインの特定にそのテキストが使用されます。SQL計画ベースラインが存在しない場合は作成されます。
plan_hash_value	計画の識別子。デフォルトのNULLにすると、SQL_IDで識別されるSQL文のカーソル・キャッシュに存在するすべての計画が取得されます。
sql_text	計画のロード先となるSQL計画ベースラインを特定する場合に使用されるSQLテキスト。SQL計画ベースラインが存在しない場合は作成されます。ユーザーがSQL文のテキストにヒントを追加してSQL文をチューニングし、その結果生成された計画を元のSQL文のSQL計画ベースラインにロードする場合は、テキストの使用が重要となります。
sql_handle	計画のロード先となるSQL計画ベースラインを特定する場合に使用されるSQLハンドル。sql_handleは、既存のSQL計画ベースラインである必要があります。ユーザーがSQL文のテキストにヒントを追加してSQL文をチューニングし、その結果生成された計画を元のSQL文のSQL計画ベースラインにロードする場合は、ハンドルの使用が重要となります。
fixed	デフォルトの'NO'にすると、ロードされた計画が、固定されていない計画として使用されます。値を'YES'にすると、ロードされた計画が、固定された計画として使用され、時間が経過してもSQL計画のベースラインは進化しません。
attribute_name	次の属性名のいずれかになります。 SQL_TEXT'' 'PARSING_SCHEMA_NAME' 'MODULE' 'ACTION'
attribute_value	属性値は、属性名が'SQL_TEXT'の場合、LIKE条件の検索パターンとして使用されます。それ以外の場合は、等価検索値として使用されます (たとえば、attribute_name => 'SQL_TEXT'およびattribute_value => '% HR-123 %'を指定すると、選択フィルタとしてSQL_TEXT LIKE '% HR-123 %'が適用されます。同様に、attribute_name => 'MODULE'およびattribute_value => 'HR'を指定すると、計画選択フィルタとして'MODULE = 'HR'が適用されます)。属性値は、二重引用符で囲んだ場合または属性名が'SQL_TEXT'の場合を除き、大文字になります。
enabled	デフォルトの'YES'にすると、ロードされた計画が、オプティマイザで使用できるように有効になります。

戻り値

ロードした計画の数。

使用上の注意

このサブプログラムを起動するには、ADMINISTER SQL MANAGEMENT OBJECT権限が必要です。

LOAD_PLANS_FROM_SQLSETファンクション

このファンクションは、SQLチューニング・セット(STS)に保存されている計画をSQL計画ベースラインにロードします。STSからロードした計画は、パフォーマンスに関しては検証されませんが、承認済の計画として既存または新規のSQL計画ベースラインに追加されます。このファンクションを使用すると、新しいSQL計画ベースラインでSQL管理ベースをシードできます。

構文

DBMS_SPM.LOAD_PLANS_FROM_SQLSET (
   sqlset_name      IN  VARCHAR2,
   sqlset_owner     IN  VARCHAR2 := NULL,
   basic_filter     IN  VARCHAR2 := NULL,
   fixed            IN  VARCHAR2 := 'NO',
   enabled          IN  VARCHAR2 := 'YES'
   commit_rows      IN  NUMBER   := 1000)
RETURN PLS_INTEGER;

パラメータ

表148-18 LOAD_PLANS_FROM_SQLSETファンクションのパラメータ

パラメータ	説明
sqlset_name	SQL計画ベースラインに計画をロードするSTSの名前。
sqlset_owner	STSの所有者。NULLにすると、現行のスキーマが所有者になります。
basic_filter	条件を満たす計画のみをロード対象として選択するためにSTSに適用されるフィルタ。このフィルタは、DBA_SQLSET_STATEMENTSビューに対して指定可能なWHERE句条件の形式にすることができます。たとえば、basic_filter => 'sql_text like ''select /*LOAD_STS*/%'''やbasic_filter => 'sql_id=''b62q7nc33gzwx'''などです。
fixed	デフォルトの'NO'にすると、ロードされた計画が、固定されていない計画として使用されます。値を'YES'にすると、ロードされた計画が、固定された計画として使用され、時間が経過してもSQL計画のベースラインは進化しません。
enabled	デフォルトの'YES'にすると、ロードされた計画が、オプティマイザで使用できるように有効になります。
commit_rows	定期的なコミットを実行する前にロードするSQL計画の数。UNDOログのサイズ縮小に役立ちます。

戻り値

ロードした計画の数。

使用上の注意

• リモート・システムから計画をロードするには、まずリモート・システムのSTSに計画をロードし、リモート・システムからローカル・システムにSTSをエクスポート/インポートしてから、このファンクションを使用します。

• 自動ワークロード・リポジトリ(AWR)から計画をロードするには、まずAWRスナップショットに保存されている計画をSTSにロードしてから、このプロシージャを使用します。

• また、1つ以上のSQL文のカーソル・キャッシュに存在する計画をSTSに取得してから、このプロシージャを使用することもできます。

MIGRATE_STORED_OUTLINEファンクション

このファンクションは、1つ以上のSQL文のストアド・アウトラインをSQL管理ベース(SMB)の計画ベースラインに移行します。ユーザーは、アウトライン名、SQLテキストまたはアウトライン・カテゴリに基づいてどのストアド・アウトラインを移行するか指定することができ、またシステムにあるすべてのストアド・アウトラインをSQL計画ベースラインに移行することもできます。

このファンクションの2番目のオーバーロードは、1つ以上のSQL文のストアド・アウトラインを1つ以上のアウトライン名を付与されたSQL管理ベース(SMB)の計画ベースラインに移行します。

構文

DBMS_SPM.MIGRATE_STORED_OUTLINE (
   attribute_name     IN  VARCHAR2,
   attribute_value    IN  CLOB,
   fixed              IN  VARCHAR2 := 'NO')
 RETURN CLOB;

DBMS_SPM.MIGRATE_STORED_OUTLINE (
   outln_list         IN  DBMS_SPM.NAME_LIST,
   fixed              IN  VARCHAR2 := 'NO')
 RETURN CLOB;

パラメータ

表148-19 MIGRATE_STORED_OUTLINEファンクションのパラメータ

パラメータ	説明
attribute_name	attribute_valueで使用するパラメータのタイプを指定して、移行されたストアド・アウトラインを識別します。大文字または小文字を区別しません。有効な値は、次のとおりです。 outline_name sql_text category all
attribute_value	attribute_nameに基づいて次の値が可能です。 移行するストアド・アウトラインの名前。 移行するストアド・アウトラインのSQLテキスト。 移行するストアド・アウトラインのカテゴリ。 attribute_nameがallの場合はNULLです。
fixed	NO(デフォルト)またはYES。移行中に生成された計画の「固定」状態を指定します。デフォルトでは、計画は「固定されていない」計画として生成されます。
outln_list	移行するアウトライン名のリスト。

戻り値

次のような、移行中に統計を説明する書式設定されたレポートを含むCLOB。

• 正常に移行されたストアド・アウトラインの数。

• 移行に失敗したストアド・アウトラインの数(および対応するアウトライン名)と失敗の理由。

使用上の注意

• ユーザーがアウトライン名を指定すると、ファンクションは、移行する単一のストアド・アウトラインを一意に識別する付与されたアウトライン名に基づいてストアド・アウトラインを計画ベースラインに移行します。

• ユーザーがSQLテキストを指定すると、ファンクションは指定したSQL文のために作成されたすべてのストアド・アウトラインを移行します。単一のSQL文は、異なるカテゴリ名の下で作成した複数のストアド・アウトラインを持つことができます。各ストアド・アウトラインに1つの計画ベースライン計画が作成されます。新しい計画ベースラインには、DEFAULTに設定されたカテゴリ名があります。計画ベースラインのモジュール名は、ストアド・アウトラインと同じになるように設定されます。

• ユーザーがカテゴリ名を指定すると、ファンクションは指定したカテゴリ名があるすべてのストアド・アウトラインを移行します。SQL文ごとのカテゴリごとに1つのストアド・アウトラインのみが存在します。各ストアド・アウトラインに1つの計画ベースラインが作成されます。

• ユーザーがallの移行を指定すると、ファンクションは、システムにあるすべてのストアド・アウトラインを計画ベースラインに移行します。各ストアド・アウトラインに1つの計画ベースラインが作成されます。

PACK_STGTAB_BASELINEファンクション

このファンクションは、SQL管理ベースからステージング表にSQL計画ベースラインをパック(エクスポート)します。

構文

DBMS_SPM.PACK_STGTAB_BASELINE (
   table_name       IN VARCHAR2,
   table_owner      IN VARCHAR2 := NULL,
   sql_handle       IN VARCHAR2 := NULL,
   plan_name        IN VARCHAR2 := NULL,
   sql_text         IN CLOB     := NULL,
   creator          IN VARCHAR2 := NULL,   origin           IN VARCHAR2 := NULL,
   enabled          IN VARCHAR2 := NULL,
   accepted         IN VARCHAR2 := NULL,
   fixed            IN VARCHAR2 := NULL,
   module           IN VARCHAR2 := NULL,
   action           IN VARCHAR2 := NULL)
RETURN NUMBER;

パラメータ

表148-20 PACK_STGTAB_BASELINEファンクションのパラメータ

パラメータ	説明
table_name	SQL計画ベースラインのパック先のステージング表の名前(二重引用符で囲まれていないかぎり、大/小文字区別なし)。
table_owner	ステージング表の所有者の名前。デフォルトのNULLにすると、現行のスキーマが表の所有者になります。
sql_handle	SQLハンドル(大/小文字区別)
plan_name	計画名(大/小文字区別、%ワイルドカードを使用可)
sql_text	SQLテキスト文字列(大/小文字区別、%ワイルドカードを使用可)
creator	SQL計画ベースラインの作成者(二重引用符で囲まれていないかぎり、大/小文字区別なし)
origin	SQL計画ベースラインの起点。'MANUAL-LOAD'、'AUTO-CAPTURE'、'MANUAL_SQLTUNE'または'AUTO-SQLTUNE'(大/小文字区別なし)である必要があります。
enabled	'YES'または'NO'(大/小文字区別なし)である必要があります。
accepted	'YES'または'NO'(大/小文字区別なし)である必要があります。
fixed	'YES'または'NO'(大/小文字区別なし)である必要があります。
module	モジュール(大/小文字区別)
action	アクション(大/小文字区別)

戻り値

パックしたSQL計画ベースラインの数。

RESET_EVOLVE_TASKプロシージャ

このプロシージャは、進化タスクを初期状態にリセットします。タスクから、すべての中間結果が削除されます。現在実行されていないタスクに対してこのプロシージャ呼び出します。

構文

DBMS_SPM.RESET_EVOLVE_TASK  (
   task_name        IN  VARCHAR2);

パラメータ

表148-21 RESET_EVOLVE_TASKプロシージャのパラメータ

パラメータ	説明
task_name	リセットするタスクの識別子。

RESUME_EVOLVE_TASKプロシージャ

このプロシージャは、以前に中断したタスクを再開します。

構文

DBMS_SPM.RESUME_EVOLVE_TASK  (
   task_name        IN  VARCHAR2);

パラメータ

表148-22 RESUME_EVOLVE_TASKプロシージャのパラメータ

パラメータ	説明
task_name	再開するタスクの識別子。

REPORT_AUTO_EVOLVE_TASKファンクション

このプロシージャは、自動進化タスクの実行結果を表示します。

構文

DBMS_SPM.REPORT_AUTO_EVOLVE_TASK  (
   type            IN  VARCHAR2  := TYPE_TEXT,
   level           IN  VARCHAR2  := LEVEL_TYPICAL,
   section         IN  VARCHAR2  := SECTION_ALL,
   object_id       IN  NUMBER    := NULL,
   execution_name  IN  VARCHAR2  := NULL)
 RETURN CLOB;

パラメータ

表148-23 REPORT_AUTO_EVOLVE_TASKファンクションのパラメータ

パラメータ	説明
type	レポートのタイプ。可能な値はTEXT、HTML、XMLです。
level	レポートの形式。可能な値はBASIC、TYPICAL、ALLです。
section	レポート内の特定のセクション。可能な値はSUMMARY、FINDINGS、PLANS、INFORMATION、ERRORS、ALLです。
object_id	単一の計画を表すアドバイザ・フレームワーク・オブジェクトの識別子。NULLの場合、すべてのオブジェクトに対してレポートが生成されます。
execution_name	実行を修飾して識別するための名前。NULLの場合は、最後のタスク実行に関するレポートが生成されます。

戻り値

レポート。

REPORT_EVOLVE_TASKファンクション

このプロシージャは、進化したタスクの結果を表示します。

構文

DBMS_SPM.REPORT_EVOLVE_TASK  (
   task_name       IN  VARCHAR2,
   type            IN  VARCHAR2  := TYPE_TEXT,
   level           IN  VARCHAR2  := LEVEL_TYPICAL,
   section         IN  VARCHAR2  := SECTION_ALL,
   object_id       IN  NUMBER    := NULL,
   task_owner      IN  VARCHAR2  := NULL,
   execution_name  IN  VARCHAR2  := NULL)
 RETURN CLOB;

パラメータ

表148-24 REPORT_EVOLVE_TASKファンクションのパラメータ

パラメータ	説明
task_name	レポートするタスクの識別子。
type	レポートのタイプ。可能な値はTEXT、HTML、XMLです。
level	レポートの形式。可能な値はBASIC、TYPICAL、ALLです。
section	レポート内の特定のセクション。可能な値はSUMMARY、FINDINGS、PLANS、INFORMATION、ERRORS、ALLです。
object_id	単一の計画を表すアドバイザ・フレームワーク・オブジェクトの識別子。NULLの場合、すべてのオブジェクトに対してレポートが生成されます。
task_owner	進化タスクの所有者。デフォルトは、現行のスキーマ所有者です。
execution_name	実行を修飾して識別するための名前。NULLの場合は、最後のタスク実行に関するレポートが生成されます。

戻り値

レポート。

SET_EVOLVE_TASK_PARAMETERプロシージャ

このプロシージャは、進化タスクのパラメータをNUMBERまたはVARCHAR2に設定します。

構文

DBMS_SPM.SET_EVOLVE_TASK_PARAMETER  (
   task_name     IN  VARCHAR2,
   parameter     IN  VARCHAR2,
   value         IN  NUMBER);

DBMS_SPM.SET_EVOLVE_TASK_PARAMETER  (
   task_name     IN  VARCHAR2  := NULL,
   parameter     IN  VARCHAR2,
   value         IN  VARCHAR2);

パラメータ

表148-25 SET_EVOLVE_TASK_PARAMETERプロシージャのパラメータ

パラメータ	説明
task_name	進化タスク名。
parameter	設定するパラメータの名前。
value	パラメータの新しい値。

UNPACK_STGTAB_BASELINEファンクション

このファンクションは、ステージング表からSQL管理ベースにSQL計画ベースラインをアンパック(インポート)します。

構文

DBMS_SPM.UNPACK_STGTAB_BASELINE (
   table_name       IN VARCHAR2,
   table_owner      IN VARCHAR2 := NULL,
   sql_handle       IN VARCHAR2 := NULL,
   plan_name        IN VARCHAR2 := NULL,
   sql_text         IN CLOB     := NULL,
   creator          IN VARCHAR2 := NULL,   origin           IN VARCHAR2 := NULL,
   enabled          IN VARCHAR2 := NULL,
   accepted         IN VARCHAR2 := NULL,
   fixed            IN VARCHAR2 := NULL,
   module           IN VARCHAR2 := NULL,
   action           IN VARCHAR2 := NULL)
RETURN NUMBER;

パラメータ

表148-26 UNPACK_STGTAB_BASELINEファンクションのパラメータ

パラメータ	説明
table_name	SQL計画ベースラインのアンパック元のステージング表の名前(二重引用符で囲まれていないかぎり、大/小文字区別なし)。
table_owner	ステージング表の所有者の名前。デフォルトのNULLにすると、現行のスキーマが表の所有者になります。
sql_handle	SQLハンドル(大/小文字区別)
plan_name	計画名(大/小文字区別、%ワイルドカードを使用可)
sql_text	SQLテキスト文字列(大/小文字区別、%ワイルドカードを使用可)
creator	SQL計画ベースラインの作成者(二重引用符で囲まれていないかぎり、大/小文字区別なし)
origin	SQL計画ベースラインの起点。'MANUAL-LOAD'、'AUTO-CAPTURE'、'MANUAL_SQLTUNE'または'AUTO-SQLTUNE'(大/小文字区別なし)である必要があります。
enabled	'YES'または'NO'(大/小文字区別なし)である必要があります。
accepted	'YES'または'NO'(大/小文字区別なし)である必要があります。
fixed	'YES'または'NO'(大/小文字区別なし)である必要があります。
module	モジュール(大/小文字区別)
action	アクション(大/小文字区別)

戻り値

アンパックした計画の数。