翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # Amazon CloudSearch の検索 API リファレンス **Topics** + [検索](#search-request) + [Amazon CloudSearch での提案リクエストの送信](#submitting-suggest-requests) + [Suggest](#suggest) + [検索サービスのエラー](#search-service-errors) 検索 API を使用して、Amazon CloudSearch ドメインに検索リクエストまたは提案リクエストを送信します。検索の詳細については、「[Amazon CloudSearch でのデータの検索](searching.md)」を参照してください。候補の詳細については、「[Amazon CloudSearch でのオートコンプリート候補の取得](getting-suggestions.md)」を参照してください。 Amazon CloudSearch を操作するために使用するその他の API は次のとおりです。 + [設定 API](configuration-api.md) — 検索ドメインを設定および管理します。 + [ドキュメントサービス API](document-service-api.md) — 検索するデータを送信します。 ## 検索 このセクションでは、検索リソースの HTTP リクエストおよびレスポンスメッセージについて説明します。 ### 検索構文 ``` GET /2013-01-01/search ``` ### 検索リクエストヘッダー HOST クエリ対象のドメインの検索リクエストエンドポイント。[DescribeDomains](API_DescribeDomains.md) を使用して、ドメインの検索リクエストエンドポイントを取得できます。 必須: はい ### 検索リクエストのパラメータ cursor 大きな結果セットのページ分割に使用できるカーソル値を取得します。`size` パラメータを使用して、各レスポンスに含めるヒット数を制御します。リクエストで `cursor` または `start` パラメータのどちらかを指定できます。両者は相互に排他的です。詳細については、「[結果のページ分割](paginating-results.md)」を参照してください。 最初のカーソルを取得するには、最初のリクエストで `cursor=initial` を指定します。それ以降のリクエストでは、レスポンスの hits セクションで返されたカーソル値を指定します。 例えば、次のリクエストはカーソル値を `initial` に設定し、`size` パラメータを 100 に設定して、最初のヒットのセットを取得します。次のヒットセット用のカーソルは、レスポンスに含まれています。 ``` search?q=john&cursor=initial&size=100&return=_no_fields { "status": { "rid": "+/Xu5s0oHwojC6o=", "time-ms": 15 }, "hits": { "found": 503, "start": 0, "cursor": "VegKzpYYQW9JSVFFRU1UeWwwZERBd09EUTNPRGM9ZA", "hit": [ {"id": "tt0120601"}, {"id": "tt1801552"}, ... ] } } ``` 次のヒットのセットを取得するには、カーソル値と取得するヒットの数を指定します。 ``` search?q=john&cursor=VegKzpYYQW9JSVFFRU1UeWwwZERBd09EUTNPRGM9ZA&size=100 ``` タイプ: 文字列 必須: いいえ expr.NAME 結果のソートに使用する式を定義します。戻りフィールドとして式を指定することもできます。式の定義と使用の詳細については、「[式の設定](configuring-expressions.md)」を参照してください。 検索リクエストで複数の式を定義して使用することができます。例えば、次のリクエストは、結果のソートに使用する式を 2 つ作成し、式の値を検索結果に含めます。 ``` search?q=(and (term field=genres 'Sci-Fi')(term field=genres 'Comedy'))&q.parser=structured &expr.expression1=_score*rating &expr.expression2=(1/rank)*year &sort=expression1 desc,expression2 desc &return=title,rating,rank,year,_score,expression1,expression2 ``` タイプ: 文字列 必須: いいえ facet.FIELD ファセット情報を取得するフィールドを指定します — `FIELD` はフィールドの名前です。指定したフィールドは、ドメイン設定でファセットを有効にしておく必要があります。ファセットオプションは、JSON オブジェクトとして指定されます。JSON オブジェクトが空の場合 (`facet.FIELD={}`)、ファセット数はすべてのフィールド値について計算され、ファセットはファセット数によってソートされ、上位 10 個のファセットが結果で返されます。 JSON オブジェクトでは 3 つのオプションを指定できます。 + `sort` は結果でファセットをソートする方法を `bucket` または `count` で指定します。ファセット値のアルファベット順または数値順でソート (昇順) するには、`bucket` を指定します。各ファセット値に対して計算されたファセット数によってソート (降順) するには、`count` を指定します。特定の値または値範囲のファセット数を取得するには、`sort` の代わりに `buckets` オプションを使用します。 + `buckets` はカウントするファセット値または範囲の配列を指定します。バケットは、リクエストで指定された順番で返されます。値の範囲を指定するには、上限と下限をカンマ (,) で区切り、ブラケットか中括弧で範囲を囲みます。角括弧 [ ] は、その境界も範囲に含まれることを示し、波括弧 \$1 \$1 は、境界は除外することを示します。期限のない範囲を指定するには、上下の境界を省略します。境界を省略するときは、波括弧 \$1 \$1 を使用する必要があります。`buckets` を指定した場合、`sort` および `size` オプションは無効です。 + `size` はファセットの最大数を結果に含めることを指定します。デフォルトで、Amazon CloudSearch は上位 10 個のファセット数を返します。`size` パラメータは、`sort` オプションを指定した場合にのみ有効です。`buckets` と共に使用することはできません。 例えば、次のリクエストは `year` フィールドのファセット数を取得し、ファセット数の値によってソートし、上位 3 個のファセット数を返します。 ``` facet.year={sort:"bucket", size:3} ``` ファセット数を計算する値または値範囲を指定するには、`buckets` オプションを使用します。例えば、次のリクエストは 10 年単位でファセット数を計算して返します。 ``` facet.year={buckets:["[1970,1979]","[1980,1989]", "[1990,1999]","[2000,2009]", "[2010,}"]} ``` 個々の値をバケットとして指定することもできます。 ``` facet.genres={buckets:["Action","Adventure","Sci-Fi"]} ``` ファセット値は大文字小文字を区別することに注意してください。サンプルの IMDb 映画データの場合、`["Action","Adventure","Sci-Fi"]` の代わりに `["action","adventure","sci-fi"]` と指定すると、ファセット数がすべてゼロになります。 タイプ: 文字列 必須: いいえ format レスポンスのコンテンツタイプを指定します。 タイプ: 文字列 有効な値: json\$1xml デフォルト: json 必須: いいえ fq 結果のスコアやソート順に影響を与えることなく検索結果をフィルタする構造化クエリを指定します。`fq` は `q` パラメータと共に使用して、`q` パラメータで指定した制約に一致するドキュメントをフィルタします。フィルタを指定して、一致したドキュメントのうちどれを結果に含めるかを制御できますが、ドキュメントのスコアやソート順には影響しません。`fq` パラメータは、構造化クエリ構文を全面的にサポートします。フィルタを使用する方法については、「[一致するドキュメントのフィルタリング](filtering-results.md)」を参照してください。構造化クエリの詳細については、「[構造化検索構文](#structured-search-syntax)」を参照してください。 タイプ: 文字列 必須: いいえ highlight.FIELD 指定した `text` または `text-array` フィールドで一致したハイライトを取得します。ハイライトオプションは、JSON オブジェクトとして指定されます。JSON オブジェクトが空の場合、返されるフィールドテキストは HTML として扱われ、最初の一致が強調タグを使ってハイライト表示されます。`search-term` JSON オブジェクトで 4 つのオプションを指定できます。 + `format` — テキストフィールドのデータ形式を指定します。`text` または `html` です。データが HTML として返されると、アルファベット以外の文字はすべてエンコードされます。デフォルトは `html` です。 + `max_phrases` — 検索用語をハイライトする最大数を指定します。デフォルトでは、最初に出現した検索用語がハイライトされます。 + `pre_tag` — 出現した検索用語の前に追加する文字列を指定します。HTML ハイライトのデフォルトは `` です。テキストハイライトのデフォルトは `*` です。 + `post_tag` — 出現した検索用語の後に追加する文字列を指定します。HTML ハイライトのデフォルトは `` です。テキストハイライトのデフォルトは `*` です。 例: `highlight.plot={}`、`highlight.plot={format:'text',max_phrases:2,pre_tag:'',post_tag:''}` タイプ: 文字列 必須: いいえ partial 使用できないインデックスパーティションがある場合に、部分的な結果を返すかどうかを制御します。検索インデックスが複数の検索インスタンスにまたがって分割されていると、デフォルトでは Amazon CloudSearch はすべてのパーティションがクエリできる場合にのみ結果を返します。つまり、1 つの検索インスタンスに障害が発生するだけで、エラー 5xx (内部サーバー) が発生します。`partial=true` を指定する場合。Amazon CloudSearch は、利用できる結果をすべて返し、検索されたドキュメントの割合を検索結果に含めます (`percent-searched`)。これにより、検索結果の品質低下を緩和することができます。例えば、結果を何も表示しないよりは、部分的な結果を表示し、一時的なシステム障害により結果が完全でないことを示すメッセージを表示する方が親切です。 タイプ: ブール値 デフォルト: False 必須: いいえ pretty JSON 出力を読みやすいように整形します。 タイプ: ブール値 デフォルト: False 必須: いいえ q リクエストの検索条件。検索条件の指定方法は、リクエストで使用するクエリパーサー、および、`q.options` パラメータで指定するパーサーオプションによって異なります。デフォルトでは、`simple` クエリパーサーがリクエストの処理に使用されます。`structured`、`lucene`、`dismax` の各クエリパーサーを使用するには、`q.parser` パラメータも指定する必要があります。検索条件の指定方法の詳細については、「[Amazon CloudSearch でのデータの検索](searching.md)」を参照してください。 タイプ: 文字列 必須: はい q.options `q.parser` パラメータで指定したクエリパーサーのオプションを設定します。オプションは JSON オブジェクトとして、例えば `q.options={defaultOperator: 'or', fields: ['title^5','description']}` のように指定します。 設定できるオプションは、使用するパーサーに応じて変わります。 + `defaultOperator` — 検索文字列の個々の用語を結合する際に使用するデフォルト演算子。例: `defaultOperator: 'or'`。`dismax` パーサーの場合、デフォルトの演算子ではなく、一致する必要がある (切り捨られた) 検索文字列内の用語の割合を表す割合を指定します。`0%` という値は OR と同等で、`100%` という値は AND と同等です。割合は、0～100 の範囲の値として指定し、その後にパーセント記号 (%) を付ける必要があります。例えば、`defaultOperator: 50%`。有効な値: `and`、`or`、0～100% の範囲の割合 (`dismax`)。デフォルト: `and` (`simple`、`structured`、`lucene`) または `100` (`dismax`)。有効なパーサー: `simple`、`structured`、`lucene`、`dismax`。 + `fields` — 検索でフィールドが指定されていない場合に検索するフィールドの配列。検索でフィールドが指定されておらず、このオプションを指定しない場合、静的に設定されたすべての `text` と `text-array` が検索されます。各フィールドの重みを指定して、Amazon CloudSearch が関連性スコアを計算する際に各フィールドの相対重要度を制御できます。フィールドの重みを指定するには、フィールド名の後にキャレット記号 (`^`) を付けて重みを指定します。例えば、`title` フィールドに対する `description` フィールドの重要性を高めるには、`fields: ['title^5','description']` と指定します。有効な値: 設定されたフィールド名と、オプションの正の数値。デフォルト: 静的に設定されたすべての `text` フィールドと `text-array` フィールド。デフォルトでは、動的フィールドと `literal` フィールドは検索されません。有効なパーサー: `simple`、`structured`、`lucene`、`dismax`。 + `operators` — 簡易クエリパーサーで無効にする演算子または特殊文字の配列。`and`、`or`、`not` 演算子を無効にすると、対応する演算子 (`+`、`|`、`-`) は特別な意味を持たなくなり、検索文字列から削除されます。同様に、`prefix` を無効にするとワイルドカード演算子 (`*`) が無効になり、`phrase` を無効にすると二重引用符でフレーズを囲んたフレーズ検索が無効になります。優先順位を無効にすると、括弧を使って優先順位を制御する機能が無効になります。`near` を無効にすると、\$1 演算子を使ってあいまいフレーズ検索を実行する機能が無効になります。`fuzzy` 演算子を無効にすると、\$1 演算子を使ってあいまい検索を実行する機能が無効になります。`escape`​ は、バックスラッシュ (`\`) を使って検索文字列内の特殊文字をエスケープする機能を無効にします。whitespace は、パーサーが空白文字を区切りとしてトークン化しないようにする高度なオプションで、ベトナム語で役立つ場合があります。(ベトナム語の単語が間違って分割されなくなります)。例えば、`operators:['and', 'not', 'or', 'prefix']` と指定して、フレーズ演算子以外のすべての演算子を無効にし、単純な単語とフレーズのクエリだけをサポートすることもできます。有効な値: `and`、`escape`、`fuzzy`、`near`、`not`、`or`、`phrase`、`precedence`、`prefix`、`whitespace`デフォルト: すべての演算子と特殊文字が有効です。有効なパーサー: `simple`。 + `phraseFields` — フレーズ検索で使用する `text` または `text-array` フィールドの配列。検索文字列の用語がフィールド内の近接した場所に出現すると、フィールドのスコアが高くなります。各フィールドの重みを指定して、スコアを高くすることができます。`phraseSlop` オプションは、検索文字列から一致が逸脱していても、スコアを高くできる範囲を制御します。フィールドの重みを指定するには、フィールド名の後にキャレット記号 (`^`) を付けて重みを指定します。例えば、`title` フィールドのフレーズ一致のスコアを `abstract` フィールドよりも高くするには、`phraseFields:['title^3', 'abstract']` と指定できます。有効な値: `text` または `text-array` フィールドの名前とオプションの正の数値。デフォルト: フィールドなし。`phraseFields` でフィールドを 1 つも指定しない場合、`phraseSlop` を指定しても近接スコアは無効になります。有効なパーサー: `dismax`。 + `phraseSlop` — 検索フレーズからどの程度逸脱していても、`phraseFields` オプションで指定した重みに従ってスコアを高めることができるかを指定する整数値。例えば、`phraseSlop: 2`。近接スコアを有効にするには、`phraseFields` も指定する必要があります。有効な値: 正の整数。デフォルト: 0。有効なパーサー: `dismax`。 + `explicitPhraseSlop` — 検索文字列でフレーズが二重引用符で囲まれているときに、検索フレーズからどの程度逸脱できるかを指定する整数値 (この近接距離を超えるフレーズは一致と見なされません。) `explicitPhraseSlop: 5`。有効な値: 正の整数。デフォルト: 0。有効なパーサー: `dismax`。 + `tieBreaker` — 検索文字列の用語がドキュメントのフィールドに見つかると、他のドキュメントと比較してその単語がフィールド内でどの程度一般的であるかに基づいてスコアが計算されます。その用語がドキュメントの複数のフィールドに出現する場合、デフォルトでは、スコアが最も高いフィールドのみがドキュメント全体のスコアに反映されます。`tieBreaker` 値を指定すると、スコアが低いフィールドの一致もドキュメントのスコアに反映されるようにできます。こうすると、2 つのドキュメントで特定の用語についてフィールドの最大スコアが同じ場合、一致するフィールドの数が多いドキュメントの方がスコアが高くなります。tieBreaker を使ってスコアを計算する計算式は次のようになります。 ``` (max field score) + (tieBreaker) * (sum of the scores for the rest of the matching fields) ``` 例えば、次のクエリは、*dog* という用語を `title`、`description`、`review` フィールドで探し、`tieBreaker` を 0.1 に設定します。 ``` q=dog&q.parser=dismax&q.options={fields:['title', 'description', 'review'], tieBreaker: 0.1} ``` *dog* がドキュメントの 3 つのフィールドすべてに出現し、各フィールドのスコアが title=1、description=3、review=1 である場合、dog という用語の総合スコアは次のように計算されます。 ``` 3 + 0.1 * (1+1) = 3.2 ``` スコアが最高のフィールド以外は無視するには (純粋な最大値)、`tieBreaker` を 0 に設定します。すべてのフィールドのスコアを合計するには (純粋な合計)、1 に設定します。有効な値: 0.0～1.0. デフォルト: 0.0. 有効なパーサー: `dismax`。 タイプ: JSON オブジェクト デフォルト: 個々のオプションの説明を参照してください。 必須: いいえ q.parser リクエストの処理に使用するクエリパーサーを指定します。値は `simple`、`structured`、`lucene`、`dismax` です。`q.parser` を指定しない場合、Amazon CloudSearch は `simple` クエリパーサーを使用します。 + `simple` — `text` および `text-array` フィールドの単純な検索を実行します。デフォルトでは、`simple` クエリパーサーは静的に設定されたすべての `text` および `text-array` フィールドを検索します。`q.options` パラメータを使って、検索するフィールドを指定できます。検索用語の前にプラス記号 (\$1) を付ける場合、一致したと見なされるには、ドキュメントにその検索用語が含まれている必要があります (`q.options` パラメータを使ってデフォルト演算子を設定しない限り、これがデフォルトです)。`-` (NOT)、`|` (OR)、`*` (ワイルドカード) 演算子を使用して、特定の用語を除外したり、指定した用語のいずれかに一致する結果を得たり、プレフィックスを検索したりできます。個々の単語ではなくフレーズを検索するには、二重引用符でフレーズを囲みます。詳細については、「[Amazon CloudSearch でのデータの検索](searching.md)」を参照してください。 + `structured` — 複数の式を組み合わせて検索条件を定義して高度な検索を実行します。特定のフィールド内を検索したり、値および値範囲を検索したり、用語ブーストや `matchall`、`near` のような高度なオプションを使用することもできます。詳細については、「[複合クエリの作成](searching-compound-queries.md)」を参照してください。 + `lucene` — Apache Lucene のクエリパーサー構文を使用して検索します。詳細については、「[Apache Lucene のクエリパーサー構文](https://cwiki.apache.org/confluence/display/solr/The+Standard+Query+Parser)」を参照してください。 + `dismax` — DisMax のクエリパーサーで定義された Apache Lucene のクエリパーサー構文の簡略化されたサブセットを使用して検索します。詳細については、[「DisMax のクエリパーサー構文」](https://cwiki.apache.org/confluence/display/solr/The+DisMax+Query+Parser)を参照してください。 タイプ: 文字列 デフォルト: `simple` 必須: いいえ return レスポンスに含めるフィールドおよび式の値。カンマ区切りリストとして指定します。デフォルトでは、検索レスポンスは戻り値として使用できるすべてのフィールドを含みます (`return=_all_fields`)。一致するドキュメントのドキュメント ID のみを返すには、`return=_no_fields` を指定します。各ドキュメントに対して計算された関連性スコアを取得するには、`return=_score` を指定します。複数の戻り値フィールドはカンマ区切りリストとして指定します。例えば、`return=title,_score` は、一致する各ドキュメントのタイトルと関連性スコアのみを返します。 タイプ: 文字列 必須: いいえ size 返される検索ヒットの最大数。 タイプ: 正の整数 デフォルト: 10 必須: いいえ sort 検索結果をソートするときに使用するフィールドまたはカスタム式のカンマ区切りリスト。各フィールドに対してソート方向 (`asc` または `desc`) を指定する必要があります。例えば、`sort=year desc,title asc` です。最大 10 個のフィールドおよび式を指定できます。結果のソート時にフィールドを使用するには、ドメイン設定でそのフィールドによるソートを有効にしている必要があります。配列型のフィールドはソートに使用することができません。`sort` パラメータが指定されていない場合、結果はデフォルトの関連性スコアによって降順にソートされます (`sort=_score desc`)。ドキュメント ID (`sort=_id`) とバージョン (`sort=_version`) によってソートすることもできます。 タイプ: 文字列 必須: いいえ start 戻り値として返す最初の検索ヒットのオフセット。リクエストで `start` または `cursor` パラメータのどちらかを指定できます。両者は相互に排他的です。詳細については、「[結果のページ分割](paginating-results.md)」を参照してください。 タイプ: 正の整数 デフォルト: 0 (最初のヒット) 必須: いいえ #### 構造化検索構文 Amazon CloudSearch の構造化検索構文を使用して、`structured` クエリパーサーを使用するときの検索条件を定義し、`fq` パラメータを使ってフィルタ条件を指定します。 構造化クエリ演算子を使用するときは、演算子の名前、演算子のオプション、および操作対象の語句を `(OPERATOR OPTIONS STRING|EXPRESSION)` のように指定します。オプションは文字列または式の前に指定する必要があります。例えば、`(and (not field=genres 'Sci-Fi')(or (term field=title boost=2 'star')(term field=plot 'star')))` です。 **重要** クエリ文字列の特殊文字は、URL エンコードする必要があります。例えば、構造化クエリでの `=` 演算子は、`%3D`: `(term+field%3Dtitle+'star'` としてエンコードする必要があります。) Amazon CloudSearch では、特殊文字が URL エンコードされていないと `InvalidQueryString` エラーになります。URL エンコードの詳細については、W3C の[「HTML URL エンコードリファレンス」](http://www.w3schools.com/tags/ref_urlencode.asp)を参照してください。 構造化クエリパーサーを使用する際に検索対象フィールドを指定しない場合、静的に設定されたすべての `text` および `text-array` フィールドが検索されます。デフォルトでは、動的フィールドと `literal` フィールドは検索*されません*。`q.options` パラメータを使用して、デフォルトで検索するフィールドを指定できます。 括弧は、複合クエリで式の評価順序を制御します。式を括弧で囲んだ場合、その式が最初に評価され、その結果の値がクエリの残り部分の評価に使用されます。式には、構造化クエリ演算子を含めることができます。 構造化クエリパーサーを使用して、単純なテキスト文字列を検索することもできます。検索する文字列を一重引用符 `q='black swan'&q.parser="structured"` で囲むだけです。 構造化クエリ演算子を使った複合クエリの作成方法の詳細については、「[複合クエリの作成](searching-compound-queries.md)」を参照してください。 FIELD 構文: `FIELD: 'STRING'|value` 指定されたフィールドで、文字列、数値、日付、数値または日付の範囲を検索します。 文字列は一重引用符で囲む必要があります。文字列内の一重引用符やバックスラッシュは、バックスラッシュを使ってエスケープする必要があります。値の範囲を指定するには、上限と下限をカンマ (,) で区切り、ブラケットか中括弧で範囲を囲みます。角括弧 [ ] は、その境界も範囲に含まれることを示し、波括弧 \$1 \$1 は、境界は除外することを示します。期限のない範囲を指定するには、上下の境界を省略します。境界を省略するときは、波括弧 \$1 \$1 を使用する必要があります。 日付と時刻は、[IETF RFC3339](http://tools.ietf.org/html/rfc3339): `yyyy-mm-ddTHH:mm:ss.SSSZ` に従って、UTC (協定世界時) で指定されます。UTC 形式で、例えば、1970 年 8 月 23 日午後 5 時は、`1970-08-23T17:00:00Z` となります。UTC で時刻を指定する場合は、小数秒を指定することもできます。例えば、`1967-01-31T23:20:50.650Z.` です。 例: ``` title:'star' year:2000 year:[1998,2000] year:{,2011] release_date:['2013-01-01T00:00:00Z',} ``` and 構文: `(and boost=N EXPRESSION EXPRESSION ... EXPRESSIONn)` 指定した式がすべて一致する場合にのみドキュメントを含めます。(ブール型 `AND` 演算子。) 式には、構造化クエリ演算子または単純な検索文字列を含めることができます。検索文字列は一重引用符で囲む必要があります。検索するフィールドのいずれかで指定された用語を含むドキュメントに一致するためには、`(and 'star' 'wars')` のようにそれぞれの用語を別の式として指定する必要があります。`(and 'star wars')` と指定した場合、*star* と *wars* が同じフィールド内にある場合のみ一致とみなされます。 ブースト値は、検索クエリのこの部分の重要度を他の部分よりも大きくする正の数値です。 例: ``` (and title:'star' actors:'Harrison Ford' year:{,2000]) ``` matchall 構文: `matchall` ドメイン内のすべてのドキュメントが一致します。デフォルトでは、最初の 10 件を返します。`size` および `start` パラメータを使用して、結果をページ分割します。 near 構文: `(near field=FIELD distance=N boost=N 'STRING') ` 指定された複数用語の文字列を `text` または `text-array` で検索し、指定された距離内にそれらの用語を含んでいるドキュメントが一致します。(これは、*あいまい*フレーズ検索と呼ばれることがあります)。`field` オプションを省略する場合、Amazon CloudSearch は、デフォルトで静的に設定されたすべての `text` および `text-array` フィールドを検索します。デフォルトでは、動的フィールドと `literal` フィールドは検索されません。デフォルトで `q.options` `fields` オプションを指定することによって、検索するフィールドを指定できます。 距離値は正の整数である必要があります。例えば、`plot` フィールドで *vampire* から 10 語以内に *teenage* があるすべてのドキュメントを検索するには、距離値 10: `(near field=plot distance=10 'teenage vampire')` を指定します。 ブースト値は、検索クエリのこの部分の重要度を他の部分よりも大きくする正の数値です。 例: ``` (near field=plot distance=10 'teenage vampire') ``` not 構文: `(not boost=N EXPRESSION)` 指定された式に一致するドキュメントを除外します。(ブール `NOT` 演算子)。式には、構造化クエリ演算子または単純な検索文字列を含めることができます。検索文字列は一重引用符で囲む必要があります。 ブースト値は、検索クエリのこの部分の重要度を他の部分よりも大きくする正の数値です。 例: ``` (not (or actors:'Harrison Ford' year:{,2010])) ``` or 構文: `(or boost=N EXPRESSION1 EXPRESSION2 ... EXPRESSIONn)` 指定した式のいずれかが一致する場合にドキュメントを含めます。(ブール `OR` 演算子)。式には、構造化クエリ演算子または単純な検索文字列を含めることができます。検索文字列は一重引用符で囲む必要があります。 ブースト値は、検索クエリのこの部分の重要度を他の部分よりも大きくする正の数値です。 例: ``` (or actors:'Alec Guinness' actors:'Harrison Ford' actors:'James Earl Jones') ``` phrase 構文: `(phrase field=FIELD boost=N 'STRING')` 指定されたフレーズを `text` または `text-array` フィールドで検索します。`field` オプションを省略する場合、Amazon CloudSearch は、デフォルトで静的に設定されたすべての `text` および `text-array` フィールドを検索します。デフォルトでは、動的フィールドと `literal` フィールドは検索されません。`q.options` `fields` オプションを指定することで、デフォルトで検索するフィールドを指定できます。 `phrase` 演算子を使用して、フレーズ検索を構造化クエリの他の検索条件と組み合わせます。例えば、`q=(and (term field=title 'star') (range field=year {,2000]))` は、title フィールドに *star* を含み、year フィールドの値が 2000 以下のすべてのドキュメントに一致します。 ブースト値は、検索クエリのこの部分の重要度を他の部分よりも大きくする正の数値です。 例: ``` (phrase field=plot 'teenage girl') ``` prefix 構文: `(prefix field=FIELD boost=N 'STRING')` 指定されたプレフィックスにゼロ個以上の文字が続く文字列を `text`、`text-array`、`literal`、または `literal-array` フィールドで検索します。`field` オプションを省略する場合、Amazon CloudSearch は、デフォルトで静的に設定されたすべての `text` および `text-array` フィールドを検索します。デフォルトでは、動的フィールドと `literal` フィールドは検索されません。`q.options` `fields` オプションを指定することで、デフォルトで検索するフィールドを指定できます。 `prefix` 演算子を使用して、前方一致検索を構造化クエリの他の検索条件と組み合わせます。例えば、`q=(and (prefix field=title 'sta') (range field=year {,2000]))` は、title フィールドに *sta* というプレフィックスを含み、year フィールドの値が 2000 以下のすべてのドキュメントに一致します。 ブースト値は、検索クエリのこの部分の重要度を他の部分よりも大きくする正の数値です。 検索候補を実装するには、前方一致検索を実行するのではなく、サジェスタを設定してクエリします。詳細については、「[候補リクエスト](#suggest-request)」を参照してください。 例: ``` (prefix field=title 'star') ``` range 構文: `(range field=FIELD boost=N RANGE)` 数値フィールド (double、double-array、int、int-array) または日付フィールド (date、date-array) で、指定された範囲内の値を検索します。指定された範囲内の値がフィールドに少なくとも 1 つあるドキュメントに一致します。`field` オプションは必須です。 `range` 演算子を使用して、範囲検索を構造化クエリの他の検索条件と組み合わせます。例えば、`q=(and (term field=title 'star') (range field=year {,2000]))` は、title フィールドに *star* を含み、year フィールドの値が 2000 以下のすべてのドキュメントに一致します。 値の範囲を指定するには、上限と下限をカンマ (,) で区切り、ブラケットか中括弧で範囲を囲みます。角括弧 [ ] は、その境界も範囲に含まれることを示し、波括弧 \$1 \$1 は、境界は除外することを示します。期限のない範囲を指定するには、上下の境界を省略します。境界を省略するときは、波括弧 \$1 \$1 を使用する必要があります。 日付と時刻は、[IETF RFC3339](http://tools.ietf.org/html/rfc3339): `yyyy-mm-ddTHH:mm:ss.SSSZ` に従って、UTC (協定世界時) で指定されます。UTC 形式で、例えば、1970 年 8 月 23 日午後 5 時は、`1970-08-23T17:00:00Z` となります。UTC で時刻を指定する場合は、小数秒を指定することもできます。例えば、`1967-01-31T23:20:50.650Z.` です。 ブースト値は、検索クエリのこの部分の重要度を他の部分よりも大きくする正の数値です。 例: ``` (range field=year [1990,2000]) (range field=year {,2000]) (range field=year [1990,}) ``` term 構文: `(term field=FIELD boost=N 'STRING'|VALUE) ` 指定されたフィールドで文字列、数値、日付を検索します。値を検索するときは `field` オプションが必須です。`field` オプションを省略する場合、Amazon CloudSearch は、デフォルトで静的に設定されたすべての `text` および `text-array` フィールドを検索します。デフォルトでは、動的フィールドと `literal` フィールドは検索されません。`q.options` `fields` オプションを指定することで、デフォルトで検索するフィールドを指定できます。 `term` 演算子を使用して、用語検索を構造化クエリの他の検索条件と組み合わせます。例えば、`q=(and (term field=title 'star') (range field=year {,2000]))` は、title フィールドに *star* を含み、year フィールドの値が 2000 以下であるすべてのドキュメントに一致します。 文字列と日付は一重引用符で囲む必要があります。文字列内の一重引用符やバックスラッシュはバックスラッシュを使ってエスケープする必要があります。 日付と時刻は、[IETF RFC3339](http://tools.ietf.org/html/rfc3339): `yyyy-mm-ddTHH:mm:ss.SSSZ` に従って、UTC (協定世界時) で指定されます。UTC 形式で、例えば、1970 年 8 月 23 日午後 5 時は、`1970-08-23T17:00:00Z` となります。UTC で時刻を指定する場合は、小数秒を指定することもできます。例えば、`1967-01-31T23:20:50.650Z.` です。 ブースト値は、検索クエリのこの部分の重要度を他の部分よりも大きくする正の数値です。 例: ``` (term field=title 'star') (term field=year 2000) ``` #### 単純検索の構文 Amazon CloudSearch の単純検索の構文は、`simple` クエリパーサーで検索条件を定義するときに使用します。簡易クエリパーサーは、`q.parser` パラメータを指定しない場合にデフォルトで使用されます。 簡易クエリパーサーは、個々の用語またはフレーズを検索するときに使用します。デフォルトでは、静的に設定されたすべての `text` および `text-array` フィールドが検索されます。デフォルトでは、動的フィールドと `literal` フィールドは検索*されません*。`q.options` パラメータを使用して、検索するフィールドの指定、検索文字列で個々の用語を組み合わせるときに使用するデフォルト演算子の変更、または簡易パーサー演算子の無効化を実行できます (`and`、`escape`、`fuzzy`、`near`、`not`、`or`、`phrase`、`precedence`、`prefix`、`whitespace`)。 簡易クエリパーサーの使用法の詳細については、「[Amazon CloudSearch でのテキストの検索](searching-text.md)」を参照してください。 \$1 (and) 構文: `+TERM` 指定の用語が必須です。一致するには、ドキュメントが指定の用語を含んでいる必要があります。 例: \$1star \$1 (escape) 構文: `\CHAR` 検索する特殊文字をエスケープします。次の文字をクエリの一部とするにはエスケープする必要があります: \$1 - & \$1 \$1 ( ) \$1 \$1 [ ] ^ " \$1 \$1 ? : \$1 /。 例: `M\*A\*S\*H` \$1 (fuzzy) 構文: `TERM~N` あいまい検索を実行します。異なっていても用語が一致すると見なされる範囲を指定するには、用語の後に \$1 演算子と値を指定します。 例: `stor~1` \$1 (near) 構文: `"PHRASE"~N` あいまいフレーズ検索を実行します。用語が離れていてもフレーズに一致すると見なされる距離を指定するには、フレーズの後に \$1 演算子と値を指定します。 例: `"star wars"~4` - (not) 構文: `-TERM` 指定の用語を禁止します。一致するには、ドキュメントがその用語を含んでいてはなりません。 例: star -wars \$1 (or) 構文: `|TERM` 指定の用語を任意にします。 例: star \$1wars "..." (phrase) 構文: `"PHRASE"` フレーズ全体を検索します。`~` 演算子と組み合わせて、あいまいフレーズ検索を実行できます。 例: "star wars" (...) (precedence) 構文: `(...)` クエリの制約を評価する順番を制御します。最も内側にある括弧内のコンテンツが最初に評価されます。 例: `+(war|trek)+star` \$1 (prefix) 構文: `CHARS*` 指定された文字列と前方一致する用語を含むドキュメントに一致します。 例: `sta*` ### 検索レスポンス リクエストが正常に完了すると、レスポンス本体に検索結果が含まれます。デフォルトで、検索結果は JSON 形式で返されます。`format` パラメータを `xml` に設定すると、検索結果は XML 形式で返されます。 `return` パラメータを明示的に指定しない限り、一致する各ドキュメント (ヒット) のドキュメント ID、および戻り値として使用できるすべてのフィールドが含まれます。レスポンスには、見つかったヒット項目の合計数 (`found`) およびリストされている最初のドキュメントのインデックス (`start`) も示されます。デフォルトで、レスポンスは最初の 10 件のヒット項目を含みます。各レスポンスに含まれるヒット数を制御するには、リクエストに `size` パラメータを指定します。ヒット項目をページ分割するには、`start` または `cursor` パラメータを使用できます。詳細については、「[結果のページ分割](paginating-results.md)」を参照してください。 次の例は一般的な JSON レスポンスを示しています。 ``` { "status": { "rid": "rtKz7rkoeAojlvk=", "time-ms": 10 }, "hits": { "found": 3, "start": 0, "hit": [ { "id": "tt1142977", "fields": { "rating": "6.9", "genres": [ "Animation", "Comedy", "Family", "Horror", "Sci-Fi" ], "plot": "Young Victor conducts a science experiment to bring his beloved dog Sparky back to life, only to face unintended, sometimes monstrous, consequences.", "release_date": "2012-09-20T00:00:00Z", "title": "Frankenweenie", "rank": "1462", "running_time_secs": "5220", "directors": [ "Tim Burton" ], "image_url": "http://ia.media-imdb.com/images/M/MV5BMjIx ODY3MjEwNV5BMl5BanBnXkFtZTcwOTMzNjc4Nw@@._ V1_SX400_.jpg", "year": "2012", "actors": [ "Winona Ryder", "Catherine O'Hara", "Martin Short" ] } }, . . . ] } } ``` 次の例は同等の XML レスポンスを示しています。 ``` 6.9 Animation Comedy Family Horror Sci-Fi Young Victor conducts a science experiment to bring his beloved dog Sparky back to life, only to face unintended, sometimes monstrous, consequences. 2012-09-20T00:00:00Z Frankenweenie 1462 5220 Tim Burton http://ia.media-imdb.com/images/M/MV5BMjI xODY3MjEwNV5BMl5BanBnXkFtZTcwOTMzNjc4Nw@@. _V1_SX400_.jpg 2012 Winona Ryder Catherine O'Hara Martin Short . . . ``` レスポンス形式の設定は、成功したリクエストのレスポンスのみに影響します。エラーレスポンスの形式は、エラーの発生元によって異なります。検索サービスによって返されるエラーは、常に JSON 形式で返されます。サーバーのタイムアウトと他のリクエストのルーティングの問題による 5xx エラーは XML 形式で返されます。リクエストがエラーコードを返す場合、エラーレスポンスの本文には、発生したエラーに関する情報が含まれています。リクエストボディの解析および検証中にエラーが発生した場合、エラーコードは 400 に設定され、レスポンス本文にエラーのリストとその発生場所が含まれます。 #### 検索レスポンスのヘッダー Content-Type オブジェクトデータの形式を記述する標準 MIME タイプ。詳細については、[「W3C RFC 2616 Section 14」](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17)を参照してください。 有効な値: application/json または application/xml デフォルト: application/json Content-Length レスポンスの本文のバイト長。 #### 検索レスポンスのプロパティ (JSON) status リソース ID (rid) およびリクエストの処理にかかった時間 (time-ms) を含みます。 rid 暗号化されたリソース ID。 time-ms 検索リクエストを処理するのにかかった時間 (ミリ秒単位)。 hits 一致するドキュメントの数 (`found`)、レスポンスに含まれる最初のドキュメントのインデックス (`start`)、各ヒット項目のドキュメント ID とデータをリストした配列 (`hit`) を含みます。 found Amazon CloudSearch が検索リクエストの処理を終了した後、検索リクエストに一致するヒット項目の合計数。 start このレスポンスで返された最初のヒット項目のインデックス。 hit 各ヒット項目のドキュメント ID とデータをリストする配列。 id ドキュメントの一意の識別子。 fields 返されたフィールドのリスト。 facets ファセット情報とファセット数を含みます。 FACETFIELD ファセットが算出されたフィールド。 buckets 算出されたファセットの値と数の配列。 value カウントされるファセット値。 count `FACETFIELD` にファセット値を含むヒット数。 #### 検索レスポンスの要素 (XML) results 検索結果を含みます。リクエストの処理中に発生したエラーは、info 要素のメッセージとして返されます。 status リソース ID (`rid`)、およびリクエストの処理にかかった時間 (`time-ms`) を含みます。 hits ヒットの統計と hit 要素のコレクションを含みます。found 属性は、Amazon CloudSearch が結果の処理を終了した後、検索リクエストに一致するヒット項目の合計数です。含まれる hit 要素は、関連性スコアまたは検索リクエストで指定された `sort` オプションに応じてソートされます。 hit 検索リクエストに一致するドキュメント。id 属性は、ドキュメントの一意の ID です。返される各フィールドの `d` (データ) 要素を含みます。 field ヒット項目から返されるフィールド。hit 要素は、返される各フィールドの `d` (データ) 要素を含みます。 facets 検索リクエストでリクエストされた各ファセットの facet 要素を含みます。 facet ファセット数が算出されたフィールドの各値の bucket 要素を含みます。`facet.FIELD` の size オプションを使用して、返される制約の数を指定できます。デフォルトで、上位 10 個の制約のファセット数が返されます。`facet.FIELD` の buckets オプションを使用して、カウントする値を明示的に指定することができます。 bucket ファセットフィールド値と、検索ヒット内でその値が出現する回数 (カウント)。 ## Amazon CloudSearch での提案リクエストの送信 候補リクエストは、HTTP GET 経由でドメインの検索エンドポイント (`2013-01-01/suggest`) に送信します。提案サービスへのアクセスを制御する方法については、「[Amazon CloudSearch のアクセスの設定](configuring-access.md)」を参照してください。 すべての候補リクエストで API バージョンを指定する必要があり、そのバージョンはドメインを作成したときに指定されたバージョンと一致している必要があります。 例えば、次のリクエストは、`search-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch.amazonaws.com` というサジェスタを使用して `oce` ドメインからクエリ文字列 `title` の候補を取得します。 ``` http://search-imdb-hd6ebyouhw2lczkueyuqksnuzu.us-west-2.cloudsearch.amazonaws.com/2013-01-01/suggest -d"q=oce&suggester=suggest_title" ``` ドメインの検索エンドポイントに GET リクエストを送信する任意のメソッドを使用できます。ウェブブラウザにリクエスト URL を直接入力したり、cURL を使用してリクエストを送信したり、お気に入りの HTTP ライブラリを使用して HTTP 呼び出しを生成したりできます。また、Amazon CloudSearch コンソールで検索テスターを使用して候補を取得することもできます。詳細については、「[検索テスターによる検索](getting-started-search.md#searching-console)」を参照してください。 **重要** ドメインのドキュメントエンドポイントと検索エンドポイントは、ドメインが存在している間変わりません。すべてのアップロードリクエストや検索リクエストの前にエンドポイントを取得するのではなく、エンドポイントをキャッシュに保存してください。各リクエストの前に `aws cloudsearch describe-domains` または `DescribeDomains` を呼び出すことによって Amazon CloudSearch 設定サービスにクエリを実行すると、リクエストが調整される可能性があります。 デフォルトでは、Amazon CloudSearch は JSON 形式でレスポンスを返します。`format` パラメータを `format=xml` のように指定して、結果を XML 形式で取得できます レスポンス形式の設定は、成功したリクエストのレスポンスのみに影響します。エラーレスポンスの形式は、エラーの発生元によって異なります。検索サービスによって返されるエラーは、常に JSON 形式で返されます。サーバーのタイムアウトと他のリクエストのルーティングの問題による 5xx エラーは XML 形式で返されます。 ## Suggest ### 候補リクエスト #### Amazon CloudSearch での提案構文 ``` GET /2013-01-01/suggest ``` #### Amazon CloudSearch での提案リクエストヘッダー HOST クエリ対象のドメインの検索リクエストエンドポイント。[DescribeDomains](API_DescribeDomains.md) を使用して、ドメインの検索リクエストエンドポイントを取得できます。 必須: はい #### Amazon CloudSearch での提案リクエストのパラメータ q 候補を入手する文字列。 タイプ: 文字列 必須: はい suggester 一致候補を見つけるのに使用するサジェスタの名前。 タイプ: 文字列 必須: はい size 返される候補の最大数。 タイプ: 正の整数 デフォルト: 10 必須: いいえ format レスポンスのコンテンツタイプを指定します。 タイプ: 文字列 有効な値: json\$1xml デフォルト: json 必須: いいえ ### 候補レスポンス リクエストが正常に完了すると、レスポンス本体に候補が含まれています。デフォルトでは、候補は JSON 形式で返されます。XML 形式で結果を得るには、`format` パラメータを `xml` に設定します。 レスポンス形式の設定は、成功したリクエストのレスポンスのみに影響します。エラーレスポンスの形式は、エラーの発生元によって異なります。検索サービスによって返されるエラーは、常に JSON 形式で返されます。サーバーのタイムアウトと他のリクエストのルーティングの問題による 5xx エラーは XML 形式で返されます。リクエストがエラーコードを返す場合、エラーレスポンスの本文には、発生したエラーに関する情報が含まれています。リクエストボディの解析および検証中にエラーが発生した場合、エラーコードは 400 に設定され、レスポンス本文にエラーのリストとその発生場所が含まれます。 次の例は候補リクエストに対する JSON レスポンスを示しています。 ``` { "status": { "rid": "qOSM5s0oCwr8pVk=", "time-ms": 2 }, "suggest": { "query": "oce", "found": 3, "suggestions": [ { "suggestion": "Ocean's Eleven", "score": 0, "id": "tt0054135" }, { "suggestion": "Ocean's Thirteen", "score": 0, "id": "tt0496806" }, { "suggestion": "Ocean's Twelve", "score": 0, "id": "tt0349903" } ] } } ``` 次の例は同等の XML レスポンスを示しています。 ``` ``` ## 検索サービスのエラー 検索リクエストまたは候補リクエストは、3 種類のステータスコードを返します。 + 5xx ステータスコードは、内部サーバーエラーが発生したことを示します。5xx エラーコードは、一般に一時的なエラー条件を表すため、すべてキャッチして再試行する必要があります。詳細については、「[エラー処理](error-handling.md)」を参照してください。 + 4xx ステータスコードは、リクエストの形式が正しくないことを示します。エラーを修正してリクエストを再送信してください。 + 2xx ステータスコードは、リクエストが正常に処理されたことを示します。 エラーレスポンスの形式は、エラーの発生元によって異なります。検索サービスによって返されるエラーは、常に JSON 形式で返されます。サーバーのタイムアウトと他のリクエストのルーティングの問題による 5xx エラーは XML 形式で返されます。 検索サービスが返すエラーは次の情報を含みます。 error 検索サービスが返したエラーメッセージを含みます。各エラーには `code` および `msg` プロパティが含まれています。 code エラーコードです。 msg 検索サービスが返したエラーの説明。