10 CTX_QUERYパッケージ

この章では、問合せフィードバックの生成、ヒット数のカウントおよびストアド・クエリー式の生成に使用できるPL/SQLパッケージCTX_QUERYについて説明します。

注意: このパッケージを使用できるのは、索引タイプがCONTEXTの場合のみです。このパッケージは、CTXCATの索引タイプをサポートしていません。

CTX_QUERYパッケージには、次のプロシージャおよびファンクションが含まれています。

名前	説明
BROWSE_WORDS	索引内のシード・ワードに関するワードを戻します。
COUNT_HITS	問合せへのヒット数を戻します。
EXPLAIN	問合せ式の解析および拡張情報を生成します。
HFEEDBACK	階層問合せフィードバック情報（上位語、下位語および関連語）を生成します。
REMOVE_SQE	指定したストアド・クエリー式をSQL表から削除します。
STORE_SQE	問合せを実行して、その結果をストアド・クエリー式表に格納します。

---

BROWSE_WORDS

このプロシージャを使用すると、Oracle Textの索引内のワードをブラウズできます。シード・ワードを指定すると、BROWSE_WORDSは索引内のそのシード・ワードに関するワード、および各ワードが含まれているドキュメントのおよその数を戻します。

この機能は、問合せの詳細化に有効です。次のワードを識別できます。

• 非選択的ワード（そのワードを含むドキュメント件数が少ないワード）

• ドキュメント・セットの中でスペルが間違っているワード

構文1: 表への結果の格納

ctx_query.browse_words(

index_name  IN   VARCHAR2,
seed        IN   VARCHAR2,
restab      IN   VARCHAR2,
browse_id   IN   NUMBER   DEFAULT 0,
numwords    IN   NUMBER   DEFAULT 10,
direction   IN   VARCHAR2 DEFAULT BROWSE_AROUND,
part_name   IN   VARCHAR2 DEFAULT NULL

);

構文2: メモリーへの結果の格納

ctx_query.browse_words(

index_name  IN      VARCHAR2,
seed        IN      VARCHAR2,
resarr      IN OUT  BROWSE_TAB,
numwords    IN      NUMBER   DEFAULT 10,
direction   IN      VARCHAR2 DEFAULT BROWSE_AROUND,
part_name   IN      VARCHAR2 DEFAULT NULL

);

index

索引の名前を指定します。schema.nameで指定できます。ローカル索引である必要があります。

seed

シード・ワードを指定します。このワードは、ブラウズ拡張の前にレクサー処理されます。ワードがトークン表に存在する必要はありません。seedは単一のワードである必要があります。複数のワードをシードとして使用すると、エラーになります。

restab

結果表の名前を指定します。restabは、schema.nameとして入力できます。このプロシージャのコール前に、表が存在している必要があります。また、表に対するINSERT権限が必要です。この表は、次のスキーマを持つ必要があります。

列	データ型
browse_id	number
word	varchar2(64)
doc_count	number

restabの中にある行が、BROWSE_WORDSがコールされる前に削除されることはありません。

resarr

結果配列の名前を指定します。resarrはctx_query.browse_tab型です。

type browse_rec is record (
   word varchar2(64),
   doc_count number
);
type browse_tab is table of browse_rec index by binary_integer;

browse_id

0〜2³²の間で数値識別子を指定します。このブラウズのために生成された行は、restabの中のbrowse_id列に値を持ちます。browse_idを指定しない場合、デフォルトは0（ゼロ）です。

numwords

戻すワード数を指定します。

direction

ブラウズの方向を指定します。次のいずれかを指定できます。

値	動作
BEFORE	シード・ワードおよびシードの前のワードをアルファベット順にブラウズします。
AROUND	シード・ワードおよびシードの前後のワードをアルファベット順にブラウズします。
AFTER	シード・ワードおよびシードの後のワードをアルファベット順にブラウズします。

記号CTX_QUERY.BROWSE_BEFORE、CTX_QUERY.BROWSE_AROUNDおよびCTX_QUERY.BROWSE_AFTERも、これらのリテラル値に対して定義されています。

part_name

ブラウズする索引パーティション名を指定します。

例

結果表でのワードのブラウズ

begin
ctx_query.browse_words('myindex','dog','myres',numwords=>5,direction=>'AROUND');
end;

select word, doc_count from myres order by word;

WORD       DOC_COUNT
--------   ----------
CZAR       15
DARLING    5
DOC        73
DUNK       100
EAR        3

結果配列でのワードのブラウズ

set serveroutput on;
declare
  resarr ctx_query.browse_tab;
begin
ctx_query.browse_words('myindex','dog',resarr,5,CTX_QUERY.BROWSE_AROUND);
for i in 1..resarr.count loop
  dbms_output.put_line(resarr(i).word || ':' || resarr(i).doc_count);
end loop;
end;

---

COUNT_HITS

指定した問合せへのヒット数を戻します。実測または予測モードでCOUNT_HITSをコールできます。実測モードは問合せへの正確なヒット数を戻します。予測モードは上限の見積りを戻しますが、実測モードよりも高速に実行します。

構文

構文1

exec CTX_QUERY.COUNT_HITS(
    index_name  IN VARCHAR2,
    text_query  IN VARCHAR2,
    exact       IN BOOLEAN  DEFAULT TRUE,
    part_name   IN VARCHAR2 DEFAULT NULL
) RETURN NUMBER;

構文2

exec CTX_QUERY.COUNT_HITS_CLOB_QUERY(
    index_name  IN VARCHAR2,
    text_query  IN CLOB,
    exact       IN BOOLEAN DEFAULT TRUE,
    part_name   IN VARCHAR2 DEFAULT NULL
) RETURN NUMBER;

index_name

索引の名前を指定します。

text_query

問合せを指定します。

exact

実測カウントにはTRUEを指定します。上限を見積るにはFALSEを指定します。

FALSEを指定することによって戻された数値はあまり正確ではありませんが、より高速に実行されます。 FULL索引が最後に最適化されてから行が更新または削除されている場合、FALSEを指定すると高すぎる数値が返されることがあります。このような不適切なヒットは完全モードでの最適化によって削除され、FALSEに設定されたEXACTと、TRUEに設定されたEXACTの戻す数値が同一になります。

part_name

問い合せる索引パーティション名を指定します。

注意

問合せに構造化基準が含まれている場合は、SELECT COUNT(*)を使用してください。

索引がTRANSACTIONALパラメータを使用して作成されている場合、COUNT_HITSには同期化済のROWIDの他に保留中のROWIDも含まれます。

---

EXPLAIN

問合せ式に関する実行計画情報を生成するには、CTX_QUERY.EXPLAINを使用します。実行計画では、テキスト問合せ式に対して解析ツリーがグラフィカル表示されます。この情報は結果表に格納されます。

このプロシージャは問合せを実行しません。かわりに、問合せの入力前に、その問合せの拡張および解析の方法をユーザーに知らせます。これは、特にSTEM、ワイルド・カード、シソーラス、FUZZY、SOUNDEXまたはABOUT問合せに有効です。解析ツリーには、次の情報も表示されます。

• 実行の順序（演算子の優先順位）

• ABOUT問合せの正規化

• 問合せ式の最適化

• ストップワード変換

• コンポジット・ワード・トークンの分類

Oracle Textによる問合せの評価方法を理解しておくと、問合せの詳細化やデバッグを行うときに役立ちます。また、実行計画情報を使用してユーザーがより高度な問合せを作成できるように、アプリケーションを設計できます。

構文

構文1

exec CTX_QUERY.EXPLAIN(

    index_name     IN VARCHAR2,
    text_query     IN VARCHAR2,
    explain_table  IN VARCHAR2,
    sharelevel     IN NUMBER DEFAULT 0,
    explain_id     IN VARCHAR2 DEFAULT NULL,
    part_name      IN VARCHAR2 DEFAULT NULL

);

構文2

exec CTX_QUERY.EXPLAIN_CLOB_QUERY(
    index_name     IN VARCHAR2,
    text_query     IN CLOB,
    explain_table  IN VARCHAR2,
    sharelevel     IN NUMBER DEFAULT 0,
    explain_id     IN VARCHAR2 DEFAULT NULL,
    part_name      IN VARCHAR2 DEFAULT NULL
);

index_name

問い合せる索引名を指定します。

text_query

行を選択する基準として使用する問合せ式を指定します。

text_queryにワイルド・カード、FUZZYまたはSOUNDEX演算子が含まれている場合、このプロシージャは索引表を調べて拡張を判断します。

ワイルド・カード、FUZZY（?）およびSOUNDEX（!）式のフィードバックでは、通常の問合せで削除が遅延した場合、その理由を判断できません。

explain_table

text_queryに対する解析ツリー表現の格納に使用する表の名前を指定します。EXPLAINからの結果を格納するには、表に対して少なくともINSERT権限およびDELETE権限が必要です。

関連項目: 実行計画表の構造の詳細は、付録A「Oracle Text結果表」の「実行計画表」を参照してください。

sharelevel

explain_tableを複数のEXPLAINコールで共有するかどうかを指定します。排他使用には0（ゼロ）を、共有使用には1を指定します。デフォルトは0（排他使用）です。

0（ゼロ）を指定すると、システムは次のEXPLAINのコールの前に自動的に結果表を切り捨てます。

共有使用の1を指定すると、このプロシージャは結果表を切り捨てません。同じexplain_idを持つ結果のみが更新されます。同じexplain_idの結果が存在しない場合は、新しい結果が実行計画表に追加されます。

explain_id

複数のEXPLAINコールが同じ共有実行計画表を使用する場合は、EXPLAINプロシージャが戻した実行計画結果を識別する名前を指定します。デフォルトはNULLです。

part_name

問い合せる索引パーティション名を指定します。

例

実行計画表の作成

たとえば、test_explainという名前の実行計画表を作成するには、次のSQL文を使用します。

create table test_explain(
         explain_id varchar2(30),
         id number,
         parent_id number,
         operation varchar2(30),
         options varchar2(30),
         object_name varchar2(64),
         position number,
         cardinality number);

CTX_QUERY.EXPLAINの実行

comp% OR ?smithなどの問合せ式の拡張を取得するには、次のようにCTX_QUERY.EXPLAINを使用します。

ctx_query.explain(
         index_name => 'newindex',
         text_query => 'comp% OR ?smith',
         explain_table => 'test_explain',
         sharelevel => 0,
         explain_id => 'Test');

実行計画表からのデータの取出し

実行計画表を読み込むには、次のように列を選択できます。

select explain_id, id, parent_id, operation, options, object_name, position
from test_explain order by id;

次のように、出力はID順に並べられ、階層問合せをシミュレートします。

EXPLAIN_ID    ID PARENT_ID OPERATION    OPTIONS OBJECT_NAME POSITION
----------- ---- --------- ------------ ------- ----------- --------
Test           1         0 OR           NULL    NULL          1
Test           2         1 EQUIVALENCE  NULL    COMP%         1
Test           3         2 WORD         NULL    COMPTROLLER   1
Test           4         2 WORD         NULL    COMPUTER      2
Test           5         1 EQUIVALENCE  (?)     SMITH         2
Test           6         5 WORD         NULL    SMITH         1
Test           7         5 WORD         NULL    SMYTHE        2

制限事項

CTX_QUERY.EXPLAINでは、問合せテンプレートの使用はサポートされていません。

リモート問合せでCTX_QUERY.EXPLAINは使用できません。

問合せにテーマが使用される場合（ABOUT問合せの場合など）は、ナレッジ・ベースがインストールされている必要があります。ナレッジ・ベースは、Oracle Textとともにインストールされていない場合があります。ナレッジ・ベースの詳細は、『Oracle Textアプリケーション開発者ガイド』を参照してください。

関連項目

第3章「Oracle Text CONTAINS問合せ演算子」

付録H「Oracle Textでのストップワード変換」

---

HFEEDBACK

英語またはフランス語の場合、このプロシージャは、指定された問合せへの階層問合せフィードバック情報（上位語、下位語および関連語）を生成します。

上位語、下位語および関連語情報はナレッジ・ベースから取得されます。ただし、索引中にも存在するナレッジ・ベース語句のみが、問合せフィードバック情報として戻ります。これによって、HFEEDBACKプロシージャから戻された語句が、現在索引付けされているドキュメント・セットよりヒットする可能性が高くなります。

階層問合せフィードバック情報は、他の問合せ語句をユーザーに提示する場合に有効です。

注意: CTX_QUERY.HFEEDBACKを使用するには、ナレッジ・ベースがインストールされている必要があります。ナレッジ・ベースは、Oracle Textとともにインストールされていない場合があります。ナレッジ・ベースの詳細は、『Oracle Textアプリケーション開発者ガイド』を参照してください。 CTX_QUERY.HFEEDBACKは、英語およびフランス語でのみサポートされています。

構文

構文1

exec CTX_QUERY.HFEEDBACK(
           index_name     IN VARCHAR2,
           text_query     IN VARCHAR2,
           feedback_table IN VARCHAR2,
           sharelevel     IN NUMBER DEFAULT 0,
           feedback_id    IN VARCHAR2 DEFAULT NULL,
           part_name      IN VARCHAR2 DEFAULT NULL
);

構文2

exec CTX_QUERY.HFEEDBACK_CLOB_QUERY(
           index_name     IN VARCHAR2,
           text_query     IN CLOB,
           feedback_table IN VARCHAR2,
           sharelevel     IN NUMBER DEFAULT 0,
           feedback_id    IN VARCHAR2 DEFAULT NULL,
           part_name      IN VARCHAR2 DEFAULT NULL
);

index_name

問い合せるテキスト列の索引の名前を指定します。

text_query

行を選択する基準として使用する問合せ式を指定します。

feedback_table

フィードバック語の格納に使用する表の名前を指定します。

関連項目: 実行計画表の構造の詳細は、付録A「Oracle Text結果表」の「HFEEDBACK表」を参照してください。

sharelevel

feedback_tableを複数のHFEEDBACKコールで共有するかどうかを指定します。排他使用には0（ゼロ）を、共有使用には1を指定します。デフォルトは0（排他使用）です。

0（ゼロ）を指定すると、システムは次のHFEEDBACKのコールの前に自動的にフィードバック表を切り捨てます。

共有使用の1を指定すると、このプロシージャはフィードバック表を切り捨てません。同じfeedback_idを持つ結果のみが更新されます。同じfeedback_idの結果が存在しない場合は、新しい結果がフィードバック表に追加されます。

feedback_id

複数のHFEEDBACKコールが同じ共有フィードバック表を使用する場合は、HFEEDBACKのコールによって戻されたフィードバック結果を識別する値を指定します。デフォルトはNULLです。

part_name

問い合せる索引パーティション名を指定します。

例

HFEEDBACK結果表の作成

CTX_QUERY.HFEEDBACKで使用する結果表を次のように作成します。

  CREATE TABLE restab (
    feedback_id VARCHAR2(30),
    id          NUMBER,
    parent_id   NUMBER,
    operation   VARCHAR2(30),
    options     VARCHAR2(30),
    object_name VARCHAR2(80),
    position    NUMBER,
    bt_feedback ctxsys.ctx_feedback_type,
    rt_feedback ctxsys.ctx_feedback_type,
    nt_feedback ctxsys.ctx_feedback_type
  ) NESTED TABLE bt_feedback STORE AS res_bt
    NESTED TABLE rt_feedback STORE AS res_rt
    NESTED TABLE nt_feedback STORE AS res_nt;

CTX_FEEDBACK_TYPEはCTXSYSスキーマのシステム定義型です。

関連項目: HFEEDBACK表の構造の詳細は、付録A「Oracle Text結果表」の「HFEEDBACK表」を参照してください。

CTX_QUERY.HFEEDBACKのコール

次のコードは、computer industryの問合せを持つHFEEDBACKプロシージャをコールします。

BEGIN
ctx_query.hfeedback (index_name     => 'my_index',
                     text_query     => 'computer industry',
                     feedback_table => 'restab',
                     sharelevel     => 0,
                     feedback_id    => 'query10'
                    );
END;

結果表からの選択

次のコードは、結果表からフィードバック・データを取り出します。このコードによって、上位語、下位語および関連語フィードバックをNESTED TABLEから個別に取り出します。

DECLARE
  i NUMBER;
BEGIN
  FOR frec IN (
    SELECT object_name, bt_feedback, rt_feedback, nt_feedback
    FROM restab
    WHERE feedback_id = 'query10' AND object_name IS NOT NULL
  ) LOOP

    dbms_output.put_line('Broader term feedback for ' || frec.object_name ||
':');
    i := frec.bt_feedback.FIRST;
    WHILE i IS NOT NULL LOOP
      dbms_output.put_line(frec.bt_feedback(i).text);
      i := frec.bt_feedback.NEXT(i);
    END LOOP;

    dbms_output.put_line('Related term feedback for ' || frec.object_name ||
':');
    i := frec.rt_feedback.FIRST;
    WHILE i IS NOT NULL LOOP
      dbms_output.put_line(frec.rt_feedback(i).text);
      i := frec.rt_feedback.NEXT(i);
    END LOOP;

    dbms_output.put_line('Narrower term feedback for ' || frec.object_name ||
':');
    i := frec.nt_feedback.FIRST;
    WHILE i IS NOT NULL LOOP
      dbms_output.put_line(frec.nt_feedback(i).text);
      i := frec.nt_feedback.NEXT(i);
    END LOOP;

  END LOOP;
END;

サンプル出力

次の出力は、computer industryについて問い合せる前述の例に対するものです。

Broader term feedback for computer industry:
hard sciences
Related term feedback for computer industry:
computer networking
electronics
knowledge
library science
mathematics
optical technology
robotics
satellite technology
semiconductors and superconductors
symbolic logic
telecommunications industry
Narrower term feedback for computer industry:
ABEND - abnormal end of task
AT&T Starlans
ATI Technologies, Incorporated
ActivCard
Actrade International Ltd.
Alta Technology
Amiga Format
Amiga Library Services
Amiga Shopper
Amstrat Action
Apple Computer, Incorporated
..

注意: 取得したHFEEDBACK情報は、索引およびナレッジ・ベースの内容に依存するため、示したサンプルの内容とは異なる可能性があります。

制限事項

CTX_QUERY.HFEEDBACKでは、問合せテンプレートの使用はサポートされていません。

---

REMOVE_SQE

CTX_QUERY.REMOVE_SQEプロシージャは、指定したストアド・クエリー式を削除します。

構文

CTX_QUERY.REMOVE_SQE(query_name IN VARCHAR2);

query_name

削除するストアド・クエリー式の名前を指定します。

例

begin
ctx_query.remove_sqe('disasters');
end;

---

STORE_SQE

このプロシージャは、ストアド・クエリー式を作成します。問合せ定義のみが格納されます。

サポートされている演算子

ストアド・クエリー式は、すべてのCONTAINS問合せ演算子をサポートしています。また、すべての特殊文字、および他のストアド・クエリー式も含めて、問合せ式で使用できるすべてのコンポーネントをサポートしています。

権限

ユーザーは、所有しているストアド・クエリー式を作成および削除できます。ユーザーは、誰が所有するストアド・クエリー式でも使用できます。CTXSYSユーザーは、どのユーザーのストアド・クエリー式も作成および削除できます。

構文

構文1

CTX_QUERY.STORE_SQE(query_name      IN VARCHAR2,
                    text_query      IN VARCHAR2);

構文2

CTX_QUERY.STORE_SQE_CLOB_QUERY(query_name      IN VARCHAR2,
                               text_query      IN CLOB);

query_name

作成するストアド・クエリー式の名前を指定します。

text_query

query_nameに関連付ける問合せ式を指定します。

例

begin
ctx_query.store_sqe('disasters', 'hurricanes | earthquakes');
end;