1. PL/SQLパッケージおよびタイプ・リファレンス
  2. DBMS_SQLQ

169 DBMS_SQLQ

DBMS_SQLQパッケージは、SQL文の実行プランに対する隔離しきい値を構成するためのインタフェースを提供します。いずれかのリソース・マネージャしきい値が、SQL文の隔離構成で指定された隔離しきい値以下である場合、その隔離構成で指定された実行プランを使用すると、SQL文は実行できなくなります。

この章のトピックは、次のとおりです:

169.1 DBMS_SQLQの概要

DBMS_SQLQパッケージは、SQL文の実行プランに対する隔離しきい値を構成するためのインタフェースを提供します。いずれかのリソース・マネージャしきい値が、SQL文の隔離構成で指定された隔離しきい値以下である場合、その隔離構成で指定された実行プランを使用すると、SQL文は実行できなくなります。

DBMS_SQLQパッケージのサブプログラムを使用すると、次の操作を実行できます。

  • SQL文の実行プランに対する隔離設定を作成し、リソース消費に対する隔離しきい値を指定します

  • 隔離構成で指定された問合せ隔離しきい値

  • 隔離構成を削除します

  • データベース間で隔離構成を転送します

169.2 DBMS_SQLQサブプログラムの要約

この表はDBMS_SQLQサブプログラムをリストし、簡単に説明しています。

表169-1 DBMS_SQLQパッケージのサブプログラム

プロシージャ 説明

ALTER_QUARANTINEプロシージャ

SQL文の実行プランの隔離設定で隔離しきい値を指定します

CREATE_QUARANTINE_BY_SQL_IDファンクション

SQL IDを使用してSQL文の実行プランの隔離構成を作成します

CREATE_QUARANTINE_BY_SQL_TEXTファンクション

SQLテキストを使用してSQL文の実行プランの隔離構成を作成します

CREATE_STGTAB_QUARANTINEプロシージャ

隔離構成を格納するステージング表を作成します

DROP_QUARANTINEプロシージャ

隔離構成を削除します

GET_PARAM_VALUE_QUARANTINEファンクション

隔離構成で指定された隔離しきい値の値を返します

PACK_STGTAB_QUARANTINEファンクション

1つ以上の隔離構成をステージング表に追加します

UNPACK_STGTAB_QUARANTINEファンクション

ステージング表から取り出した隔離構成をデータベースに作成します

169.2.1 ALTER_QUARANTINEプロシージャ

このプロシージャは、SQL文の実行プランの隔離設定でのリソースに対する隔離しきい値を指定します

構文

DBMS_SQLQ.ALTER_QUARANTINE (
   quarantine_name   IN VARCHAR2,
   parameter_name    IN VARCHAR2,
   parameter_value   IN VARCHAR2);

パラメータ

表169-2 ALTER_QUARANTINEプロシージャのパラメータ

パラメータ 説明

quarantine_name

隔離構成の名前

parameter_name

隔離しきい値を指定する必要があるリソースの名前。次のいずれかの値を指定できます。

  • CPU_TIME: CPU時間

  • ELAPSED_TIME: 経過時間

  • IO_MEGABYTES: I/O (MB単位)

  • IO_REQUESTS: 物理I/Oのリクエスト数

  • IO_LOGICAL: 論理I/Oのリクエスト数

  • ENABLED: 隔離構成を有効または無効にするフラグ。有効にする場合はYESを指定し、無効にする場合はNOを指定します。デフォルト値は、YESです。

  • AUTOPURGE: 指定した隔離構成の自動パージを有効または無効にするフラグ。YESに設定すると、隔離構成は53週間後に自動的にパージされます(使用していない場合)。NOに設定すると、隔離構成はパージされません。デフォルト値は、YESです。

parameter_value

parameter_nameで指定されたリソースの隔離しきい値。

例

次の例では、隔離構成SQL_QUARANTINE_3z0mwuq3aqsm8cfe7a0e4に対して、CPU時間に指定された隔離しきい値が5秒で、経過時間が10秒です。 

BEGIN

  DBMS_SQLQ.ALTER_QUARANTINE(
   QUARANTINE_NAME  =>  'SQL_QUARANTINE_3z0mwuq3aqsm8cfe7a0e4',
   PARAMETER_NAME   =>  'CPU_TIME',
   PARAMETER_VALUE  =>  '5');

  DBMS_SQLQ.ALTER_QUARANTINE(
   QUARANTINE_NAME  =>  'SQL_QUARANTINE_3z0mwuq3aqsm8cfe7a0e4',
   PARAMETER_NAME   =>  'ELAPSED_TIME',
   PARAMETER_VALUE  =>  '10');

END;
/

隔離構成で指定された実行プランを使用してSQL文が実行され、CPU時間のリソース・マネージャしきい値が5秒以下または経過時間が10秒以下である場合、SQL文は実行できなくなります。

169.2.2 CREATE_QUARANTINE_BY_SQL_IDファンクション

このファンクションは、SQL IDに基づくSQL文の実行プランの隔離構成を作成します。

構文

DBMS_SQLQ.CREATE_QUARANTINE_BY_SQL_ID (
   sql_id           IN VARCHAR2,
   plan_hash_value  IN NUMBER DEFAULT NULL)
RETURN VARCHAR2;

パラメータ

表169-3 CREATE_QUARANTINE_BY_SQL_IDファンクションのパラメータ

パラメータ 説明

sql_id

SQL文のSQL ID。

plan_hash_value

SQL文の実行プランのハッシュ値。デフォルト値はNULLです。

NULLの場合は、SQL文のすべての実行計画に隔離構成が適用されます。

戻り値

隔離構成の名前

例

次の例では、SQL IDが8vu7s907prbgrのSQL文に対する隔離構成を作成します。隔離構成は、このSQL文のすべての実行計画に適用されます。 

DECLARE
  quarantine_config VARCHAR2(30);
BEGIN
  quarantine_config := DBMS_SQLQ.CREATE_QUARANTINE_BY_SQL_ID(SQL_ID => '8vu7s907prbgr');
END;
/

次の例では、SQL IDが8vu7s907prbgrのSQL文に対応する、ハッシュ値が3488063716の実行プランに対して隔離構成を作成します。 

DECLARE
  quarantine_config VARCHAR2(30);
BEGIN
  quarantine_config := DBMS_SQLQ.CREATE_QUARANTINE_BY_SQL_ID(SQL_ID => '8vu7s907prbgr', PLAN_HASH_VALUE => '3488063716');
END;
/

169.2.3 CREATE_QUARANTINE_BY_SQL_TEXTファンクション

このファンクションは、SQLテキストに基づくSQL文の実行プランの隔離構成を作成します。

構文

DBMS_SQLQ.CREATE_QUARANTINE_BY_SQL_TEXT (
   sql_text         IN CLOB,
   plan_hash_value  IN NUMBER DEFAULT NULL)
RETURN VARCHAR2;

パラメータ

表169-4 CREATE_QUARANTINE_BY_SQL_TEXTファンクションのパラメータ

パラメータ 説明

sql_text

SQL文。

plan_hash_value

SQL文の実行プランのハッシュ値。デフォルト値はNULLです。

NULLの場合は、SQL文のすべての実行計画に隔離構成が適用されます。

戻り値

隔離構成の名前

例

次の例では、SQL文'select count(*) from emp'のすべての実行プランに適用する隔離構成を作成します。 

DECLARE
  quarantine_config VARCHAR2(30);
BEGIN
  quarantine_config := DBMS_SQLQ.CREATE_QUARANTINE_BY_SQL_TEXT(SQL_TEXT => to_clob('select count(*) from emp'));
END;
/

次の例では、SQLテキストが'select count(*) from emp'のSQL文に対応する、ハッシュ値が3488063716の実行計画に対する隔離構成を作成します。 

DECLARE
  quarantine_config VARCHAR2(30);
BEGIN
  quarantine_config := DBMS_SQLQ.CREATE_QUARANTINE_BY_SQL_TEXT(SQL_TEXT => to_clob('select count(*) from emp'), PLAN_HASH_VALUE => '3488063716');
END;
/

169.2.4 CREATE_STGTAB_QUARANTINEプロシージャ

このプロシージャでは、隔離構成を格納するステージング表を作成します。現在のデータベースからステージング表をエクスポートして別のデータベースにインポートすることで、この隔離構成をデータベース全体で使用できるようになります。

構文

DBMS_SQLQ.CREATE_STGTAB_QUARANTINE (
   staging_table_name   IN VARCHAR2,
   staging_table_owner  IN VARCHAR2 DEFAULT NULL,
   tablespace_name      IN VARCHAR2 DEFAULT NULL);

パラメータ

表169-5 CREATE_STGTAB_QUARANTINEプロシージャのパラメータ

パラメータ 説明

staging_table_name

ステージング表の名前。

staging_table_owner

ステージング表のスキーマ所有者名。デフォルト値は、NULLです。この値は、このプロシージャを実行するデータベース・ユーザーがステージング表の所有者として設定されることを意味します。

tablespace_name

ステージング表の作成先にする表領域の名前。デフォルト値はNULLです。この値はステージング表がデータベースのデフォルト表領域に作成されることを意味します。

例

次の例では、データベースのデフォルト表領域にステージング表TBL_STG_QUARANTINEを作成します。その表の所有者は、このプロシージャを実行するデータベース・ユーザーに設定しています。 

BEGIN
  DBMS_SQLQ.CREATE_STGTAB_QUARANTINE(STAGING_TABLE_NAME => 'TBL_STG_QUARANTINE');
END;
/

169.2.5 DROP_QUARANTINEプロシージャ

このプロシージャでは、隔離構成を削除します。

構文

DBMS_SQLQ.DROP_QUARANTINE(quarantine_name IN VARCHAR2);

パラメータ

表169-6 DROP_QUARANTINEプロシージャのパラメータ

パラメータ 説明

quarantine_name

削除する隔離構成の名前。

例

次の例では、SQL_QUARANTINE_3z0mwuq3aqsm8cfe7a0e4という名前の隔離構成を削除します。 

BEGIN
  DBMS_SQLQ.DROP_QUARANTINE('SQL_QUARANTINE_3z0mwuq3aqsm8cfe7a0e4');
END;
/

169.2.6 GET_PARAM_VALUE_QUARANTINEファンクション

このファンクションは、隔離設定で指定されたリソースの隔離しきい値を返します。

構文

DBMS_SQLQ.GET_PARAM_VALUE_QUARANTINE (
   quarantine_name   IN VARCHAR2,
   parameter_name    IN VARCHAR2)
RETURN VARCHAR2;

パラメータ

表169-7 GET_PARAM_VALUE_QUARANTINEファンクションのパラメータ

パラメータ 説明

quarantine_name

隔離構成の名前

parameter_name

隔離しきい値を取得する必要があるリソース。

戻り値

隔離設定で指定されたリソースの隔離しきい値を返します。

例

次の例では、SQL_QUARANTINE_3z0mwuq3aqsm8cfe7a0e4という名前の隔離構成で指定されたCPU時間の隔離しきい値が返されます。 

DECLARE
  quarantine_config_setting_value VARCHAR2(30);
BEGIN
  quarantine_config_setting_value := DBMS_SQLQ.GET_PARAM_VALUE_QUARANTINE(
                                        QUARANTINE_NAME  =>  'SQL_QUARANTINE_3z0mwuq3aqsm8cfe7a0e4',
                                        PARAMETER_NAME   =>  'CPU_TIME');
END;
/

169.2.7 PACK_STGTAB_QUARANTINEファンクション

このファンクションでは、1つ以上の隔離構成をステージング表に追加します。

構文

DBMS_SQLQ.PACK_STGTAB_QUARANTINE (
   staging_table_name    IN VARCHAR2,
   staging_table_owner   IN VARCHAR2 DEFAULT NULL,
   name                  IN VARCHAR2 DEFAULT '%',
   sql_text              IN VARCHAR2 DEFAULT '%',
   enabled               IN VARCHAR2 DEFAULT NULL)
RETURN NUMBER;

パラメータ

表169-8 PACK_STGTAB_QUARANTINEファンクションのパラメータ

パラメータ 説明

staging_table_name

隔離構成の追加先にするステージング表の名前。

staging_table_owner

ステージング表のスキーマ所有者名。デフォルト値は、NULLです。この値は、このプロシージャを実行するデータベース・ユーザーがステージング表の所有者として設定されることを意味します。

name

隔離構成の名前この値は大/小文字が区別されます。また、ワイルドカード文字を使用できます。

sql_text

SQL文テキスト。この値は大/小文字が区別されます。また、ワイルドカード文字を使用できます。

enabled

隔離構成を有効にするか無効にするかを示すフラグ。YESに設定すると、隔離構成が有効になります。それ以外の場合は無効になります。デフォルト値は、NULLです。つまり、デフォルトでは隔離構成が無効になることを意味します。

戻り値

ステージング表に追加する隔離構成の数。

例

次の例では、名前がSQL_QUARANTINE_で始まるすべての隔離構成を、ステージング表TBL_STG_QUARANTINEに追加します。 

DECLARE
  quarantine_configs NUMBER;
BEGIN
  quarantine_configs := DBMS_SQLQ.PACK_STGTAB_QUARANTINE(
                           STAGING_TABLE_NAME => 'TBL_STG_QUARANTINE',
                           NAME => 'SQL_QUARANTINE_%');
END;
/

169.2.8 UNPACK_STGTAB_QUARANTINEファンクション

このファンクションは、ステージング表から取り出した隔離構成をデータベースに作成します。

構文

DBMS_SQLQ.UNPACK_STGTAB_QUARANTINE (
   staging_table_name    IN VARCHAR2,
   staging_table_owner   IN VARCHAR2 DEFAULT NULL,
   name                  IN VARCHAR2 DEFAULT '%',
   sql_text              IN VARCHAR2 DEFAULT '%',
   enabled               IN VARCHAR2 DEFAULT NULL)
RETURN NUMBER;

パラメータ

表169-9 UNPACK_STGTAB_QUARANTINEファンクションのパラメータ

パラメータ 説明

staging_table_name

データベースに作成する隔離構成を取り出すステージング表の名前。

staging_table_owner

ステージング表のスキーマ所有者名。デフォルト値は、NULLです。この値は、このプロシージャを実行するデータベース・ユーザーがステージング表の所有者として設定されることを意味します。

name

隔離構成の名前この値は大/小文字が区別されます。また、ワイルドカード文字を使用できます。

sql_text

SQL文テキスト。この値は大/小文字が区別されます。また、ワイルドカード文字を使用できます。

enabled

隔離構成を有効にするか無効にするかを示すフラグ。この値がYESの場合は、隔離構成が有効になります。それ以外の場合は無効になります。デフォルト値は、NULLです。つまり、デフォルトでは隔離構成が無効になることを意味します。

戻り値

ステージング表から取り出してデータベースに作成する隔離構成の数。

例

次の例では、ステージング表TBL_STG_QUARANTINEに格納されているすべての隔離構成を取り出してデータベースに隔離構成を作成します。 

DECLARE
  quarantine_configs NUMBER;
BEGIN
  quarantine_configs := DBMS_SQLQ.UNPACK_STGTAB_QUARANTINE(
                                      STAGING_TABLE_NAME => 'TBL_STG_QUARANTINE');
END;
/