1. リファレンス
  2. CTX_OUTPUTパッケージ

11 CTX_OUTPUTパッケージ

この章では、PL/SQLパッケージCTX_OUTPUTの使用方法について説明します。

CTX_OUTPUTには、次のストアド・プロシージャが含まれています。

名前 説明

ADD_EVENT

索引ログにイベントを追加します。

ADD_TRACE

トレースを使用可能にします。

DISABLE_QUERY_STATS

索引の問合せ統計の収集をオフに切り替えます。

ENABLE_QUERY_STATS

索引の問合せ統計の収集を使用可能にします。

END_LOG

索引およびドキュメント・サービスの要求のロギングを停止します。

END_QUERY_LOG

ログ・ファイルへの問合せのロギングを停止します。

GET_TRACE_VALUE

トレースの値を戻します。

LOG_TRACES

トレースをログ・ファイルに出力します。

LOGFILENAME

現在のログ・ファイルの名前を戻します。

REMOVE_EVENT

索引ログからイベントを削除します。

REMOVE_TRACE

トレースを使用不可にします。

RESET_TRACE

トレースをクリアします。

START_LOG

索引およびドキュメント・サービスの要求のロギングを開始します。

START_QUERY_LOG

問合せのログ・ファイルを作成します。

ノート:

CTX_OUTPUTパッケージのAPIは、スキーマまたは所有者名を接頭辞として使用する識別子をサポートしていません。

11.1 ADD_EVENT

このプロシージャを使用して、詳細なログ出力を表示するためにイベントを索引ログに追加するか、またはOracle Textエラーのエラー・トレースを使用可能にします。索引ログが、データベース・トレース・ファイルに追加されます。

構文

CTX_OUTPUT.ADD_EVENT(event in NUMBER, errnum in NUMBER := null);
event

ロギングする索引イベントの型を指定します。次のイベントを追加できます。

  • CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID: 索引付けが終了した各行のROWIDをロギングします。これは、失敗した索引操作のデバッグに有効です。

  • CTX_OUTPUT.EVENT_INDEX_PRINT_TOKEN: 各トークンが索引付けされるたびに出力します。

  • CTX_OUTPUT.EVENT_DRG_DUMP_ERRORSTACK: ログの指定されたDRGエラーのスタック・トレースを出力します。errnumが指定されないと、エラーが発生します。

ノート:

CTX_OUTPUT.EVENT_OPT_PRINT_TOKENは、最適化されるたびに各トークンを出力し、CTX_OUTPUT.EVENT_INDEX_PRINT_TOKENは、索引付けされるたびに各トークンを出力します。これらは、PDBロックダウン・プロファイルCTX_PROTOCOLSを使用する場合、使用不可になります。
errnum

CTX_OUTPUT.EVENT_DRG_DUMP_ERRRORSTACKイベントのDRGエラー番号を指定します。

例

begin
CTX_OUTPUT.ADD_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID);
end;

関連項目

「REMOVE_EVENT」

11.2 ADD_TRACE

トレースを使用可能にします。トレースが使用可能でない場合、このコールにより、トレースがアクティブなトレースのリストに追加され、値が0(ゼロ)にリセットされます。トレースがすでに使用可能になっている場合、エラーが発生します。

構文

CTX_OUTPUT.ADD_TRACE(trace_id BINARY_INTEGER);
trace_id

使用可能にするトレースのIDを指定します。有効なトレース値は、表11-1を参照してください。

ノート

表11-1は、有効なトレースを示しています。

表11-1 有効なトレース

記号 ID メトリック

TRACE_IDX_USER_DATASTORE

1

ユーザー・データストアの実行に要した時間

TRACE_IDX_AUTO_FILTER

2

AUTO_FILTERフィルタの起動に要した時間(非推奨のTRACE_IDX_INSO_FILTERトレースの代替)

TRACE_QRY_XX_TIME

3

$Xカーソルの実行に要した時間

TRACE_QRY_XF_TIME

4

$Xからのフェッチに要した時間

TRACE_QRY_X_ROWS

5

トークン・メタデータが$Xからフェッチされた行の合計数

TRACE_QRY_IF_TIME

6

$IからLOBロケータをフェッチするために要した時間

TRACE_QRY_IR_TIME

7

$I LOB情報の読取りに要した時間

TRACE_QRY_I_ROWS

8

$I token_infoが実際に読み取られた行の数

TRACE_QRY_I_SIZE

9

$I LOBから読み取られたバイト数

TRACE_QRY_R_TIME

10

$R情報のフェッチおよび読取りに要した時間

TRACE_QRY_CON_TIME

11

CONTAINS処理に要した時間(drexrcontains/drexrstart/drexrfetch)

TRACE_QRY_S_TIME

15

$S情報のフェッチおよび読取りに要した時間

TRACE_QRY_O_TIME

19

$O情報の読取りに要した時間

TRACE_QRY_D_TIME

23

$D情報の読取りに要した時間

TRACE_QRY_SNIPPET_TIME

25

ドキュメントからスニペットを抽出する際に費やした時間

TRACE_HIL_DOCSERV_TIME

26

ドキュメント・サービスのプロシージャ(スニペット、ハイライト、マークアップ)によって費やされた時間

トレースはロギングから独立しています。トレースの開始にはロギングがオンになっている必要はなく、その逆も同じです。

トレースはセッションに関連付けられています。1つのセッション内で発生する操作は測定できますが、逆にセッション全体にわたる測定はできません。

パラレル同期化または最適化の際、トレースが現在有効になっている場合にかぎり、トレース・プロファイルはスレーブ・セッションにコピーされます。各スレーブは独自のトレースを蓄積し、終了前にすべてのトレース値をスレーブ・ログ・ファイルに暗黙的に書き込みます。

関連項目

「REMOVE_TRACE」

「GET_TRACE_VALUE」

「LOG_TRACES」

「RESET_TRACE」

『Oracle Textアプリケーション開発者ガイド』

11.3 DISABLE_QUERY_STATS

索引の問合せ統計の収集を使用不可にします。

構文

ctx_output.disable_query_stats(
index_name IN VARCHAR2
);
index_name

問合せ統計の収集を使用不可にする索引の名前。

例

索引myindexの問合せ統計の収集をオフに切り替えます。 

CTX_OUTPUT.DISABLE_QUERY_STATS(myindex);

ノート

索引の問合せ統計を使用不可にすると、その索引の問合せに関連するメタデータの収集と格納が停止されます。その索引に対応するすべてのエントリは、ディクショナリ表からクリアされます。問合せ統計が使用可能でない索引に対してこのプロシージャをコールすると、エラーが戻ります。

関連項目

CTX_OUTPUT.「ENABLE_QUERY_STATS」

CTX_REPORT.「INDEX_STATS」

11.4 ENABLE_QUERY_STATS

索引の問合せ統計の収集を使用可能にします。索引の問合せに関連するメタデータを保存する場合は、このプロシージャを使用して、その索引に対する統計の収集を使用可能にします。索引のctx_output.enable_query_statsがオンになっている場合にのみ、収集されたメタデータにアクセスできます。

ノート:

問合せ統計メタデータへのアクセスは、索引のctx_output.enable_query_statsがオンになっている場合にのみ機能します。収集される問合せ統計メタデータのリストは、CTX_REPORT.「INDEX_STATS」を参照してください。

構文

ctx_output.enable_query_stats(
index_name IN VARCHAR2
);
index_name

問合せ統計の収集を使用可能にする索引の名前。

例

索引myindexの問合せ統計の収集をオンに切り替えます。 

CTX_OUTPUT.ENABLE_QUERY_STATS(myindex);

ノート

索引の問合せ統計が使用可能かどうかを示す情報は、CTX_INDEXESビューおよびCTX_USER_INDEXESビューのidx_query_stats_enabled列で確認できます。索引のquery_statsが使用可能な場合は、その列に「YES」が表示され、使用可能でない場合は「NO」が表示されます。

問合せ統計に対応するデータは、永続的なディクショナリ表に格納されます。特定の索引に対してstatisticsが使用可能になると、その索引について全セッションから問合せ統計が収集されます。

問合せ統計がすでに使用可能になっている索引に対してこのプロシージャをコールすると、エラーが発生します。

統計収集は、問合せのパフォーマンスにわずかな影響を与えます。

関連項目

CTX_OUTPUT.「DISABLE_QUERY_STATS」

CTX_REPORT.「INDEX_STATS」.

11.5 END_LOG

索引およびドキュメント・サービスの要求のロギングを停止します。

構文

ctx_output.end_log;

例

begin
CTX_OUTPUT.END_LOG;
end;

11.6 END_QUERY_LOG

このプロシージャを使用して、問合せのログのデータベースのトレース・ファイルへの出力を中止します。

構文

ctx_output.end_query_log;

例

begin
CTX_OUTPUT.START_QUERY_LOG('mylog1');
     < get queries >
CTX_OUTPUT.END_QUERY_LOG;
end;

11.7 GET_TRACE_VALUE

トレースの現行値をプログラムによって取得します。

構文

CTX_OUTPUT.GET_TRACE_VALUE(trace_id BINARY_INTEGER);
trace_id

値を取得するトレースIDを指定します。有効な値は、表11-1を参照してください。

例

これにより、変数valueの値を設定します。 

value := ctx_output.get_trace_value(trace_id);

ノート

SQLを使用してもトレース値を取得できます。

select * from ctx_trace_values;

CTX_TRACE_VALUESビューのエントリは、「CTX_TRACE_VALUES」を参照してください。

トレースが使用可能でない場合は、エラーが発生します。

このコールでは、トレースは0(ゼロ)にリセットされません。

トレースはセッションに関連付けられています。1つのセッション内で発生する操作は測定できますが、逆にセッション全体にわたる測定はできません。

関連項目

「REMOVE_TRACE」

「ADD_TRACE」

「LOG_TRACES」

「RESET_TRACE」

『Oracle Textアプリケーション開発者ガイド』

11.8 LOG_TRACES

このプロシージャを使用して、すべてのアクティブなトレースをRDBMSトレース・ファイルに出力します。

構文

CTX_OUTPUT.LOG_TRACES;

ノート

このコールでは、トレースは0(ゼロ)にリセットされません。

トレースは、データベースのトレース・ファイルに出力されます。

関連項目

「REMOVE_TRACE」

「GET_TRACE_VALUE」

「ADD_TRACE」

「RESET_TRACE」

『Oracle Textアプリケーション開発者ガイド』

11.9 LOGFILENAME

現行のセッションのトレース・ファイル名を返します。ログの出力が開始しない場合、エラーが発生します。

構文

CTX_OUTPUT.LOGFILENAME RETURN VARCHAR2;

戻り値

ログ・ファイルの名前

例

declare
   logname varchar2(100);
begin
   logname := CTX_OUTPUT.LOGFILENAME;
   dbms_output.put_line('The current log file is: '||logname); 
end;

11.10 REMOVE_EVENT

このプロシージャを使用して、ctx_output.add_eventを使用して追加したイベントを削除します。

構文

CTX_OUTPUT.REMOVE_EVENT(event in NUMBER);
event

ログから削除する索引イベントの型を指定します。次のイベントを削除できます。

  • CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID: 索引付けが終了した各行のROWIDをロギングします。これは、失敗した索引操作のデバッグに有効です。

  • CTX_OUTPUT.EVENT_OPT_PRINT_TOKEN: 各トークンが最適化されるたびに出力します。

  • CTX_OUTPUT.EVENT_INDEX_PRINT_TOKEN: 各トークンが索引付けされるたびに出力します。

例

begin
CTX_OUTPUT.REMOVE_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID);
end;

関連項目

「ADD_EVENT」

11.11 REMOVE_TRACE

トレースを使用不可にします。

構文

CTX_OUTPUT.REMOVE_TRACE(trace_id BINARY_INTEGER);
trace_id

使用不可にするトレースのIDを指定します。有効な値は、表11-1を参照してください。

ノート

トレースが使用可能でない場合は、エラーが発生します。

関連項目

「GET_TRACE_VALUE」

「ADD_TRACE」

「LOG_TRACES」

「RESET_TRACE」

『Oracle Textアプリケーション開発者ガイド』

11.12 RESET_TRACE

トレースをクリアします(つまり0(ゼロ)にリセットします)。

構文

CTX_OUTPUT.RESET_TRACE(trace_id BINARY_INTEGER);
trace_id

リセットするトレースのIDを指定します。有効な値は、表11-1を参照してください。

ノート

トレースが使用可能でない場合は、エラーが発生します。

関連項目

「REMOVE_TRACE」

「GET_TRACE_VALUE」

「ADD_TRACE」

「LOG_TRACES」

『Oracle Textアプリケーション開発者ガイド』

11.13 START_LOG

索引およびドキュメント・サービスの要求のロギングを開始します。Oracle Database 12c リリース2 (12.2)以降では、索引ログはデータベース・トレース・ファイルに書き込まれます。

構文

CTX_OUTPUT.START_LOG(logfile in varchar2, overwrite in default true);
logfile

ログ・ファイルの名前を指定します。Oracle Database 12cリリース2 (12.2)以降では、logfileパラメータは無視されます。ログが、データベース・トレース・ファイルに追加されます。V$DIAG_INFOおよびV$PROCESSなどのディクショナリ・ビューを使用して、現行セッションのトレース・ファイルへのパス、または各Oracle Databaseプロセスのトレース・ファイルへのパスを検索します。

自動診断リポジトリ・コマンド・インタプリタ(ADRCI)ユーティリティは、トレース・ファイルへのアクセスにも使用できます。

overwrite

logfileで指定された元の問合せログ・ファイル(すでに存在する場合)を上書きするか、またはそこに追加するかを指定します。Oracle Database 12cリリース2 (12.2)以上では、このパラメータは無視されます。デフォルトでは、すべてのログがデータベース・トレース・ファイルに追加されます。

例

begin
CTX_OUTPUT.START_LOG('mylog1');
end;

索引ログを表示するには、次のようにして、ビューV$DIAG_TRACE_FILE_CONTENTSのCOMPONENT_NAME=’CONTEXT_INDEX’を検索します。 

select PAYLOAD from V$DIAG_TRACE_FILE_CONTENTS where COMPONENT_NAME='CONTEXT_INDEX' and TRACE_FILENAME = trc_name;

問合せログを表示するには、次のようにして、ビューV$DIAG_TRACE_FILE_CONTENTSのCOMPONENT_NAME=’CONTEXT_QUERY’を検索します。 

select PAYLOAD from V$DIAG_TRACE_FILE_CONTENTS where COMPONENT_NAME='CONTEXT_QUERY' and TRACE_FILENAME = trc_name;

パラレル問合せ(PQ)スレーブのトレース・ファイル名のタイプは、SID_pxxx_PID.trcです。パラレル・スレーブ内のトレースを表示するには: 

select TRACE_FILENAME, PAYLOAD from V$DIAG_TRACE_FILE_CONTENTS where COMPONENT_NAME='CONTEXT_INDEX' and TRACE_FILENAME LIKE '%p00%';

ノート

PDBロックダウン・プロファイルCTX_LOGGINGが有効な場合、ログは書き込まれません。

トレースの開始にはロギングがオンになっている必要はなく、その逆も同じです。

ロギングはセッションに関連付けられています。1つのセッション内で発生する操作はログに記録できますが、逆に複数セッションにわたる操作はログに記録できません。

CTX_OUTPUT.START_LOGに使用されるファイル名の文字は、英数字、マイナス記号、ピリオド、スペース、ハッシュ記号、アンダースコア、一重引用符および二重引用符に制限されています。ファイル名にその他の文字が使用されていると、エラーが発生します。

11.14 START_QUERY_LOG

ロギング問合せのリクエストを開始します。Oracle Database 12c リリース2 (12.2)以降では、問合せログはデータベース・トレース・ファイルに書き込まれます。

問合せのロギングを停止するには、CTX_OUTPUT.END_QUERY_LOGを使用します。どの問合せが最も頻繁に正常に戻されたかなど、ログに記録された問合せに関するレポートを取得するには、CTX_REPORT.QUERY_LOG_SUMMARYを使用します。

問合せログには、問合せ文字列、索引名、問合せのタイムスタンプ、および問合せがヒットを戻したかどうかが含まれます。2003年11月11日6:46 (現地時間)にBlues Guitaristsという句に対する問合せが成功した場合、問合せログに次の形式で入力されます。 

<QuerySet><TimeStamp>18:46:51 02/04/03</TimeStamp><IndexName>
IDX_SEARCH_TABLE</IndexName><Query>Blues
Guitarists</Query><ReturnHit>Yes</ReturnHit></QuerySet>

構文

CTX_OUTPUT.START_QUERY_LOG(logfile in varchar2, overwrite in default true);
logfile

問合せログ・ファイルの名前を指定します。Oracle Database 12cリリース2 (12.2)以降では、logfileパラメータは無視されます。そのかわり、ログが、データベース・トレース・ファイルに追加されます。V$DIAG_INFOおよびV$PROCESSなどのディクショナリ・ビューを使用して、現行セッションのトレース・ファイルへのパス、または各Oracle Databaseプロセスのトレース・ファイルへのパスを検索します。

自動診断リポジトリ・コマンド・インタプリタ(ADRCI)ユーティリティは、トレース・ファイルへのアクセスにも使用できます。

overwrite

logfileで指定された元の問合せログ・ファイル(すでに存在する場合)を上書きするか、またはそこに追加するかを指定します。Oracle Database 12cリリース2 (12.2)以上では、このパラメータは無視されます。デフォルトでは、すべてのログがデータベース・トレース・ファイルに追加されます。

例

begin
CTX_OUTPUT.START_QUERY_LOG('mylog1');
     < get queries >
CTX_OUTPUT.END_QUERY_LOG;
end;

ノート

PDBロックダウン・プロファイルCTX_LOGGINGが有効な場合、ログは書き込まれません。

CTX_OUTPUT.START_QUERY_LOGに使用されるファイル名の文字は、英数字、マイナス記号、ピリオド、スペース、ハッシュ記号、アンダースコア、一重引用符および二重引用符に制限されています。ファイル名にその他の文字が使用されていると、エラーが発生します。

ロギングはセッションに関連付けられています。1つのセッション内で発生する操作はログに記録できますが、逆に複数セッションにわたる操作はログに記録できません。