query-search

構文

query-results nodeset query-search(query, query-object, 
query-condition-object, query-condition-xpath, query-modification-macros, 
sources, start, syntax-operators, syntax-repository-node, 
syntax-field-mappings, sort-by, sort-xpaths, sort-score-xpath, 
sort-num-passages, rank-decay, num, num-over-request, 
num-per-source, num-max, browse, browse-num, browse-start, 
browse-clusters-num, term-expand-max-expansions, term-expand-error-when-exceeds-limit, 
spelling-enabled, spelling-configuration, dict-expand-dictionary, 
dict-expand-max-expansions, dict-expand-stem-enabled, dict-expand-stem-stemmers, 
dict-expand-wildcard-enabled, dict-expand-wildcard-min-length, dict-expand-wildcard-segmenter, 
dict-expand-wildcard-delanguage, dict-expand-regex-enabled, arena, 
output-contents-mode, output-contents, output-summary, output-score, 
output-shingles, output-duplicates, output-key, output-cache-references, 
output-cache-data, output-sort-keys, output-axl, output-bold-contents, 
output-bold-contents-except, output-bold-class-root, output-query-node, 
output-display-mode, authorization-rights, authorization-username, 
authorization-password, collapse-xpath, collapse-num, collapse-binning, 
collapse-sort-xpaths, binning-state, binning-mode, binning-configuration, 
force-binning, fetch, fetch-timeout, aggregate, 
aggregate-max-passes, cluster, cluster-near-duplicates, cluster-kbs, 
cluster-stemmers, cluster-segmenter, efficient-paging, 
efficient-paging-n-top-docs-to-cluster, debug, profile, extra-xml);
string query;
operator nodeset query-object;
operator nodeset query-condition-object;
string query-condition-xpath;
string query-modification-macros;
string sources;
int start;
string syntax-operators;
string syntax-repository-node;
field-map nodeset syntax-field-mappings;
string sort-by;
sort nodeset sort-xpaths;
string sort-score-xpath;
int sort-num-passages;
double rank-decay;
int num;
double num-over-request;
int num-per-source;
int num-max;
boolean browse;
int browse-num;
int browse-start;
int browse-clusters-num;
int term-expand-max-expansions;
boolean term-expand-error-when-exceeds-limit;
boolean spelling-enabled;
spelling-correction nodeset spelling-configuration;
string dict-expand-dictionary;
int dict-expand-max-expansions;
boolean dict-expand-stem-enabled;
string dict-expand-stem-stemmers;
boolean dict-expand-wildcard-enabled;
int dict-expand-wildcard-min-length;
string dict-expand-wildcard-segmenter;
boolean dict-expand-wildcard-delanguage;
boolean dict-expand-regex-enabled;
string arena;
enum output-contents-mode;
string output-contents;
boolean output-summary;
boolean output-score;
boolean output-shingles;
boolean output-duplicates;
boolean output-key;
boolean output-cache-references;
boolean output-cache-data;
boolean output-sort-keys;
nodeset output-axl;
string output-bold-contents;
boolean output-bold-contents-except;
string output-bold-class-root;
boolean output-query-node;
enum output-display-mode;
string authorization-rights;
string authorization-username;
string authorization-password;
string collapse-xpath;
int collapse-num;
boolean collapse-binning;
sort nodeset collapse-sort-xpaths;
string binning-state;
enum binning-mode;
binning-setnodeset binning-configuration;
boolean force-binning;
boolean fetch;
int fetch-timeout;
boolean aggregate;
int aggregate-max-passes;
boolean cluster;
double cluster-near-duplicates;
string cluster-kbs;
string cluster-stemmers;
string cluster-segmenter;
boolean efficient-paging;
int efficient-paging-n-top-docs-to-cluster;
boolean debug;
boolean profile;
nodeset extra-xml;

パラメーター

• string query - syntax-operators を使用して解析される照会ストリング。これは、ユーザーが生成した照会を渡す際に有用です。
• operator nodeset query-object - 照会オブジェクト (構文に従って照会ストリングを解析することで得られるオブジェクトに似ています)。この照会オブジェクトは、プログラムで生成された照会を渡す際に有用です (一義的に操作する方がはるかに容易であるため)。照会ストリングと照会オブジェクトの両方が指定される場合は、「AND」演算子で結合されます。(例えば、ユーザーが生成した照会をプログラムの条件と結合するために) 両方を指定しても問題ありません。
• operator nodeset query-condition-object - query と query-object の両方に加えられる条件として解釈され、かつ結果をランク付けするのではなく制限するためにのみ使用される照会オブジェクト (構文に従って照会ストリングを解析することで得られるオブジェクトに似ています)。
• string query-condition-xpath - 他の照会パラメーターと結合される結果のセットを制限するために使用される (ランク付けには使用されない) XPath。
• string query-modification-macros - 元の照会を変更するために使用されるマクロのスペース区切りリスト。
• string sources - 照会されるソースをスペースで区切ったリスト。指定しない場合は、ソースは照会されません (照会がどのように解析されて拡張されるかを、実際に照会を実行することなく確認する場合に便利です)。
• int start - 各ソース/コレクションによって返される最初の文書のランク (0 から始まります)。この指定は、コレクションが 1 つだけの場合に意味があります。複数のソースをフェデレートしている場合は、browse-start を使用してください。検索コレクションのみをフェデレートしている場合は、最初の要求で取得される内容に基づいてコレクションごとに start を (フィールドとして) 渡すことで、「次の」結果セットを取得する方が効率的です。デフォルト値: 0
• string syntax-operators - 演算子名のスペース区切りリスト。これらの演算子は、ここで参照される構文リポジトリー・ノードで定義される必要があります。照会検索は、ソースを選択せずに実行依頼する照会の解析にのみ使用できます。デフォルト値: AND and () CONTAINING CONTENT %field%: + NEAR - NOT NOTCONTAINING NOTWITHIN OR0 quotes regex stem THRU BEFORE FOLLOWEDBY weight wildcard wildchar WITHIN WORDS site less-than less-than-or-equal greater-than greater-than-or-equal equal range。
• string syntax-repository-node - リポジトリーからロードされる構文ノードの名前 (構文演算子の定義を含みます)。デフォルト値: custom。
• field-map nodeset syntax-field-mappings - フィールド・マッピングのセット。
• string sort-by - ソートに使用されるソート・フィールド (v.sort-by) の値をスペースで区切ったリスト (これらの値は、各ターゲット・ソースでソート式にマップされている必要があります)。
• sort nodeset sort-xpaths - ソート XPath およびソート順を指定するソート・ノードのセット。sort-score-xpath および sort-by も参照してください。sort-by が指定される場合は組み合わせとして使用され、sort-by は 1 次ソート・キーを指定します。
• string sort-score-xpath - 結果ごとに出力されるスコア (output-score を参照)。 その他のソートが指定されない場合、これがデフォルトのソート式です。変数 $score、$la-score、および高速索引付けの対象として定義したコンテンツ名 (コレクションの索引付け構成で定義して、索引状況で報告されます) を使用するカスタム XPath 式を指定できます。スコアは常に数値であるため、式の評価結果は必要に応じて数値にキャストされます。sort-score-xpath とソート条件の両方が指定される場合、ソート条件が優先されます。この XPath は検索結果ごとに (場合によっては数百万回) 評価されるので注意してください。(すべてではありませんが) 一部の XPath 演算子と関数は、重い XPath 構造の操作を回避するように最適化されています。大規模なコレクションでは、式をこれらの演算子に制限することをお勧めします (不適切な応答時間を避けるため)。最適化されている XPath 演算子と関数の最新リストについては、資料を確認してください。
• int sort-num-passages - 自然的関連性を計算する際に考慮される一致節の数 (つまり $score)。ソートに $score を使用しない場合にパフォーマンスを向上させるには、0 に設定します。指定しない場合は、コレクション・レベルで設定された値が使用されます。
• double rank-decay - ランキング時に、i 番目に最適な節のスコアは、この値の i 乗になります。すべての節を等しい値として扱うには、1 に設定します。
• int num - 指定すると、Watson™ Explorer は各ソースから取得された結果の数をこの総数に合わせようとします。集計モードでは、追加の結果を得るために特定のソースまで戻ることがあります。デフォルト値: 10
• double num-over-request - 複数のソースが同時に照会されて重複が削除される場合、結果の総数は予期したよりも少なくなる可能性があります。このパラメーターでは、要求される結果の総数を増やして減少分を補います。これは、集計モードでソースに何回も戻らないようにするためにも有用です。デフォルト値: 1.3。
• int num-per-source - 各ソースに対して要求される結果の数。指定される場合、num よりも優先されます。
• int num-max - 各コレクションでランク付けされる上位の結果の最大数。この数値は、要求される数よりも大きくする必要があり、キャッシュの最適化という観点でのみ意味があります (ソースから追加で結果を得る場合は、要求された上位ランク数が num-max よりも小さい場合にのみ初期キャッシュを使用できます)。
• boolean browse - 有効にすると、結果は後で参照できるように一時ファイルに保存されます。これは、結果をクラスタリングするときに特に有用です。デフォルト値: false。
• int browse-num - 参照モードでは、最初にこの数の結果のみが返されます。デフォルト値: 10
• int browse-start - 取得された数の結果のうち、ランクが browse-start よりも高い結果のみを返します (0 で始まります)。デフォルト値: 0
• int browse-clusters-num - 参照モードでは、この数のクラスターのみが返されます。デフォルト値: 10
• int term-expand-max-expansions - 指定すると、検索コレクションで拡張される用語の数がこの値に制限されます。拡張は、出現頻度の最も高い用語から順にソートされます。
• boolean term-expand-error-when-exceeds-limit - 有効にすると、用語の拡張が許容された数を超えている場合に、検索コレクションから結果が返されず、エラーが返されます。
• boolean spelling-enabled - 有効にすると、スペルが訂正されたバージョンの照会ノードが結果とともに返されます。デフォルト値: false。
• spelling-correction nodeset spelling-configuration - スペル訂正機能の構成オプション。デフォルト以外のフィールドのスペルを訂正する必要があるか、別の辞書を使用する場合に使用します。
• string dict-expand-dictionary - 辞書に基づく拡張を実行するために使用する辞書の名前。
• int dict-expand-max-expansions - 各用語を拡張できる拡張の最大数。
• boolean dict-expand-stem-enabled - 有効にすると、stem 演算子を使用する用語が、同じステムを持つすべての用語で置き換えられます。
• string dict-expand-stem-stemmers - ステムの拡張を実行すると、このステマーを使用して関連するワードが検索されます。
• boolean dict-expand-wildcard-enabled - 有効にすると、ワイルドカードまたは wildchar 演算子を使用する用語が、ワイルドカード式と一致するすべての用語で置き換えられます。
• int dict-expand-wildcard-min-length - ワイルドカードの拡張を実行する際、用語に少なくともこの数の非ワイルドカード文字が含まれている必要があります。
• string dict-expand-wildcard-segmenter - ワイルドカードの拡張を実行する際、一致を検索する前に、このセグメンターを使用して用語がセグメント化されます。
• boolean dict-expand-wildcard-delanguage - ワイルドカードの拡張を実行する際、一致を検索する前に用語から不要語が削除されます。
• boolean dict-expand-regex-enabled - 有効にすると、regex 演算子を使用する用語が、正規表現と一致するすべての用語で置き換えられます。
• string arena - 検索コレクション内で照会する分野を指定します。
• enum output-contents-mode - output-contents パラメーターがどのように解釈されるかを指定します。 defaults: パラメーターは無視され、各コレクションのデフォルトが使用されます。list: 名前がリストされているコンテンツを出力します (コンテンツを出力しないようにするには、output-contents でこのオプションに空の値を指定して使用します)。except: 名前がリストされていないコンテンツを出力します (すべてのコンテンツを出力するには、output-contents でこのオプションに空の値を指定して使用します。一般的には、文書のテキスト全体が出力されるのを回避するために、常にスニペットを除外します)。デフォルト値: defaults。指定可能な値: defaults|list|except。
• string output-contents - output-contents-mode の値に基づいて、出力されるか出力されないコンテンツの名前のスペース区切りリスト。
• boolean output-summary - 有効にすると、各結果の要約が生成されます (コレクション構成で選択されているコンテンツに基づきます)。要約は通常、ユーザー・エクスペリエンスとクラスタリングを向上させますが、入出力のコストが高くなる可能性があります (そのため、多数の結果を取得する場合はオフにすることをお勧めします)。
• boolean output-score - フェデレーション層で設定されたスコアではなく、各結果に対して検索エンジンが計算したスコアを出力します。複数のコレクションを集計する場合、これをオンにしてください。指定しない場合は、各ソースのデフォルトが使用されます。
• boolean output-shingles - ドキュメント・ハッシュを出力して、さまざまなコレクションからの検索結果を集計し、コレクションのドキュメント・ハッシュの重複を削除できるようにします (aggregate パラメーターを参照してください)。単一のコレクションを照会するときにはオフにしてください。指定しない場合は、各ソースのデフォルトが使用されます。
• boolean output-duplicates - false の場合は、ドキュメント・ハッシュに基づいて各検索コレクションから重複が除去されます。
• boolean output-key - コレクションにまたがって重複を除去するためにフェデレーション・レベルで使用されるキー (正規化された vse-key に基づく) を出力します (単一のコレクションを照会する際は、常にオフにする必要があります)。指定しない場合は、各ソースのデフォルトが使用されます。
• boolean output-cache-references - 結果文書ごとにキャッシュ参照を出力して、対応するキャッシュ・データを参照できるようにします。指定しない場合は、各ソースのデフォルトが使用されます。
• boolean output-cache-data - 結果ごとにキャッシュ・データを出力します。大量のデータが生成される場合があり、通常は一度に単一の文書に対して使用されます。
• boolean output-sort-keys - ソート式が使用される場合、それらの値を出力して、複数のコレクションの相互ソートを実行できます。一度に 1 つのコレクションのみを照会する場合はオフにして、複数のコレクションを集約する場合はオンにしてください。指定しない場合は、各ソースのデフォルトが使用されます。
• nodeset output-axl - 検索コレクションの出力を指定するために使用される AXL コード。
• string output-bold-contents - 照会語を太字にする (あるいは、output-bold-contents-except の値に基づいて太字にしない) コンテンツ名のスペース区切りリスト。
• boolean output-bold-contents-except - true に設定する場合、コンテンツのリストは、太字にしないコンテンツの除外リストとして見なされます。デフォルト値: false。
• string output-bold-class-root - 指定されない場合、太字化に標準の <b> タグが使用されます。指定される場合、各キーワードに対応する数値と連結されたこのルートを使用して、<span> タグがクラス名と共に使用されます。
• boolean output-query-node - 検索の実行に使用された照会ノードを返します。これは、パラメーターとして指定された照会ノードとは異なる場合があります。デフォルト値: true。
• enum output-display-mode - 「limited」モードを使用する場合、「normal」モードで返される XML データのサブセットが返されます。このサブセットは、API を使用して大容量のデータ・セットを返すアプリケーション向けに最適化されています。デフォルト値: default。指定可能な値: default|limited。
• string authorization-rights - セキュリティー・グループの改行区切りリスト (ターゲット・コレクションは同じグループを使用する ACL を持っていることが予期されます)。
• string authorization-username - 実行時バインディング・セキュリティーに使用するユーザー名。
• string authorization-password - 実行時バインディング・セキュリティーに使用するパスワード。
• string collapse-xpath - この XPath 式は照会を満たす文書ごとに評価され、同じキー値を共有する文書は単一の検索結果に縮小されます。
• int collapse-num - 縮小する場合、これはキーごとに出力する 2 次文書の最大数です。0 を指定すると、各キーで最もスコアの高い文書のみが出力されます。
• boolean collapse-binning - デフォルトで、ビンは各文書に適用されます。このオプションを選択すると、縮小された各セットで最もスコアの高い文書のみにビンが実行されます。このモードでは、要求された数よりも少ない文書が返される可能性があります。
• sort nodeset collapse-sort-xpaths - この XPath 式は照会を満たす文書ごとに評価され、同じキー値を共有する文書は単一の検索結果に縮小されます。
• string binning-state - ビンと対話するときに渡されるストリング・トークン。
• enum binning-mode - off: ビン・モードを無効にします。normal: すべてのビンの現行状態を計算します。double: normal と同じ情報を計算しますが、ビンの制限なしの完全な状態でのビンも計算します。デフォルト値: defaults。指定可能な値: defaults|off|normal|double。
• binning-set nodeset binning-configuration - コレクションからのビン構成を拡張するために使用する追加の構成。これは通常、ユーザーに基づく追加の処理が要求される場合にのみ渡されます。
• boolean force-binning - 通常、start パラメーターがゼロではない場合、ビン・データは出力されません。これは、集計にコレクションを使用するときに誤った結果が出力されないようにするためです。集計が使用されない場合は、このオプションにより、ビン・データの出力を強制できます。デフォルト値: false。
• boolean fetch - true の場合は、リモート要求がフェッチされます。要求を実行せずに完全に拡張されたソース参照のセットを表示する必要がある場合 (高度なフォームを作成する場合に有用です) を除き、常にオンにしてください。デフォルト値: true。
• int fetch-timeout - 要求が中止されるまでのタイムアウト。デフォルト値: 60000。
• boolean aggregate - オンにすると、照会されるすべてのソースが単一のソースのように動作します。単一のコレクションのように動作するよう設定された検索コレクションのセットを照会する場合、オンにしてください。オンにする場合、output-score、output-shingles、output-key、および output-sort-keys をオンにしてください。デフォルト値: false。
• int aggregate-max-passes - 集計モードでは、適切な数の結果を取得するために特定のソースに何回も戻ることができます (複数のソースを 1 つのソースとして照会する場合、Watson Explorer は、結果を表示するまで、どのソースのスコア結果が低い/高いのかを認識できず、すべてのソースで本当に上位の結果をフェッチするために複数回ソースに戻る必要が生じることがあります)。デフォルト値: 3。
• boolean cluster - 検索結果のクラスタリングを実行できるようにします。重みが 0 より大きいコンテンツおよびデフォルト・アクションまたは「クラスター」アクションのみが考慮されます。デフォルト値: false。
• double cluster-near-duplicates - x (異なる内容のパーセンテージとして考えてください) よりも相互に類似している文書は重複と見なされます。(複数のソースの) 出力には、重複した文書の 1 つのインスタンスのみが表示されます。このオプションを 1 に設定すると、すべての文書が相互に重複することになります。0 に設定すると、まったく同じ索引が付けられたテキストを含む文書のみが重複とマークされます。-1 に設定すると、近似重複の検出が完全に無効になります。デフォルト値: -1。
• string cluster-kbs - クラスタリングおよび類似重複排除に使用する知識ベースのスペース区切りリスト (事前定義またはユーザー定義)。複数の知識ベースに同じ単語がある場合、最後にリストされている知識ベースが使用されます。例えば、「english german」の場合、両方の知識ベースに「die」が含まれていても、最後にリストされている German 知識ベース内の項目が優先されます。 現在事前定義されている知識ベースのリストについては、主要資料を参照してください。デフォルト値: core web english custom。
• string cluster-stemmers - クラスタリングおよび類似重複排除に使用するステマーのスペース区切りリスト。複数のステマーを結合できます。例: 「dutch french」はオランダ語のステマーに適用され、そのステマーによって単語がステミングされない場合にはフランス語のステマーに適用されます。現在サポートされているステマーのリストについては、主要資料を参照してください。デフォルト値: delanguage english depluralize。
• string cluster-segmenter - クラスタリングおよび類似重複排除に使用するセグメンターを指定します。セグメンターは、セグメント化されていない言語 (日本語や中国語など) の連続した言葉を個々の構成要素 (語) に分割します。 現在サポートされているセグメンターのリストについては、主要資料を参照してください。デフォルト値: none。
• boolean efficient-paging - さらに効率的にソースから文書を取得して、より多くの数の文書が返されるようにします。この機能は、その他の特定の Watson Explorer 機能と互換性がありません。デフォルト値: false。
• int efficient-paging-n-top-docs-to-cluster - 効率的なページングを有効にすると、すべての文書が事前に取得されなくなり、クラスタリングに利用できなくなります。このオプションでは、クラスタリング用に取得する上位ランクの文書の数を制御します。デフォルト値: 200。
• boolean debug - true の場合はデバッグ・ログが作成され、管理ツールを使用して参照できます (「Management」>「Debugging Sessions」)。このオプションは、パフォーマンスに影響を与えるため、実動では決してオンのままにしておかないでください。デフォルト値: false。
• boolean profile - true の場合、Watson Explorer は、プロファイルのデバッグ・ログを使用できるように軽量のデバッグを実行します。このオプションが機能するためには、デバッグをオンにしておく必要があることに注意してください。デフォルト値: false。
• nodeset extra-xml - 照会が実行依頼される前に処理される追加の AXL コード。さらに高度なオプションまたはカスタムの変数を追加するために使用できます。

戻り値

• query-results nodeset

例外

• この関数に固有の例外はありません。

認証

ping を除くすべての Watson Explorer Engine API 関数と同様に、query-search 関数には認証が必要です。

REST を使用する場合、HTTP または HTTPS を介して単に v.username および v.password を CGI パラメーターとして渡し、query-search 関数への REST 呼び出しを認証することができます。

SOAP API を使用する場合、エンドポイントで資格情報をパラメーターとして渡すか、すべての Watson Explorer Engine 関数でサポートされている認証方式を活用することができます。いずれも、関数の実行に使用されるユーザー名とパスワードを指定するために認証オブジェクトに渡すことができる setAuthentication メソッドを提供します。query-search 関数への SOAP 呼び出しを Java で実行する例は次のとおりです。

    Authentication authentication = new Authentication();
    authentication.setUsername("joe-user");
    authentication.setPassword("joes-password");

    QuerySearch foo = new QuerySearch();
    foo.setAuthentication(authentication);

通常、個々のアプリケーション全体で 1 つの認証オブジェクトが再使用されます。