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

12 CTX_QUERYパッケージ

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

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

名前 説明

BROWSE_WORDS

索引内のシード・ワードに関するワードを戻します。

COUNT_HITS

問合せへのヒット数を戻します。

EXPLAIN

問合せ式の解析および拡張情報を生成します。

HFEEDBACK

階層問合せフィードバック情報(上位語、下位語および関連語)を生成します。

REMOVE_SQE

指定したストアド・クエリー式をSQL表から削除します。

RESULT_SET

問合せを実行して、結果セットを生成します。

RESULT_SET_CLOB_QUERY

問合せを実行して、CLOB問合せパラメータに基づいた結果セットを生成します。

RESULT_SET_DOCUMENT

CONTAINS問合せのカーソルを明示的にクローズした後で、問合せテンプレートに<ctx_result_set_descriptor>要素がある場合に、結果セット・ドキュメントを保持します。

STORE_SQE

問合せを実行して、その結果をストアド・クエリー式表に格納します。

ノート:

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

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

12.1 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から232の間で数値識別子を指定します。このブラウズのために生成された行は、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;

12.2 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も含まれます。

12.3 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権限が必要です。

関連項目:

実行計画表の構造の詳細は、「Oracle Text結果表」の「EXPLAIN表」を参照してください。

sharelevel

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

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

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

explain_id

複数のEXPLAINコールが同じ共有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(255),
         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は使用できません。

関連項目

Oracle Text CONTAINS問合せ演算子

Oracle Textでのストップワード変換

12.4 HFEEDBACK

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

上位語、下位語および関連語情報はナレッジ・ベースから取得されます。ただし、索引中にも存在するナレッジ・ベース語句のみが、問合せフィードバック情報として戻ります。これによって、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

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

関連項目:

実行計画表の構造の詳細は、「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表の構造の詳細は、「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: 
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では、問合せテンプレートおよびローリング・アップグレードの使用はサポートされていません。

12.5 REMOVE_SQE

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

CTX_QUERY.REMOVE_SQEを使用すると、セッション期間SQEと永続SQEの両方を削除できます。「STORE_SQE」を参照してください。

query_nameネームスペースは永続SQEとセッション期間SQEの間で共有されるため、削除するSQEの期間を指定する必要はありません。

構文

CTX_QUERY.REMOVE_SQE(
          query_name IN VARCHAR2
);
query_name

削除するストアド・クエリーまたはセッション期間問合せの式の名前を指定します。

例

begin
  ctx_query.remove_sqe('dis1');
  ctx_query.remove_sqe('dis2');
end;
/

12.6 RESULT_SET

このプロシージャは、XMLまたはJSON問合せを実行してXMLまたはJSONの結果セットを生成します。

結果セット・インタフェースは、SQLで表すことが困難なデータ・ビューを戻します。

関連項目:

XML結果セット・インタフェースの使用方法については、『Oracle Textアプリケーション開発者ガイド』を参照してください

構文

CTX_QUERY.RESULT_SET (
   index_name            IN VARCHAR2,
   query                 IN VARCHAR2,
   result_set_descriptor IN CLOB,
   result_set            IN OUT NOCOPY CLOB,
   part_name             IN VARCHAR2 DEFAULT NULL,
   format                IN NUMBER DEFAULT CTX_QUERY.XML_FORMAT
);
index_name

問合せを実行する索引を指定します。

query

問合せ文字列を指定します。

result_set_descriptor

XMLまたはJSONの結果セット記述子を指定します。結果セットに含む内容を示します。

result_set

出力結果セットを指定します。この変数にNULLを入力すると、セッション中に一時LOBが割り当てられてユーザーに戻ります。ユーザーは、この一時LOBの割当て解除の責任があります。

part_name

索引パーティション名を指定します。グローバル索引の場合、part_nameをNULLにする必要があります。パーティション索引でpart_nameがNULLではない場合、指定されたパーティションにのみ、問合せが評価されます。パーティション索引でpart_nameがNULLの場合、すべてのパーティションで問合せが評価されます。

format

結果セットの記述子の書式を指定します。XML形式の場合はCTX_QUERY.XML_FORMAT、JSON形式の場合はCTX_QUERY.JSON_FORMATを使用します。デフォルトはCTX_QUERY.XML_FORMATです。

入力結果セット記述子

結果セット記述子は、結果セットの計算対象を示すXMLメッセージまたはJSONオブジェクトです。結果セット記述子の要素とその出現順序は、出力結果セットの内容を指定する簡単なテンプレートとして使用できます。つまり、ヒットしたROWIDのリスト、カウント、トークン数などを指定します。要素の属性には、ROWIDリストのヒット数や予測カウントおよび実測カウントなど、特定の操作のパラメータおよびオプションを指定します。

XML形式の入力結果セット記述子

結果セット記述子自体は、次のDTDに準拠したXMLです。

<!DOCTYPE ctx_result_set_descriptor [
<!ELEMENT ctx_result_set_descriptor (hitlist?, group*, count?, collocates?)>
<!ELEMENT hitlist (rowid?, score?, sdata*, snippet*, sentiment?)>
<!ELEMENT group (count?, group_values?)>
<!ELEMENT count EMPTY>
<!ELEMENT rowid EMPTY>
<!ELEMENT score EMPTY>
<!ELEMENT sdata EMPTY>
<!ELEMENT group_values (value*)>
<!ELEMENT value EMPTY>
<!ELEMENT sentiment (item*)>
<!ELEMENT item EMPTY>
<!ELEMENT collocates EMPTY>
<!ATTLIST sentiment classifier CDATA "DEFAULT_CLASSIFIER">
<!ATTLIST item topic CDATA #REQUIRED>
<!ATTLIST item type (about|exact) "exact">
<!ATTLIST item agg (TRUE|FALSE) "FALSE">
<!ATTLIST item radius CDATA "50">
<!ATTLIST item max_inst CDATA "5">
<!ATTLIST item starttag CDATA #IMPLIED>
<!ATTLIST item endtag CDATA #IMPLIED>
<!ATTLIST collocates radius CDATA "20">
<!ATTLIST collocates max_words CDATA "10">
<!ATTLIST collocates use_tscore (TRUE|FALSE) "TRUE">
<!ATTLIST collocates use_hits CDATA "10">
<!ATTLIST group sdata CDATA #REQUIRED>

<!ATTLIST group topn CDATA #IMPLIED>
<!ATTLIST group bucketby CDATA #IMPLIED>
<!ATTLIST group sortby CDATA #IMPLIED>
<!ATTLIST group order CDATA #IMPLIED>
<!ATTLIST value id CDATA #IMPLIED>
<!ATTLIST hitlist start_hit_num CDATA #REQUIRED>
<!ATTLIST hitlist end_hit_num CDATA #REQUIRED>
<!ATTLIST hitlist order CDATA #IMPLIED>
<!ATTLIST count exact (TRUE|FALSE) "FALSE">

<!ATTLIST sdata name CDATA #REQUIRED>
<!ATTLIST snippet radius CDATA #IMPLIED>
<!ATTLIST snippet max_length CDATA #IMPLIED>
<!ATTLIST snippet starttag CDATA #IMPLIED>
<!ATTLIST snippet endtag CDATA #IMPLIED>
]>

結果セット記述子に有効なXML要素は、次のとおりです。

  • ctx_result_set_descriptor

    これは、結果セット記述子のルート要素です。親要素と使用できる属性はありません。

    有効な子要素は、次のとおりです。

    • 0(ゼロ)個以上のhitlist要素。

    • 0(ゼロ)個以上のgroup要素。

    • 1つのcount要素。

  • group

    group要素は、生成された結果セットをグループに分類します。つまり、SDATAセクションの値を使用して、結果を分類します。ファセット・ナビゲーションをサポートする場合は、ファセット数を取得するためにgroup要素も使用します。親要素はctx_result_set_descriptorです。使用できる属性は、次のとおりです。

    • sdata

      グループ化に使用するSDATAセクションの名前を指定します。これは必須です。

    • bucketby

      カウントの際にグループ値をバケット化する方法を決定します。single属性には、一意の各ファセット値とその数が表示されます。Oracle Databaseリリース21c以上では、数値ファセットの範囲とその数を表示するcustom属性値もサポートされています。

    • topn

      返されるファセット値の最大数を制限します。デフォルトでは、降順のグループ数でソートされます。有効な属性値は、ゼロより大きい正の整数です。

    • sortby

      有効な属性値は、valueとcountです。valueは、その値自体を使用して、それぞれのデータ型に応じてソートされます。count (デフォルト)は、グループごとのカウント数を使用してソートされます。

    • order

      順序は、昇順または降順にできます。

    groupの有効な子要素は、次のとおりです。

    • count

    • range

  • hitlist

    hitlist要素は、ヒットしたドキュメントのリストの包含を制御します。親要素はctx_result_set_descriptorです。使用できる属性は、次のとおりです。

    hitlistで使用できる属性要素は、次のとおりです。

    • start_hit_num

      生成された結果セットに含める最初にヒットしたドキュメントを指定します。16000以下の正の整数を設定できます。たとえば、start_hit_numが21の場合、21番目にヒットしたドキュメントから結果セットにヒットしたドキュメントが格納されます。この要素は必須です。

    • end_hit_num

      生成された結果セットに含める最後にヒットしたドキュメントを指定します。48000以下の正の整数を設定できます。たとえば、end_hit_numが40の場合、40番目にヒットしたドキュメントまで結果セットにヒットしたドキュメントが格納されます。この要素は必須です。

    • order

      生成された結果セットにドキュメントの順序を指定するオプション属性です。値は、SQL ORDER BY文と類似するリストです。ただし、列名のかわりにSCOREまたはSDATAセクション名を使用できます。次の例では、MYDATEとMYPRICEがSDATAセクション名です。 

      (order = "SCORE DESC, MYDATE, MYPRICE DESC")

      hitlistで使用できる子要素は、次のとおりです。

    • 1つのrowid要素。

    • 1つのscore要素。

    • 1つ以上のsdata要素。

    • 1つのsnippet要素。

  • count

    生成された結果セットにヒットしたドキュメントの数を格納します。親要素は、次のとおりです。

    • ctx_result_set_descriptor

    • group

    countで使用できる属性は、次のとおりです。

    • exact

      予測モードに使用します。trueまたはfalseに設定します。これは必須です。デフォルトは、falseです。

    countの有効な子要素はありません。

  • rowid

    生成された結果セットにヒットごとのROWID情報を格納します。親要素は、hitlistです。属性および有効な子要素はありません。

  • score

    生成された結果セットにヒットごとのスコア情報を格納します。

    • 親要素は、hitlistです。

    • 使用できる属性および有効な子要素はありません。

  • sdata

    生成された結果セットにヒットごとのsdata値を格納します。

    • 親要素は、hitlistです。

    • 使用できる属性はnameです。sdataセクションの名前を指定します。これは必須です。

    • 子要素はありません。

  • sentiment

    この要素は、hitlistの部分として戻される各ドキュメントに対するセンチメント分類結果の包含を制御します。hitlist要素内のセンチメント要素は、1つのみです。

    親要素は、hitlistです。

    この要素で使用可能な属性は、classifierです。これは、センチメント分析の実行で使用するセンチメント分類子を指定します。分類子が指定されない場合、CTXSYS.DEFAULT_SENTIMENT_CLASSIFIERを使用します。指定した分類子が使用できない場合、エラーが表示されます。

  • item

    この要素は、戻されたドキュメントのセットにセンチメント情報をフェッチする必要があるキーワードまたは概念を指定します。各sentiment要素には、少なくとも1つの子item要素を含める必要があります。子item要素の最大数は、10です。空のitem要素を指定する(属性を指定しない)と、ドキュメント全体のセンチメント・スコアが戻されます。

    親要素は、sentimentです。

    itemで使用できる属性は、次のとおりです。

    • topic

      これは、センチメント分析が実行されるトピックを指定します。

    • type

      この属性がABOUTに設定されると、分類子は、指定されたトピックをキーワードではなく概念として処理します。デフォルトはEXACTです。

    • agg

      センチメント・スコアを集計し、ドキュメント全体に対する単一スコアとして提示するか、決定します。値は、TRUEまたはFALSEのいずれかです。TRUEを指定すると、テキスト・セグメントごとのスコアが集計され、テキスト・セグメントは出力結果には戻されず、集計スコアのみが戻されます。デフォルト値は、FALSEです。

    • radius

      キーワードのセンチメント分類中に識別するテキストの周囲の半径を指定します。デフォルト値は50です。

    • max_inst

      センチメント分類で分析する、指定されたトピックに関連するテキスト抜粋のインスタンスの数を指定します。デフォルト値は5です。

    • starttag

      トピックのハイライトを開始するタグを指定します。

    • endtag

      トピックのハイライトを終了するタグを指定します。

  • コロケート

    この要素は、問合せで取得された一連のドキュメントに関連するキーワードまたは概念の生成を制御します。

    親要素は、ctx_result_set_descriptorです。

    collocatesで使用できる属性は、次のとおりです。

    • radius

      コロケートで識別するテキストの周囲の半径を指定します。デフォルト値は20です。

    • max_words

      指定された問合せで返されるコロケートの最大数を指定します。デフォルト値は10です。

    • use_tscore

      コロケートのスコアリングでTスコアを使用するかどうか、指定します。値は、TRUEまたはFALSEのいずれかで、デフォルトはTRUEです。

      この属性をTRUEに設定すると、共通トークンのコロケートを識別できます。この属性をFALSEに設定すると、一意の語を強調するコロケートを識別できます。

出力結果セットXML

出力結果セットXMLは、次のDTDに準拠したXMLです。

<!DOCTYPE ctx_result_set [
<!ELEMENT ctx_result_set (hitlist?, groups*, count? , collocates?)>
<!ELEMENT hitlist (hit*)>
<!ELEMENT hit (rowid?, score?, snippet*, sdata*, sentiment?)>
<!ELEMENT groups (group*)>
<!ELEMENT group (count?)>
<!ELEMENT count (#PCDATA)>
<!ELEMENT rowid (#PCDATA)>
<!ELEMENT score (#PCDATA)>
<!ELEMENT snippet (segment*)>
<!ELEMENT sdata (#PCDATA)>
<!ELEMENT sentiment (item*)>
<!ELEMENT item (segment*, score*, doc?)>
<!ELEMENT segment (segment_text?, segment_score?)>
<!ELEMENT segment_text (#PCDATA)>
<!ELEMENT segment_score (#PCDATA)>
<!ELEMENT doc (score?)>
<!ELEMENT collocates (collocation*)>
<!ELEMENT collocation (word?, score?)>
<!ELEMENT word (#PCDATA)>
<!ATTLIST item topic CDATA #REQUIRED>
<!ATTLIST groups sdata CDATA #REQUIRED>
<!ATTLIST group value CDATA #REQUIRED>

<!ATTLIST group range CDATA #IMPLIED>
<!ATTLIST group single CDATA #IMPLIED>
<!ATTLIST sdata name CDATA #REQUIRED>

出力結果セットに有効なXML要素のリストは、次のとおりです。

  • ctx_result_set

    生成された結果セットのルート要素です。属性はありません。親要素はありません。有効な子要素は、次のとおりです。

    • 1つのhitlist要素。

    • 0(ゼロ)個以上のgroups要素。

  • groups

    グループ分類セクションの開始を区切ります。親要素は、ctx_result_setです。使用できる属性は、次のとおりです。

    • sdata

      グループ化に使用するsdataセクションの名前です。

    有効な子要素は、次のとおりです。

    • 0(ゼロ)個以上のgroup要素。

  • group

    GROUP BYの値の開始を区切ります。親要素は、groups要素です。使用できる属性は、次のとおりです。

    • value

      sdataセクションの値です。

    有効な子要素は、1つのcount要素です。

  • hitlist

    hitlist情報の開始を区切ります。親要素はctx_result_setです。子は0個以上のhit要素です。属性はありません。

  • hit

    hitlist内の特定のドキュメントの情報の開始を区切ります。親要素はhitlistです。使用できる属性はありません。有効な子要素は、次のとおりです。

    • 0(ゼロ)個または1個のrowid要素。

    • 0(ゼロ)個または1個のscore要素。

    • 0(ゼロ)個または1個のsdata要素。

    • ゼロまたは1つのsnippet要素。

  • rowid

    ドキュメントのROWIDです。ドキュメントのROWIDが格納されます。親要素は、hit要素です。子要素および使用できる属性はありません。

  • score

    ドキュメントのスコアです。親要素は、hit要素です。数値のスコアが格納されます。使用できる属性および有効な子要素はありません。

  • sdata

    ドキュメントのSDATAの値です。親要素は、hit要素です。使用できる属性は、sdataセクション名のnameです。有効な子要素はありません。SDATAセクション値が格納されます。DATEの値は「YYYY-MM-DD HH24:MI:SS」形式で、格納される実際の値によって異なります。

  • count

    ドキュメントのヒット数です。親要素は、ctx_result_set要素またはgroup要素です。数値のヒット数が格納されます。属性および有効な子要素はありません。

  • sentiment

    hitlistドキュメントのセンチメント要素を区切ります。子要素はitemで、親はhitlistです。出力結果セットに属性は含まれません。

  • item

    hitlistドキュメントのitem要素を区切ります。親要素はsentimentで、子要素はsegment、scoreおよびdocです。topicという属性を1つ持ちます。

  • segment

    ヒント内のセグメント要素のインスタンスを区切ります。親要素はitemです。子要素はsegment_textおよびsegment_scoreです。属性は含まれません。

  • segment_text

    指定されたアイテム・トピックに対してテキスト・セグメントを指定します。親要素はsegmentです。子要素も属性もありません。

  • segment_score

    セグメントに対するセンチメント・スコアを指定します。親要素はsegmentです。子要素も属性もありません。

  • score

    ドキュメントまたは親アイテム・トピックに対するセンチメント・スコアを指定します。コロケーション内に存在する場合、特定のコロケーション・キーワードに対するコロケーション・スコアを指定します。親要素はdocまたはcollocationです。子要素も属性もありません

  • doc

    ドキュメント全体のセンチメント・スコアであることを示します。親要素はitemで、子要素はscoreです。DIRECT_DATASTOREに属性はありません。

  • コロケート

    結果セットの出力のコロケート要素を区切ります。親要素はctx_result_setで、子要素はcollocationです。DIRECT_DATASTOREに属性はありません。

  • collocation

    単一コロケーションを示します。親要素はcollocatesで、子要素はwordおよびscoreです。DIRECT_DATASTOREに属性はありません。

  • word

    コロケート・トークンを指定します。親要素はcollocationです。子要素も属性もありません。

例

XMLのresult_set_descriptorを指定したCTX_QUERY.RESULT_SETのこのコールは、XML形式で次の情報を生成します。

  • pubDate SDATAセクション値のDESCおよびスコアのDESCで順序付けられた、スコア、ROWID、author SDATAセクション値、およびpubDate SDATAセクション値を表示する上位5個のヒット

  • テキスト問合せのドキュメントの総ヒット数

  • pubDate SDATAセクション値でグループ化した数

  • author SDATAセクション値でグループ化した数 

declare
  rs clob;
begin
  dbms_lob.createtemporary(rs, true, dbms_lob.session);
  ctx_query.result_set('docidx', 'oracle', '
  <ctx_result_set_descriptor>  
   <count/>
   <hitlist start_hit_num="1" end_hit_num="5" order="pubDate desc, score desc">
     <score/>
     <rowid/>
     <sdata name="author"/>
     <sdata name="pubDate"/>
   </hitlist>
   <group sdata="pubDate">
     <count/>
   </group>
   <group sdata="author">
     <count/>
   </group>
  </ctx_result_set_descriptor>
', rs);
  dbms_lob.freetemporary(rs);
exception
  when others then
   dbms_lob.freetemporary(rs);
   raise;
end;
/

結果セットの出力CLOBのXML出力ストアは、次のようになります。

<ctx_result_set>
  <hitlist>
    <hit>
      <score>3</score><rowid>AAAPoEAABAAAMWsAAC</rowid>
      <sdata name="AUTHOR">John</sdata>
      <sdata name="PUBDATE">2001-01-03 00:00:00</sdata>
    </hit>
    <hit>
      <score>3</score><rowid>AAAPoEAABAAAMWsAAG</rowid>
      <sdata name="AUTHOR">John</sdata>
      <sdata name="PUBDATE">2001-01-03 00:00:00</sdata>
    </hit>
    <hit>
      <score>3</score><rowid>AAAPoEAABAAAMWsAAK</rowid>
      <sdata name="AUTHOR">John</sdata>
      <sdata name="PUBDATE">2001-01-03 00:00:00</sdata>
    </hit>
    <hit>
      <score>3</score><rowid>AAAPoEAABAAAMWsAAO</rowid>
      <sdata name="AUTHOR">John</sdata>
      <sdata name="PUBDATE">2001-01-03 00:00:00</sdata>
    </hit>
    <hit>
      <score>3</score><rowid>AAAPoEAABAAAMWsAAS</rowid>
      <sdata name="AUTHOR">John</sdata>
      <sdata name="PUBDATE">2001-01-03 00:00:00</sdata>
    </hit>
  </hitlist>
 
  <count>100</count>
 
  <groups sdata="PUBDATE">
    <group value="2001-01-01 00:00:00"><count>25</count></group>
    <group value="2001-01-02 00:00:00"><count>50</count></group>
    <group value="2001-01-03 00:00:00"><count>25</count></group>
  </groups>
 
  <groups sdata="AUTHOR">
    <group value="John"><count>50</count></group>
    <group value="Mike"><count>25</count></group>
    <group value="Steve"><count>25</count></group>
  </groups>
 
</ctx_result_set>

JSON形式の入力結果セット記述子

JSON形式の結果セット記述子は、$query、$searchおよび$facet部分で構成されています。JSON形式の結果セット記述子を使用すると、コンテキスト索引とJSON検索索引を問い合せることができます。これは次の形式です。 

{
  "$query": <text query and filter conditions>,
  "$search": <search result specifications>,
  "$facet": <faceted result specifications>	
}

  • $query

    $queryを使用して、検索問合せ、パス制約および追加パス・ベースのフィルタ条件を指定します。$queryを指定すると、CTX_QUERY.RESULT_SETプロシージャのqueryパラメータは無視されます。

    ノート:

    $query部分は、JSON検索索引が列に存在する場合にのみサポートされます。Oracle Text索引がある場合は、$query部分を指定できません。

    $queryは、Simple Oracle Document Access (SODA)フィルタ指定のサブセットであり、例による問合せ(QBE)またはフィルタとも呼ばれます。次の句のみがサポートされます。

    • Contains Clause - contains句は、1つの$contains演算子を含むオブジェクトが後に続くフィールドであり、その値は文字列です。フィールド値の文字列または数値が、配列要素を含むどこかの文字列オペランドと一致する場合にのみ、ドキュメントと一致します。一致はOracle Textの全文です。contains句は、QBEの最も外側の条件でのみ使用できます。$and演算子内の最上位レベルでのみ複数のcontains句を使用することもできます。

      たとえば、次のQBEは、「doe」という単語を含む「name」フィールド、および数値10または文字列「10」を単語として含む「address」フィールドをチェックします。

      {
  "$and" : [
  {"name": { "$contains" : "doe" } }, 
     {  "address" : { "$contains" : "10" } }
  ]
}

      ノート:

      • パスの間に他のパス・ステップを含めるには、contains句でワイルドカード・フィールド・ステップ(*)を使用します。たとえば:

        address.*.name

      • パスの間に子孫パス・ステップを含めるには、contains句で子孫表記(..)を使用します。たとえば:

        address..name2

        この問合せでは、name2がaddressの子孫とみなされ、表のaddressレコードと一致します。

      • $containsフィールド条件は、単純な$contains問合せの一部として、または最も外側の$and条件の一部としてのみ使用できます。$or条件の一部または内部の$and条件の一部として使用することはできません。実行すると、エラーが発生します。

    • フィールド条件句 - フィールド条件句はJSONオブジェクト・メンバーで、そのフィールドは演算子でなく、その値が条件演算句である1つ以上のメンバーを含むオブジェクトです。 

      field : { condition-operator-clause ... }
      次の条件演算子のみがサポートされています。

      • $eq - フィールドの値がオペランドの値と同じで、オペランドがJSONスカラー値である場合にドキュメントに一致します。また、フィールドの値が配列オブジェクトであり、オペランドの値がその配列の要素である場合にドキュメントに一致します。

      • $gt - フィールドの値がオペランドの値より大きい場合にのみ、ドキュメントと一致します。オペランドは、JSON数値または文字列である必要があります。

      • $gte - フィールドの値がオペランドの値以上の場合にのみ、ドキュメントと一致します。オペランドは、JSON数値または文字列である必要があります。

      • $lt - フィールドの値がオペランドの値より小さい場合にのみ、ドキュメントと一致します。オペランドは、JSON数値または文字列である必要があります。

      • $lte - フィールドの値がオペランドの値以下の場合にのみ、ドキュメントと一致します。オペランドは、JSON数値または文字列である必要があります。

      ノート:

      • ワイルドカード・フィールドのステップ(*)および配列ステップ([および])はサポートされていません。

      • 文字列値のフィールド条件をサポートするには、search_on text_value_stringによるJSON検索索引が必要です。

    • 論理組合せ句 - 論理組合せ句は、複数の空でないフィルタ条件の結果を組み合せます。論理組合せ句は論理組合せ演算子($andまたは$or)であり、空でない1つ以上のフィルタ条件の空でない配列が後に続きます。演算子の句の値には、数値または文字列値のみを指定できます。

    次の例は、サポートされている句を含む$query部分です。 

    "$query" :
{
  "$and" : [
    { "book.*.summary" : {  "$contains" : "(Music or Song) and Dance"  } },
    { "book.*.review" : {  "$contains" : "(Good or excellent) and interesting"  } },
    { "$or" : [
      { "book.rating" : { "$gte" : 4.5 } },
      { "$and" : [  { "book.price" : { "$lte" : 100 } },  { "book.author" : { "$eq" : "Doe" } } ] }
    ]
  ]
}

  • $search

    $searchを使用して、スコア・ランク付けされた検索結果とその件数を表示します。JSON以外のOracle Text全文索引の場合は、検索結果を予測するSDATAセクションを指定することもできます。

    次の属性を使用できます。

    • startおよびend - 検索結果の範囲を指定します。たとえば、start = 1およびend = 10の場合は、最初の10のドキュメントが戻されます。

    • project - 検索結果に対して投影するSDATAセクションのリストを指定します。この属性は、JSON以外のOracle Text全文索引に対してのみサポートされます。

  • $facet

    $facetを使用してJSONドキュメントの様々なパスまたはコンテキスト索引ドキュメントのSDATAセクションに対するファセットを指定します。単一の一意の値によってバケット化されたファセット、およびユーザー指定の範囲バケット別のファセットがサポートされています。ファセットは、COUNT、MINなどの集計のいずれかである場合もあります。

    ファセット・オブジェクトは、次の方法で指定できます。

    • 出力に指定したフィールドの単一の一意の値ごとにファセット・グループ数が含まれる文字列または数値としてのフィールド。

      { "$uniqueCount": { "path/sdata" : field,  "type" (Optional) : "string/number" } }
      詳細は次のとおりです。

      • fieldは、pathの使用時にJSON検索索引を使用する問合せ用のSODAパス、およびsdataの使用時にコンテキスト索引を使用する問合せ用のSDATAセクション名を参照します。

      • typeは、string (デフォルト)またはnumberのいずれかです。sdataを使用している場合は、各sdataにすでに事前定義された型が含まれているため、typeパラメータを使用できません。

    • JSON検索索引を使用する場合の文字列値専用のフィールド。fieldは、JSON検索索引を使用して問合せするためのSODAパスを示します。 

      { "$uniqueCount": field }

    • バケット範囲を使用してファセット・グループで集計を計算するためのフィールド。

      { 
  "$op : {
     "path/sdata" : field ,
     "bucket <Optional>" : [ { "$gt/$gte (Optional)" : <lower bound 1>, 
                               "$lt/$lte (Optional)" : <upper bound 1>}, ... ],
     "type" <Optional> : "string/number"
         }
}
      詳細は次のとおりです。
      • $opは、$sum、$min、$max、$avgまたは$countのいずれかです。

      • fieldは、pathの使用時にJSON検索索引を使用する問合せ用のSODAパス、およびsdataの使用時にコンテキスト索引を使用する問合せ用のSDATAセクション名を参照します。

      • 各範囲バケットには、最大で1つの下限($gtまたは$gte)と上限($ltまたは$lte)が必要です。

      • typeは、number (デフォルト)またはstringのいずれかです。sdataを使用している場合は、各sdataにすでに事前定義された型が含まれているため、typeパラメータを使用できません。

      ノート:

      $sumおよび$avg集計は、typeパラメータの値がnumberであるか、sdataが数値型である場合にのみサポートされます。string型には、$count、$minおよび$maxのみを使用できます。

    • バケット範囲を使用せずに数値ファセットで集計を計算するための専用フィールド。

      { "$op" : <field> }

      $opは、$sum、$min、$max、$avgまたは$countのいずれかです。

    次に、$facet部分の例を示します。 

    "$facet": [
          { 
          "$sum" : { 
                    "path" : "book.price", 
                    "bucket" : [ { "$lt" : 100 }, { "$gte" : 100, "$lt" : 150 }, { "$gte" : 150 } ]
                   }
          },
          {
          "$count" : { 
                      "path" : "book.author", 
                      "bucket" : [ {"$lt" : "G"}, {"$gte" : "G", "$lt" : "S"}, {"$gte" : "S"} ],
                      "type" : "string"
                     }
          },
          { "$uniqueCount" : "book.author" },
          { "$uniqueCount " : { "path" : "book.rating", "type" : "number" } },
          { "$avg" :  "book.sales" }
          { "$min" :  "book.name",  "type" : "string" }
         ]
    この例では、次が生成されます。

    • 指定されたbook.priceの各バケット範囲の価格の合計

    • 指定された範囲内の作成者の総数

    • book.authorの一意の値ごとのグループ数

    • 評価を数値として扱うbook.ratingごとのグループ数

    • 問合せを満たしたすべての本の売上の平均

    • 辞書的に最も短い作成者の名前

    ノート:

    文字列値のファセットをサポートするには、search_on text_value_stringによるJSON検索索引が必要です。

JSON形式の結果セットの出力

JSON形式の結果セット出力は、次の部分で構成されるJSONオブジェクトです。

"$count" : number
"$hit" : [ <hit_object_1>, ..., <hit_object_i> , ... ]
"$facet": [ <facet_object_1>, ..., <facet_object_i>, ...]
出力結果セットに有効なJSONオブジェクトのリストは、次のとおりです。

  • $count

    $count JSONオブジェクトは、問合せのヒットの合計数を示します。

  • $hit

    $hit JSONオブジェクトは、入力問合せの$search部分にstartおよびendを使用して指定されたヒット数に応じて、検索スコアの降順でソートされた検索ヒット・オブジェクトの配列を示します。次の属性が含まれます。

    • score

      score属性は、各ヒットのスコア情報を示します。

    • rowid

      rowid属性は、各ヒットのROWID情報を示します。

    • project

      project属性は、入力問合せの$search部分で指定されたsdata値を示します。project属性は、JSON以外のOracle Text全文索引に対してのみサポートされます。

  • $facet

    $facet JSONオブジェクトは、入力問合せの$facet部分で指定されたすべてのファセットに対するファセット・レスポンスの配列を示します。

    一意の各入力文字列または数値の数を列挙するための出力形式は、次のとおりです。

    { "<field>" : [ ..., { "value" : <value_i>, "$uniqueCount" : <group_count_i>}, ...  ]}

    ファセット・グループの集計を計算するために入力に指定されたバケットの数を列挙するための出力形式は、次のとおりです。

    { "<field>" : [ ..., { "bucket" : <bucket_object_i>, "<op>" : <group_count_i>}, ...  ]}

    ノート:

    バケット出力で、下限($gtまたは$gte)または上限($ltまたは$lte)が入力で指定されていない場合、最小値または最大値が検出され、出力に表示されます。

    バケットを使用せずに数値ファセットの集計を計算するための数を列挙する出力形式は、次のとおりです。

    { "<field>" : { "<op>" : <actual_value of the aggregation> } }

例12-1 CONTEXT索引を持つJSON形式の結果セット・インタフェースの使用

この例は、CONTEXT索引を持つJSON形式の結果セット・インタフェースの使用方法を示しています。

表を作成し、値を移入します。

drop table zebra_table;
create table zebra_table(id number, details clob);

INSERT INTO zebra_table
VALUES (1,'  Zebra details : <price>2000</price><price>1000</price>
                             <name>Storm</name>
                             <stripes>Dark</stripes><stripes>Light</stripes>  
                             <handler>Bob</handler>
                             <sold>true</sold>');

INSERT INTO zebra_table
VALUES (2,'  Zebra details : <rating>5</rating> <price>1000</price>
                             <name>Snowy</name>   
                             <stripes>Light</stripes><stripes>Grey</stripes>  
                             <handler>Jane Doe</handler>
                             <sold>true</sold>');

INSERT INTO zebra_table
VALUES (3,'  Zebra details : <rating>4.5</rating> <price>3000</price>
                             <name>Zigs</name>   
                             <stripes>Grey</stripes><stripes>Dark</stripes>  
                             <handler>Jane Doe</handler>
                             <sold>false</sold>');

INSERT INTO zebra_table
VALUES (4,'  Zebra details : <rating>4.5</rating> <price>3000</price>
                             <name>Zigs</name>
                             <stripes>Grey</stripes><stripes>Dark</stripes>
                             <handler>Jane Doe</handler> <sold></sold>');

mysecgrpという名前のセクション・グループを作成し、各列がファセットとして処理されるようにoptimized_for search属性を有効にします。 

exec ctx_ddl.drop_section_group   ('mysecgrp')
exec ctx_ddl.create_section_group ('mysecgrp', 'BASIC_SECTION_GROUP')

exec ctx_ddl.add_sdata_section    ('mysecgrp', 'rating', 'rating', 'NUMBER')
exec ctx_ddl.set_section_attribute('mysecgrp', 'rating', 'optimized_for', 'search')

exec ctx_ddl.add_sdata_section    ('mysecgrp', 'price', 'price', 'NUMBER')
exec ctx_ddl.set_section_attribute('mysecgrp', 'price', 'optimized_for', 'search')

exec ctx_ddl.add_sdata_section    ('mysecgrp', 'name', 'name', 'VARCHAR2')
exec ctx_ddl.set_section_attribute('mysecgrp', 'name', 'optimized_for', 'search')

exec ctx_ddl.add_sdata_section    ('mysecgrp', 'stripes', 'stripes', 'VARCHAR2')
exec ctx_ddl.set_section_attribute('mysecgrp', 'stripes', 'optimized_for', 'search')

exec ctx_ddl.add_sdata_section    ('mysecgrp', 'handler', 'handler', 'VARCHAR2')
exec ctx_ddl.set_section_attribute('mysecgrp', 'handler', 'optimized_for', 'search')

exec ctx_ddl.add_sdata_section    ('mysecgrp', 'sold', 'sold', 'VARCHAR2')
exec ctx_ddl.set_section_attribute('mysecgrp', 'sold', 'optimized_for', 'search')

detailsにCONTEXT索引を作成し、parameters句を使用してプリファレンスを指定します。 

create index zebra_idx on zebra_table(details)
indextype is ctxsys.context
parameters('section group mysecgrp');
JSONのresult_set_descriptorを指定したCTX_QUERY.RESULT_SETのコールは、JSON形式で次の情報を生成します。

  • 最初の2つのヒットのROWID、名前およびハンドラ

  • 一意のシマウマ名の合計数

  • 売れたシマウマと売れ残ったシマウマの合計数

  • 価格に応じたシマウマの合計数

  • 価格と平均評価の合計に基づく、合計ヒット数および一意数の価格範囲内の価格と平均評価の合計

  • 特定の範囲内のハンドラ名でグループ化されたシマウマの合計数

variable rs_output clob;

declare
  qry varchar2(4000);
  rs_descriptor clob;
begin
  qry := 'zebra details';
  rs_descriptor := '
{
  "$search" : { "start" : 1,  "end" : 2, "project" : [ "name", "handler" ] },
  "$facet" : [ 
                   { "$uniqueCount" : "name" },
                   { "$uniqueCount" : "sold" },
                   { "$uniqueCount" : { "sdata" : "price" } },
                   { "$sum" : { "sdata" : "price", 
                                "bucket" : 
                                  [ { "$lt" : 3000 }, { "$gte" : 3000 } ] 
                              } 
                   },
                   { "$avg" : "rating" },
                   { 
                     "$count" : { "sdata" : "handler",   
                                  "bucket" : 
                                    [ { "$lte" : "C" }, { "$gt" : "C" } ]  
                                } 
                   }
             ]
}
';
  dbms_lob.createtemporary( :rs_output, true );
  ctx_query.result_set( 'zebra_idx', qry, rs_descriptor, :rs_output, 
                        format => CTX_QUERY.JSON_FORMAT );
end;
/

select json_query(:rs_output, '$' pretty) from dual;

出力は次のようになります。

{
  "$count" : 4,
  "$hit" :
  [
    {
      "score" : 3,
      "rowid" : "AAASxXAABAAAY95AAA",
      "project" :
      {
	"NAME" : "Storm",
	"HANDLER" : "Bob"
      }
    },
    {
      "score" : 3,
      "rowid" : "AAASxXAABAAAY95AAB",
      "project" :
      {
	"NAME" : "Snowy",
	"HANDLER" : "Jane Doe"
      }
    }
  ],
  "$facet" :
  [
    {
      "NAME" :
      [
	{
	  "value" : "Zigs",
	  "$uniqueCount" : 2
	},
	{
	  "value" : "Snowy",
	  "$uniqueCount" : 1
	},
	{
	  "value" : "Storm",
	  "$uniqueCount" : 1
	}
      ]
    },
    {
      "SOLD" :
      [
	{
	  "value" : "true",
	  "$uniqueCount" : 2
	},
	{
	  "value" : "false",
	  "$uniqueCount" : 1
	}
      ]
    },
    {
      "PRICE" :
      [
	{
	  "value" : 1000,
	  "$uniqueCount" : 2
	},
	{
	  "value" : 3000,
	  "$uniqueCount" : 2
	},
	{
	  "value" : 2000,
	  "$uniqueCount" : 1
	}
      ]
    },
    {
      "PRICE" :
      [
	{
	  "bucket" :
	  {
	    "$gte" : 1000,
	    "$lt" : 3000
	  },
	  "$sum" : 4000
	},
	{
	  "bucket" :
	  {
	    "$gte" : 3000,
	    "$lte" : 3000
	  },
	  "$sum" : 6000
	}
      ]
    },
    {
      "RATING" :
      {
	"$avg" : 4.66666666666666666667
      }
    },
    {
      "HANDLER" :
      [
	{
	  "bucket" :
	  {
	    "$gte" : "Bob",
	    "$lte" : "C"
	  },
	  "$count" : 1
	},
	{
	  "bucket" :
	  {
	    "$gt" : "C",
	    "$lte" : "Jane Doe"
	  },
	  "$count" : 3
	}
      ]
    }
  ]
}

例12-2 JSON検索索引を持つJSON形式の結果セット・インタフェースの使用

この例は、JSON検索索引を持つJSON形式の結果セット・インタフェースの使用方法を示しています。

表を作成し、値を移入します。

drop table zebra_table;
create table zebra_table(id number, details clob check(details is json));

INSERT INTO zebra_table
VALUES (1,'{ "zebra" : { "price" : [2000,1000],
                       "name" : "Storm",   
                       "stripes" : ["Dark","Light"],  
                       "handler" : "Bob", "sold" : true }}');

INSERT INTO zebra_table
VALUES (2,'{ "zebra" : { "rating": 5, "price" : 1000,
                       "name" : "Zigzag",   
                       "stripes" : ["Light","Grey"],  
                       "handler" : "Jane Doe", "sold" : "true" }}');

INSERT INTO zebra_table
VALUES (3,'{ "zebra" : { "rating": 4.5, "price" : 3000,
                       "name" : "Zigs",   
                       "stripes" : ["Grey","Dark"],  
                       "handler" : "Jane Doe", "sold" : false }}');

INSERT INTO zebra_table
VALUES (4,'{ "zebra" : { "rating": "4.5", "price" : "3000",
                       "name" : "Zigs",
                       "stripes" : ["Grey","Dark"],
                       "handler" : "Jane Doe", "sold" : null }}');

detailsにJSON検索索引を作成し、parameters句を使用してプリファレンスを指定します。 

create search index zebra_idx on zebra_table(details) for json
parameters('search_on text_value_string');
JSONのresult_set_descriptorを指定したCTX_QUERY.RESULT_SETのコールは、JSON形式で次の情報を生成します。

  • 特定の条件を満たす名前を持つシマウマの合計数

  • 特定の条件を満たす名前を持つ最初の2つのヒットのROWID

  • 一意のシマウマ名の合計数

  • 売れたシマウマと売れ残ったシマウマの合計数

  • 価格に応じたシマウマの合計数

  • 価格と平均評価の合計に基づく、合計ヒット数および一意数の価格範囲内の価格と平均評価の合計

  • 特定の範囲内のハンドラ名でグループ化されたシマウマの合計数

variable rs_output clob;

declare
  rs_descriptor clob;
begin
  rs_descriptor := '
{
  "$query" : { "zebra.*.name" : { "$contains" : "sto% or zig%" } },
  "$search" : { "start" : 1,  "end" : 2 },
  "$facet" : [ 
                   { "$uniqueCount" : "zebra.name" },
                   { "$uniqueCount" : "zebra.sold" },
                   { "$uniqueCount" : 
                       { "path" : "zebra.price", "type" : "number" }
                   },
                   { "$sum" : { "path" : "zebra.price", 
                                "bucket" : 
                                  [ { "$lt" : 3000 }, { "$gte" : 3000 } ] 
                              } 
                   },
                   { "$avg" : "zebra.rating" },
                   { 
                     "$count" : { "path" : "zebra.handler", 
                                  "type" : "string",  
                                  "bucket" : 
                                    [ { "$lte" : "C" }, { "$gt" : "C" } ]  
                                } 
                   }
             ]
}
';
  dbms_lob.createtemporary( :rs_output, true );
  ctx_query.result_set( 'zebra_idx', null, rs_descriptor, :rs_output, 
                        format => CTX_QUERY.JSON_FORMAT );
end;
/

select json_query(:rs_output, '$' pretty) from dual;

出力は次のようになります。

{
  "$count" : 4,
  "$hit" :
  [
    {
      "score" : 4,
      "rowid" : "AAASwtAABAAAY95AAB"
    },
    {
      "score" : 4,
      "rowid" : "AAASwtAABAAAY95AAC"

    }
  ],
  "$facet" :
  [
    {
      "zebra.name" :
      [
	{
	  "value" : "Zigs",
	  "$uniqueCount" : 2
	},

	{
	  "value" : "Zigzag",
	  "$uniqueCount" : 1
	},
	{
	  "value" : "Storm",
	  "$uniqueCount" : 1
	}
      ]
    },
    {

      "zebra.sold" :
      [
	{
	  "value" : "true",
	  "$uniqueCount" : 2
	},
	{
	  "value" : "null",
	  "$uniqueCount" : 1
	},
	{
	  "value" : "false",
	  "$uniqueCount" : 1
	}
      ]
    },
    {
      "zebra.price" :
      [
	{
	  "value" : 1000,
	  "$uniqueCount" : 2

	},
	{
	  "value" : 3000,
	  "$uniqueCount" : 2
	},
	{
	  "value" : 2000,
	  "$uniqueCount" : 1
	}
      ]
    },

    {
      "zebra.price" :
      [
	{
	  "bucket" :
	  {
	    "$gte" : 1000,
	    "$lt" : 3000
	  },
	  "$sum" : 4000
	},

	{
	  "bucket" :
	  {
	    "$gte" : 3000,
	    "$lte" : 3000
	  },
	  "$sum" : 6000
	}
      ]
    },
    {
      "zebra.rating" :
      {
	"$avg" : 4.66666666666666666667
      }
    },
    {
      "zebra.handler" :
      [
	{
	  "bucket" :
	  {

	    "$gte" : "Bob",
	    "$lte" : "C"
	  },
	  "$count" : 1
	},
	{
	  "bucket" :
	  {
	    "$gt" : "C",
	    "$lte" : "Jane Doe"
	  },
	  "$count" : 3
	}
      ]
    }
  ]
}

制約と制限事項

RESULT_SETには、次の制約と制限事項が適用されます。

  • 結果セット・インタフェース(RSI)は仮想プライベート・データベースではサポートされません。(VPDは通常のCONTAINS問合せでサポートされますがRSIではサポートされません。)

  • ファンクションを実行するには、元表を問い合せることができる必要があります。

  • 元表でVPDポリシーが有効な場合、結果セットのドキュメント位置に資格のないドキュメントは表示されません。

  • VPDポリシーを使用している場合、カウントなどの集計メソッドが正確でないことがあります。

関連項目:

12.7 RESULT_SET_CLOB_QUERY

このプロシージャは、XMLまたはJSON問合せを実行して、XMLまたはJSONにCLOB問合せパラメータに基づいた結果セットを生成します。

構文

RESULT_SET_CLOB_QUERYプロシージャは、RESULT_SETプロシージャと同一です。ただし、長い問い合わせを処理する場合、問合せパラメータのデータ型は、VARCHAR2ではなくCLOBです。 

CTX_QUERY.RESULT_SET_CLOB_QUERY (
   index_name            IN VARCHAR2,
   query                 IN CLOB,
   result_set_descriptor IN CLOB,
   result_set            IN OUT CLOB,
   part_name             IN VARCHAR2 DEFAULT 
);

関連項目:

これらのパラメータの詳細は、RESULT_SETを参照してください

12.8 RESULT_SET_DOCUMENT

CONTAINS問合せのカーソルを明示的にクローズした後で、問合せテンプレートに<ctx_result_set_descriptor>要素がある場合に、RESULT_SET_DOCUMENTは結果セット・ドキュメントを保持します。

構文

CTX_QUERY.RESULT_SET_DOCUMENT(
   index_name            IN VARCHAR2,
   query                 IN VARCHAR2,
   result_set_descriptor IN CLOB,
   result_set            IN OUT NOCOPY CLOB,
   part_name             IN VARCHAR2 DEFAULT NULL
);
index_name

問合せを実行する索引を指定します。

query

問合せ文字列を指定します。

result_set_descriptor

XMLまたはJSONの結果セット記述子を指定します。結果セットに含む内容を示します。

result_set

出力結果セットを指定します。この変数にNULLを入力すると、セッション中に一時LOBが割り当てられてユーザーに戻ります。ユーザーは、この一時LOBの割当て解除の責任があります。

part_name

索引パーティション名を指定します。グローバル索引の場合、part_nameをNULLにする必要があります。パーティション索引でpart_nameがNULLではない場合、指定されたパーティションにのみ、問合せが評価されます。パーティション索引でpart_nameがNULLの場合、すべてのパーティションで問合せが評価されます。

関連項目

「RESULT_SET」

12.9 STORE_SQE

このプロシージャは、ストアド・クエリーまたはセッション期間問合せの式(SQE)を作成します。問合せ定義のみが格納されます。

SQEは、結果を格納せずに問合せの定義を格納するときに使用します。CONTAINSのSQL演算子によって、その問合せの定義を参照します。このように、SQEを使用すると、長い問合せ式や使用頻度の高い問合せ式を簡単に定義できます。セッション期間SQEを作成すると、不要または使用しないSQEを削除するメンテナンス・オーバーヘッドを回避する場合に便利です。

サポートされる演算子

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

権限

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

構文

構文1

CTX_QUERY.STORE_SQE(
           query_name      IN VARCHAR2,
           text_query      IN VARCHAR2, 
           duration        IN NUMBER default CTX_QUERY.DURATION_PERSISTENT
);

構文2

CTX_QUERY.STORE_SQE_CLOB_SYNTAX(
           query_name      IN VARCHAR2, 
           text_query      IN CLOB,      
           duration        IN NUMBER default CTX_QUERY.DURATION_PERSISTENT
);
query_name

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

text_query

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

duration

可能な値はDURATION_SESSIONとDURATION_PERSISTENTです。

  • durationをDURATION_SESSIONに設定すると、ストアド・クエリー式はPL/SQLパッケージ変数に格納され、セッションに使用できます。

  • durationがDURATION_PERSISTENTに設定されると、ストアド・クエリー式はデータベース表に格納され、他のデータベース・セッションで参照できます。

  • シャードされたデータベースのカタログから発行された場合、DURATION_SESSIONオプションを指定したSQEはサポートされません。かわりにDURATION_PERSISTENTオプションを使用してください。

  • query_nameネームスペースは、永続SQEとセッション期間SQEの間で共有されます。他の永続SQEまたはセッション期間SQEによってすでに使用されている名前で永続SQEまたはセッション期間SQEを追加しようとすると、エラーが発生します。

duration_persistent

CLOB問合せがある場合は、期間をデータベース表に格納するように指定します。このSQEは、不要になった時点で削除されます。

  • query_nameネームスペースは、永続SQEとセッション期間SQEの間で共有されます。他の永続SQEまたはセッション期間SQEによってすでに使用されている名前で永続SQEまたはセッション期間SQEを追加しようとすると、エラーが発生します。

例

begin
  ctx_query.store_sqe('dis1', 'flood', CTX_QUERY.DURATION_SESSION);
  ctx_query.store_sqe('dis2', 'tornado', CTX_QUERY.DURATION_PERSISTENT);
  ctx_query.store_sqe('dis3', 'fire')
end;
/

制限事項

SQEは、Oracle Databaseリリース23cより前のロジカル・スタンバイではサポートされていません。