Search processing - OpenSearch - Alibaba Cloud ドキュメントセンター

豊富な検索構文により、さまざまなクエリをサポートします。

URL

/v3/openapi/apps/$app_name/search?fetch_fields=name&query=config=format:fulljson&&query=name:'testuser'&&sort=id

$app_name：アプリケーション名です。Advanced Edition および Standard Edition は複数のアプリケーションをサポートしているため、特定のバージョンを対象とするにはアプリケーション名を指定する必要があります。たとえば、アプリケーション ID を使用して、オフラインアプリケーションの検索サービスにアクセスできます。
上記の URL には、リクエストヘッダーやエンコーディングなどの詳細は含まれていません。
上記の URL ではホストアドレスが省略されています。
上記の URL に含まれるクエリパラメーターの定義、使用方法、および例については、以下の「クエリパラメーター」セクションをご参照ください。

リクエストプロトコル

HTTP

リクエストメソッド

GET

サポートされるフォーマット

JSON

クエリパラメーター

クエリパラメーターの連結方法の詳細については、「V3 API 署名メカニズム」をご参照ください。

パラメーター	タイプ	必須	デフォルト	説明
query	string	はい		検索クエリ。このパラメーターは空にできません。Industry Algorithm Edition は空の検索をサポートしており、`query` 句で検索語を指定せずに検索できます。これを行うには、空の文字列`''`を検索語として渡します。空の検索シナリオでは、2112 エラーは表示上の問題であり、完全な結果セットには影響しません。クエリ文字列は、`config` 句、`query` 句、`sort` 句、`filter` 句、`aggregate` 句、`distinct` 句、`kvpairs` 句などの句で構成されます。
fetch_fields	string	いいえ	すべての表示可能なフィールド。	検索結果で返すフィールドを指定します。複数のフィールドはセミコロン`;`で区切ります。このパラメーターは、コンソールのデフォルト表示フィールド機能に対応します。
qp	string	いいえ	アクティブなルール	使用するクエリ分析ルールを指定します。複数のルールはカンマ`,`で区切ります。
disable	string	いいえ		指定されたパラメーターを無効にします。
first_rank_name	string	いいえ	デフォルトの基本ソート式名	基本ソート式の名前を指定します。名前は 1 つだけ指定できます。
second_rank_name	string	いいえ	デフォルトのサービスソート式名	サービスソート式の名前を指定します。名前は 1 つだけ指定できます。
user_id	string	いいえ		エンドユーザーの一意の識別子。このパラメーターには、優先度の高い順に次のいずれかを設定します：1. エンドユーザーの永続的なログイン ID。2. エンドユーザーのモバイルデバイスの IMEI。
abtest	string	いいえ		このパラメーターは、A/B テスト機能を使用するために必須です。
raw_query	string	いいえ		カテゴリ予測などのアルゴリズムトレーニングに使用されます。すべてのクエリでこのパラメーターを設定することを推奨します。
search_strategy	string	いいえ		マルチパス検索のクエリ戦略名を指定します。
re_search	string	いいえ		リトライポリシーを指定します。現在、ポリシーは合計ヒット数のしきい値にのみ基づくことができます。
biz	string	いいえ		リクエストの発生元や目的など、リクエストのビジネスコンテキストを記述します。
summary	string	いいえ	デフォルトのサマリー構成	検索結果のサマリーを設定します。ハイライトや切り捨てなどの操作のためにフィールドを指定できます。
from_request_id	string	いいえ		検索リクエストのソースを指定します。クエリが検索サジェスト、人気のあるクエリ、クエリサジェストなどの機能から発生した場合、このパラメーターを元の推奨リクエストの `request_id` に設定します。このリファラルイベントをリンクすることで、メトリックの計算、効果の測定、およびこれらの上流機能の最適化のためのデータ収集が可能になります。詳細については、「検索サジェスト」ドキュメントをご参照ください。
vector_search	string	いいえ
`query` 句	string	はい		検索条件を指定します。
`config` 句	string	いいえ		応答フォーマットと返すドキュメントの数を指定します。
`filter` 句	string	いいえ		フィルタリング条件を指定します。
`sort` 句	string	いいえ		ドキュメントのソート条件を指定します。整数フィールドのみがサポートされています。この句は V3 API および SDK でのみ利用可能です。

クエリパラメーター

query： 複数の句を組み合わせて、さまざまな検索要件を満たすことができます。クエリパラメーター内の句は && で連結されます。Industry Algorithm Edition は空の検索をサポートしています。query 句で検索語として空の文字列 '' を渡すと、システムは完全な結果を返します。空の検索中に 2112 エラーが発生することがありますが、これは表示上の問題であり、実際の検索結果には影響しません。
fetch_fields： クエリのパフォーマンスに影響を与えないように、必要なフィールドのみを取得してください。SDK/API でこのパラメーターを設定すると、コンソールの対応する設定がオーバーライドされます。
qp： SDK/API でこのパラメーターを設定すると、コンソールの対応する設定がオーバーライドされます。

注：コンソールの検索テストページには、qp の効果とその結果が表示されます。この情報は現在、API または SDK を通じては利用できません。

disable： クエリ中に指定された機能を無効にします。クエリ分析 (qp)、ハイライト (summary)、粗から密へのランキング (first_rank、second_rank)、再検索 (re_search) などの機能を無効にできます。

説明
- クエリ中に無効にする機能を指定します。
- 現在、クエリ分析、ハイライト、粗から密へのランキング、再検索の無効化をサポートしています。
フォーマット：
```
disable=function[;function]
function=function_name[:function_param]
```
- 例：
  - クエリ分析を無効にするには、disable=qp と設定します。
  - クエリ分析内の spell_check 機能を無効にするには、disable=qp:spell_check と設定します。フォーマットは disable=qp:$qp_processor_name です。詳細については、「QueryProcessor」をご参照ください。
  - 再検索を無効にするには、disable=re_search と設定します。
first_rank_name： SDK または API 呼び出しで設定すると、このパラメーターはコンソールの対応する設定をオーバーライドします。
second_rank_name： SDK または API 呼び出しで設定すると、このパラメーターはコンソールの対応する設定をオーバーライドします。
user_id：
- user_id の値は、検索リクエストで URL エンコードする必要があります。
- データ統計機能は、このパラメーターを使用してユニークビジター (UV) を計算します。
- データ収集を統合している場合は、行動データの報告に使用される user_id が検索リクエストの user_id と一致することを確認してください。
abtest： abtest=urlencode(scene_tag:urlencode(\$scene),flow_divider:urlencode(\$value))。ここで、urlencode は URL エンコーディング関数です。
- flow_divider にはエンドユーザーの ID を設定します。ID が利用できない場合は、エンドユーザーのデバイス ID または IP アドレスを使用できます。このパラメーターは必須です。
- scene_tag：コンソールでシーンタグを設定しない場合、A/B テストはすべてのシーンからのトラフィックに適用され、クエリで scene_tag を設定する必要はありません。
raw_query：

説明
- このパラメーターはカテゴリ予測に使用されます。クエリ分析で設定されるカテゴリ予測は、query と raw_query パラメーターが同一の場合にのみ実行されます。
- このパラメーターは、カテゴリ予測などのアルゴリズムトレーニングにも使用されます。このため、すべてのクエリでこのパラメーターを設定してください。
- このパラメーターには、エンドユーザーが入力した元のクエリを設定します。
フォーマット：
```
raw_query=content
```
- content：元のクエリ。
re_search：

説明
- 再検索戦略を指定します。現在、total_hits のしきい値に基づく戦略のみがサポートされています。
- この機能を使用するには、クエリ分析を設定する必要があります。
- トークン化されたクエリのすべての term が同じエンティティ認識の重みを持つ場合、再検索はトリガーされません。再検索をトリガーするには、エンティティ認識でカテゴリの重みを調整する必要があります。
フォーマット：
```
re_search=strategy:threshold,params:total_hits#${COUNT}
```
- COUNT：total_hits のしきい値。合計ヒット数が COUNT 未満の場合、システムは再検索をトリガーします。
- 例：
  - re_search=url_encode(strategy:threshold,params:total_hits#6)
biz：

説明
- トラフィックソースのビジネスタイプなど、リクエストのビジネス情報を指定します。
  
  フォーマット：
```
biz=type:$TYPE
```
- type：トラフィックのタイプ。独自に定義できます。この値を使用して、レポートで異なるソースからのトラフィックを区別します。
- 例：
  - biz=type:home_page

vector_search：

パラメーター	タイプ	デフォルト	説明
namespace	list<string>		検索対象の名前空間。
threshold	float		ベクトル取得の最小スコアしきい値。
top_n	uint32		ベクトル取得から返す上位の結果の数。
search_params.qc_scan_ratio	float	0.01	`max_scan_num` を計算するために使用される比率。数式は：ドキュメントの総数 * `scan_ratio` です。
search_params.hnsw_ef	uint32	500	検索精度を指定します。値が大きいほど、スキャンされるドキュメントの数が増え、取得率が向上します。

vector_threshold：

説明
- ベクトルリコールのベクトルスコアしきい値を制御します。システムは、このしきい値よりも低いベクトルスコアを持つドキュメントのみを返します。
フォーマット
- 値は浮動小数点数である必要があります。
- このパラメーターはオプションです。省略した場合、システムは組み込みのしきい値を使用します。

Summary：
- summary_element_prefix と summary_element_postfix パラメーターは一緒に設定する必要があります。
- summary_element パラメーターは、summary_element_prefix および summary_element_postfix パラメーターと相互作用します。最後に指定されたものが優先されます。
- サマリーとハイライトは個別に設定できません。
- SDK または API を介して行われたパラメーター設定は、コンソールの対応する設定をオーバーライドします。

パラメーター	タイプ	必須	値	デフォルト	説明
summary_field	string	はい			サマリーを生成するために使用されるフィールド。
summary_element	string	いいえ		em	ハイライトタグ。山括弧なしの HTML タグ名として指定します。
summary_ellipsis	string	いいえ		…	切り捨てられたサマリーに追加する省略記号。
summary_snippets	int	いいえ		1	返すサマリースニペットの数。
summary_len	string	いいえ			各サマリースニペットのおおよその長さ。
summary_element_prefix	string	いいえ			ハイライトされた用語のプレフィックス。これは <em> のような完全な HTML タグである必要があります。
summary_element_postfix	string	いいえ			ハイライトされた用語のサフィックス。これは </em> のような完全な HTML タグである必要があります。

結果

パラメーター	タイプ	説明
status	string	実行結果。`OK` は成功を示し、`FAIL` は失敗を示します。リクエストが失敗した場合は、返されたエラーコードを使用してトラブルシューティングを行います。
request_id	string	このクエリの一意のリクエスト ID。トラブルシューティングに使用します。
result	JSON	検索結果とメタデータが含まれます。このオブジェクトには、検索時間 (`searchtime`)、見つかった合計一致数 (`total`)、返された結果の数 (`num`)、返すことができる結果の最大数 (`viewtotal`)、結果項目のリスト (`items`)、およびファセット結果 (`facet`) が含まれます。
errors	list	エラーのリスト。各エラーオブジェクトには `code` と `message` が含まれます。エラーコードの説明については、「エラーコード」ドキュメントをご参照ください。

searchtime： クエリに対するエンジンの処理時間 (秒単位)。
total、viewtotal、num の違い： total は、config 句を無視して、クエリに一致するエンジン内の結果の数です。この値は、大きな結果セットに対して最適化されています。ただし、パフォーマンスと関連性の理由から、エンジンは最大で viewtotal の結果を返します。ページネーションの場合、start+hit は viewtotal 未満である必要があります。total は通常、表示に使用されます。num は、現在のクエリリクエストに対して返される実際のアイテム数であり、config 句の start および hit パラメーターによって制約され、hit の値を超えることはありません。
compute_cost：単一のオブジェクトを含む配列。このオブジェクトでは、index_name はアプリケーション ID を表し、value はクエリによって消費された LCU を表します。
items： 取得されたドキュメントが含まれます。各ドキュメントオブジェクト内で、fields オブジェクトには取得されたコンテンツが含まれます。
variableValue： distance 値など、カスタムパラメーターの結果を表します。このノードは、config 句の format パラメーターが xml または fulljson に設定されている場合にのみ返されます。json フォーマットでは、デフォルトでこのノードは返されません。
sortExprValues： ドキュメントのソートスコアを表します。
facet： aggregate 句によって返される情報が含まれます。
配列フィールドタイプ：JSON および fulljson フォーマットでは、配列内の値はタブ文字 (\t) で区切られます。XML フォーマットでは、これらの値はスペースで区切られます。

検索例

JSON 応答

{
 "result": {
  "searchtime": 0.009554,
  "total": 1,
  "compute_cost": [
   {
    "index_name": "110247758",
    "value": 0.304
   }
  ],
  "num": 1,
  "viewtotal": 1,
  "items": [
   {
    "variableValue": {

    },
    "sortExprValues": [
     "10000"
    ],
    "property": {

    },
    "attribute": {

    },
    "fields": {
     "size": "XL",
     "discount_price": "9.9",
     "pid": "950",
     "range_age": "18\t25",
     "detail": "Men's Lapel Jacket, New 2021 Spring & Fall Style, Lightweight Casual Zip-Up Youth Outerwear",
     "index_name": "110247758"
    }
   }
  ],
  "facet": []
 },
 "ops_request_misc": "%7B%22request%5Fid%22%3A%22162642700916781929257960%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
 "tracer": "",
 "request_id": "162642700916781929257960",
 "errors": [],
 "status": "OK"
}

エラー応答

{
 "result": {
  "searchtime": 0.003999,
  "total": 0,
  "compute_cost": [
   {
    "index_name": "110247758",
    "value": 0.232
   }
  ],
  "num": 0,
  "viewtotal": 0,
  "items": [],
  "facet": []
 },
 "ops_request_misc": "%7B%22request%5Fid%22%3A%22162642716516781913069826%22%2C%22scm%22%3A%2220140713.110229359..%22%7D",
 "tracer": "",
 "request_id": "162642716516781913069826",
 "errors": [
  {
   "code": 6127,
   "message": "Attribute does not exist."
  }
 ],
 "status": "FAIL"
}

注：status が FAIL の場合は、error が発生し、result が返されなかったことを示します。ただし、status が OK で結果が返された場合でも、error が発生することがあります。たとえば、1000 サーバーエラー (検索タイムアウト) や 2112 エラー (詳細ランキングに index が指定されていない) が発生しても、結果を受け取ることがあります。

クエリ結果のトラブルシューティング

検索 API 呼び出しによって返された結果が、結果の不一致、結果なし、または予期しない結果数など、期待どおりでない場合は、次の方法でトラブルシューティングを行います：

API と検索テストページで使用されるクエリ文の比較：API 呼び出しからの結果がコンソールの検索テストページに表示される結果と異なる場合は、それぞれが実際に送信したクエリ文を比較し、query 句の違いを確認します。
データの存在確認：プライマリキー id でデータを直接クエリして、データが存在するかどうかを確認します。これにより、データ同期の遅延によって引き起こされる問題を排除できます。
形態素解析の問題のトラブルシューティング：形態素解析が予期しない結果を引き起こしている疑いがある場合は、カスタム形態素解析介入を追加して結果を最適化できます。
ベクトルクエリの精度の調整：ベクトルクエリで結果が期待どおりでない場合は、クエリ値を小数点以下 5 桁に丸めてクエリを再試行してみてください。
結果が返されない場合のトラブルシューティング手順：
1. まず、応答の total が 0 であるかどうかを確認します。total は、クエリ条件に一致するエンジン内の結果の総数を表します。この値は、結果数が多い場合に最適化されます (このドキュメントの「応答」セクションの total、viewtotal、num の違いの説明をご参照ください)。
2. total が 0 ではないが items が返されない場合は、config 句の start および hit パラメーターを確認します。

スクロール検索

速度を最適化するため、従来の検索では最も関連性の高い結果が限られた数だけ返されます。たとえば、search メソッドは最大 5,000 件のドキュメントをリコールできます。分析のためにより多くの結果が必要な場合は、scroll API を使用してより大きな結果セットを取得します。

サポートされる句

query 句
config 句 (start パラメーターは効果がありません)
filter 句
sort 句 (単一の INT 型フィールドのみをサポート。v3 API および SDK のみ)

URL

初期クエリ

/v3/openapi/apps/$app_name/search?search_type=scan&scroll=1m&[query parameters]

後続クエリ

/v3/openapi/apps/$app_name/search?scroll_id=$scroll_id&scroll=1m&[query-parameters]

$app_name： アプリケーション名。
上記の URL では、アプリケーションのホストアドレスが省略されています。
上記の 2 つのスクロールリクエスト URL では、リクエストヘッダー、クエリパラメーター、およびエンコーディングが省略されています。完全な URL の例については、以下の説明をご参照ください。
scroll メソッドは多くの機能のサポートが制限されています。制限事項の詳細なリストについては、以下の注記をご参照ください。

リクエストプロトコル

HTTP

HTTP リクエストメソッド

GET

サポートされるフォーマット

JSON

クエリパラメーター

パラメーター	タイプ	必須	値	デフォルト	説明
scroll	string	はい	week, day, hour, minute, second		次のスクロールリクエストのために検索コンテキストを保持する期間を指定します。このパラメーターは各リクエストで設定する必要があります。たとえば、1 分の場合は `1m` を使用します。サポートされている時間単位：`w` (週)、`d` (日)、`h` (時)、`m` (分)、`s` (秒)。
search_type	string	はい	scan		初期クエリに必須です。後続のクエリでは、このパラメーターを省略し、`scroll_id` を使用して次のバッチの結果を取得します。
scroll_id	string	はい			初期リクエストは `scroll_id` を返しますが、ドキュメントは返しません。後続のリクエストでは、前の応答から得た `scroll_id` を渡します。各後続の応答は、新しい `scroll_id` と次の一致するドキュメントのバッチを返します。
query 句	string	はい			検索条件を指定します。
config 句	string	はい			応答フォーマットと返すドキュメントの数を指定します。
filter 句	string	いいえ			フィルタリング条件を指定します。
sort 句	string	いいえ			ドキュメントのソート条件を指定します。単一の整数フィールドでのソートのみをサポートします。この句は V3 API および SDK でのみ利用可能です。
fetch_fields パラメーター	string	いいえ			結果で返すアプリケーションフィールドを指定します。

応答

パラメーター	タイプ	説明
status	string	リクエスト状態。`OK` は成功を示し、`FAIL` は失敗を示します。リクエストが失敗した場合は、返されたエラーコードを参照して問題をトラブルシューティングします。
request_id	string	クエリのリクエスト ID。主にトラブルシューティングに使用されます。
result	string	応答ペイロード。検索時間 (`searchtime`)、合計数 (`total`)、この応答の結果数 (`num`)、クエリの最大結果数 (`viewtotal`)、検索結果のリスト (`items`)、ファセット結果 (`facet`)、およびスクロール ID (`scroll_id`) が含まれます。
errors	string	エラー情報が含まれます。`error_message` フィールドにエラーメッセージが含まれます。各 `error_code` の説明については、「エラーコード」ドキュメントをご参照ください。

説明

scroll 操作は、fulljson または JSON フォーマットでのみ結果を返します。

スクロール

説明

注：config 句では、start は無視されます。リクエストごとに返すドキュメントの数を指定するには、hit の値を使用します。aggregate、distinct、粗から密へのランキング式などの機能はサポートされていません。sort 句は、単一の INT フィールドでのソートのみをサポートします。複数のアプリケーションにまたがるスクロールクエリは実行できません。無効な scroll_id を指定するとエラーが返されます。サポートされている応答フォーマットは fulljson と JSON のみです。最初のクエリは scroll_id のみを返し、ドキュメントデータは返しません。データを取得するには、前の応答から得た scroll_id を使用して後続のクエリを送信する必要があります。

最初のリクエスト

説明

この例では、リクエストヘッダーやエンコーディングなどの詳細は省略されています。

http://$host/v3/openapi/apps/app_schema_demo/search?query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'search'&&sort=+id&&filter=id>0&search_type=scan&scroll=1m&fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id

成功応答

{
  "status": "OK",
  "request_id": "150150574119953661605242",
  "result": {
    "searchtime": 0.005029,
    "total": 1,
    "num": 0,
    "viewtotal": 1,
    "scroll_id": "eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1 MMg3ROwCesLlG6X7a2o=",
    "items": [],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}

後続のリクエスト

説明

この例では、リクエストヘッダーやエンコーディングの詳細は省略されています。

http://$host/v3/openapi/apps/app_schema_demo/search?fetch_fields=id;name;phone;int_arr;literal_arr;float_arr;cate_id&query=config=start:0,hit:1,format:fulljson,rerank_size:200&&query=name:'search'&&sort=+id&&filter=id>0&scroll=1m&scroll_id=eJxtUMtuhDAM/BrvOYQC5cABdulvRFFIirsm2TpBavv1Ndut1EMlS36NZ0Y2ZHMxbueceAjIuWCMnrPjRITLyfzZm83y9V+QVGT8x80U3PxQNUqieVZV1/an4ItbTUBPSx5wgXqKdvOSbmuKR8ZYjGWWirB4tvToAiX7u3G2eCNK77vnz8GlGPAV6suKBeqxAn0OiTd7NGEnesspyoyFLF6hecn4JUKjVgp0K3FnkfMfIyPoDuYWegX9GeYOpicY9TG8gwOSuBL04X1+MMg3ROwCesLlG6X7a2o=

結果

{
  "status": "OK",
  "request_id": "150150574119952551519970",
  "result": {
    "searchtime": 0.006293,
    "total": 1,
    "num": 1,
    "viewtotal": 1,
    "scroll_id": "eJxNT9tugzAM/RrznIRC4YEHaNlvRFFIhteQtE6Qtn39TNdJk2z5dnx8rIPJRdudcqKhl60Uir2Vp06ISv8b6s3QbZCVzpaCdp93XXBzg2wEW9MJ2dWq8q7YVXt0YckDLlBP0WyOw31N8YgYizZEnAUsjkx4VT4k8zexpjiNS/XYHX0NNkWP71BfVyxQjxLUxSfazFH4PYSPnCL3iMniDZq3jN98aFRCgGrZniy8/itkBHWGuYVeQH+B+QzTCUZ1NJ9gj4FVMfrQPr8Y+Hk+dgU14fIDVhtfTw==",
    "items": [
      {
        "fields": {
          "cate_id": "0",
          "float_arr": "0",
          "id": "1",
          "int_arr": "0",
          "literal_arr": "search",
          "name": "search",
          "phone": "123****5678",
          "index_name": "app_schema_demo"
        },
        "property": {},
        "attribute": {},
        "variableValue": {},
        "sortExprValues": [
          "1"
        ]
      }
    ],
    "facet": []
  },
  "errors": [],
  "tracer": ""
}