Amazon の検索 API リファレンス CloudSearch - Amazon CloudSearch
検索候補リクエストの送信候補検索サービスのエラー

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amazon の検索 API リファレンス CloudSearch

Search API を使用して、Amazon CloudSearch ドメインに検索または提案リクエストを送信します。検索の詳細については、「Amazon でのデータの検索 CloudSearch」を参照してください。候補の詳細については、「Amazon でのオートコンプリート候補の取得 CloudSearch」を参照してください。

Amazon とのやり取りに使用するその他の APIs CloudSearch は次のとおりです。

検索

このセクションでは、検索リソースの HTTP リクエストおよびレスポンスメッセージについて説明します。

検索構文

GET /2013-01-01/search

検索リクエストヘッダー

HOST

クエリ対象のドメインの検索リクエストエンドポイント。DescribeDomains を使用して、ドメインの検索リクエストエンドポイントを取得できます。

必須: はい

検索リクエストのパラメータ

cursor

大きな結果セットのページ分割に使用できるカーソル値を取得します。size パラメータを使用して、各レスポンスに含めるヒット数を制御します。リクエストで cursor または start パラメータのどちらかを指定できます。両者は相互に排他的です。詳細については、「Paginate the results」を参照してください。

最初のカーソルを取得するには、最初のリクエストで 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

結果のソートに使用する式を定義します。戻りフィールドとして式を指定することもできます。式の定義と使用の詳細については、「式の設定」を参照してください。

検索リクエストで複数の式を定義して使用することができます。例えば、次のリクエストは、結果のソートに使用する式を 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 はカウントするファセット値または範囲の配列を指定します。バケットは、リクエストで指定された順番で返されます。値の範囲を指定するには、上限と下限をカンマ (,) で区切り、ブラケットか中括弧で範囲を囲みます。角括弧 [ ] は、その境界も範囲に含まれることを示し、波括弧 { } は、境界は除外することを示します。期限のない範囲を指定するには、上下の境界を省略します。境界を省略するときは、波括弧 { } を使用する必要があります。buckets を指定した場合、sort および size オプションは無効です。

  • size はファセットの最大数を結果に含めることを指定します。デフォルトでは、Amazon は上位 10 個のカウント CloudSearch を返します。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|xml

デフォルト: json

必須: いいえ

fq

結果のスコアやソート順に影響を与えることなく検索結果をフィルタする構造化クエリを指定します。fq は q パラメータと共に使用して、q パラメータで指定した制約に一致するドキュメントをフィルタします。フィルタを指定して、一致したドキュメントのうちどれを結果に含めるかを制御できますが、ドキュメントのスコアやソート順には影響しません。fq パラメータは、構造化クエリ構文を全面的にサポートします。フィルタを使用する方法については、「一致するドキュメントのフィルタリング」を参照してください。構造化クエリの詳細については、「構造化検索構文」を参照してください。

タイプ: 文字列

必須: いいえ

highlight.FIELD

指定した text または text-array フィールドで一致したハイライトを取得します。ハイライトオプションは、JSON オブジェクトとして指定されます。JSON オブジェクトが空の場合、返されるフィールドテキストは HTML として扱われ、最初の一致が強調タグを使ってハイライト表示されます。<em>search-term</em>

JSON オブジェクトで 4 つのオプションを指定できます。

  • format — テキストフィールドのデータ形式を指定します。text または html です。データが HTML として返されると、アルファベット以外の文字はすべてエンコードされます。デフォルトは html です。

  • max_phrases — 検索用語をハイライトする最大数を指定します。デフォルトでは、最初に出現した検索用語がハイライトされます。

  • pre_tag — 出現した検索用語の前に追加する文字列を指定します。HTML ハイライトのデフォルトは <em> です。テキストハイライトのデフォルトは * です。

  • post_tag — 出現した検索用語の後に追加する文字列を指定します。HTML ハイライトのデフォルトは </em> です。テキストハイライトのデフォルトは * です。

例: highlight.plot={}、highlight.plot={format:'text',max_phrases:2,pre_tag:'<b>',post_tag:'</b>'}

タイプ: 文字列

必須: いいえ

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」を参照してください。

型: 文字列

必須: はい

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 を無効にすると、~ 演算子を使ってあいまいフレーズ検索を実行する機能が無効になります。fuzzy 演算子を無効にすると、~ 演算子を使ってあいまい検索を実行する機能が無効になります。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 です。が指定されていない場合、Amazon CloudSearch q.parserはsimpleクエリパーサーを使用します。

  • simple — text および text-array フィールドの単純な検索を実行します。デフォルトでは、simple クエリパーサーは静的に設定されたすべての text および text-array フィールドを検索します。q.options パラメータを使って、検索するフィールドを指定できます。検索用語の前にプラス記号 (+) を付ける場合、一致したと見なされるには、ドキュメントにその検索用語が含まれている必要があります (q.options パラメータを使ってデフォルト演算子を設定しない限り、これがデフォルトです)。- (NOT)、| (OR)、* (ワイルドカード) 演算子を使用して、特定の用語を除外したり、指定した用語のいずれかに一致する結果を得たり、プレフィックスを検索したりできます。個々の単語ではなくフレーズを検索するには、二重引用符でフレーズを囲みます。詳細については、「Amazon でのデータの検索 CloudSearch」を参照してください。

  • structured — 複数の式を組み合わせて検索条件を定義して高度な検索を実行します。特定のフィールド内を検索したり、値および値範囲を検索したり、用語ブーストや matchall、near のような高度なオプションを使用することもできます。詳細については、「複合クエリの作成」を参照してください。

  • lucene — Apache Lucene のクエリパーサー構文を使用して検索します。詳細については、「Apache Lucene のクエリパーサー構文」を参照してください。

  • dismax— クエリパーサーで定義された Apache Lucene DisMax クエリパーサー構文の簡略化されたサブセットを使用して検索します。詳細については、DisMax 「クエリパーサー構文」を参照してください。

タイプ: 文字列

デフォルト: 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 パラメータのどちらかを指定できます。両者は相互に排他的です。詳細については、「Paginate the results」を参照してください。

タイプ: 正の整数

デフォルト: 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' としてエンコードする必要があります。) 特殊文字が URL エンコードされていない場合、Amazon はInvalidQueryStringエラー CloudSearch を返します。URL エンコードの詳細については、W3C の「HTML URL エンコードリファレンス」を参照してください。

構造化クエリパーサーを使用する際に検索対象フィールドを指定しない場合、静的に設定されたすべての text および text-array フィールドが検索されます。デフォルトでは、動的フィールドと literal フィールドは検索されません。q.options パラメータを使用して、デフォルトで検索するフィールドを指定できます。

括弧は、複合クエリで式の評価順序を制御します。式を括弧で囲んだ場合、その式が最初に評価され、その結果の値がクエリの残り部分の評価に使用されます。式には、構造化クエリ演算子を含めることができます。

構造化クエリパーサーを使用して、単純なテキスト文字列を検索することもできます。検索する文字列を一重引用符 q='black swan'&q.parser="structured" で囲むだけです。

構造化クエリ演算子を使った複合クエリの作成方法の詳細については、「複合クエリの作成」を参照してください。

FIELD

構文: FIELD: 'STRING'|value

指定されたフィールドで、文字列、数値、日付、数値または日付の範囲を検索します。

文字列は一重引用符で囲む必要があります。文字列内の一重引用符やバックスラッシュは、バックスラッシュを使ってエスケープする必要があります。値の範囲を指定するには、上限と下限をカンマ (,) で区切り、ブラケットか中括弧で範囲を囲みます。角括弧 [ ] は、その境界も範囲に含まれることを示し、波括弧 { } は、境界は除外することを示します。期限のない範囲を指定するには、上下の境界を省略します。境界を省略するときは、波括弧 { } を使用する必要があります。

日付と時刻は、IETF 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 はデフォルトで静的に設定されたすべての フィールドtextと text-arrayフィールド CloudSearch を検索します。デフォルトでは、動的フィールドと 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 はデフォルトで静的に設定されたすべての フィールドtextと text-arrayフィールド CloudSearch を検索します。デフォルトでは、動的フィールドと 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 はデフォルトで静的に設定されたすべての フィールドtextと text-arrayフィールド CloudSearch を検索します。デフォルトでは、動的フィールドと literal フィールドは検索されません。q.options fields オプションを指定することで、デフォルトで検索するフィールドを指定できます。

prefix 演算子を使用して、前方一致検索を構造化クエリの他の検索条件と組み合わせます。例えば、q=(and (prefix field=title 'sta') (range field=year {,2000])) は、title フィールドに sta というプレフィックスを含み、year フィールドの値が 2000 以下のすべてのドキュメントに一致します。

ブースト値は、検索クエリのこの部分の重要度を他の部分よりも大きくする正の数値です。

注記

検索候補を実装するには、前方一致検索を実行するのではなく、サジェスタを設定してクエリします。詳細については、「候補リクエスト」を参照してください。

例：

(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 以下のすべてのドキュメントに一致します。

値の範囲を指定するには、上限と下限をカンマ (,) で区切り、ブラケットか中括弧で範囲を囲みます。角括弧 [ ] は、その境界も範囲に含まれることを示し、波括弧 { } は、境界は除外することを示します。期限のない範囲を指定するには、上下の境界を省略します。境界を省略するときは、波括弧 { } を使用する必要があります。

日付と時刻は、IETF 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 はデフォルトで静的に設定されたすべての フィールドtextと text-arrayフィールド CloudSearch を検索します。デフォルトでは、動的フィールドと literal フィールドは検索されません。q.options fields オプションを指定することで、デフォルトで検索するフィールドを指定できます。

term 演算子を使用して、用語検索を構造化クエリの他の検索条件と組み合わせます。例えば、q=(and (term field=title 'star') (range field=year {,2000])) は、title フィールドに star を含み、year フィールドの値が 2000 以下であるすべてのドキュメントに一致します。

文字列と日付は一重引用符で囲む必要があります。文字列内の一重引用符やバックスラッシュはバックスラッシュを使ってエスケープする必要があります。

日付と時刻は、IETF 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)。

簡易クエリパーサーの使用法の詳細については、「text」を参照してください。

+ (and)

構文: +TERM

指定の用語が必須です。一致するには、ドキュメントが指定の用語を含んでいる必要があります。

例: +star

\ (escape)

構文: \CHAR

検索する特殊文字をエスケープします。次の文字をクエリの一部とするにはエスケープする必要があります: + - & | ! ( ) { } [ ] ^ " ~ * ? : \ /。

例: M\*A\*S\*H

~ (fuzzy)

構文: TERM~N

あいまい検索を実行します。異なっていても用語が一致すると見なされる範囲を指定するには、用語の後に ~ 演算子と値を指定します。

例: stor~1

~ (near)

構文: "PHRASE"~N

あいまいフレーズ検索を実行します。用語が離れていてもフレーズに一致すると見なされる距離を指定するには、フレーズの後に ~ 演算子と値を指定します。

例: "star wars"~4

- (not)

構文: -TERM

指定の用語を禁止します。一致するには、ドキュメントがその用語を含んでいてはなりません。

例: star -wars

| (or)

構文: |TERM

指定の用語を任意にします。

例: star |wars

"..." (phrase)

構文: "PHRASE"

フレーズ全体を検索します。~ 演算子と組み合わせて、あいまいフレーズ検索を実行できます。

例: "star wars"

(...) (precedence)

構文: (...)

クエリの制約を評価する順番を制御します。最も内側にある括弧内のコンテンツが最初に評価されます。

例: +(war|trek)+star

* (prefix)

構文: CHARS*

指定された文字列と前方一致する用語を含むドキュメントに一致します。

例: sta*

検索レスポンス

リクエストが正常に完了すると、レスポンス本体に検索結果が含まれます。デフォルトで、検索結果は JSON 形式で返されます。format パラメータを xml に設定すると、検索結果は XML 形式で返されます。

return パラメータを明示的に指定しない限り、一致する各ドキュメント (ヒット) のドキュメント ID、および戻り値として使用できるすべてのフィールドが含まれます。レスポンスには、見つかったヒット項目の合計数 (found) およびリストされている最初のドキュメントのインデックス (start) も示されます。デフォルトで、レスポンスは最初の 10 件のヒット項目を含みます。各レスポンスに含まれるヒット数を制御するには、リクエストに size パラメータを指定します。ヒット項目をページ分割するには、start または cursor パラメータを使用できます。詳細については、「Paginate the results」を参照してください。

次の例は一般的な 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 レスポンスを示しています。

<results>
    <status rid="itzL7rkoeQojlvk=" time-ms="34"/>
    <hits found="3" start="0">
        <hit id="tt1142977">
            <field name="rating">6.9</field>
            <field name="genres">Animation</field>
            <field name="genres">Comedy</field>
            <field name="genres">Family</field>
            <field name="genres">Horror</field>
            <field name="genres">Sci-Fi</field>
            <field name="plot">Young Victor conducts a science experiment to
                               bring his beloved dog Sparky back to life, only
                               to face unintended, sometimes monstrous, 
                               consequences.
            </field>
            <field name="release_date">2012-09-20T00:00:00Z</field>
            <field name="title">Frankenweenie</field>
            <field name="rank">1462</field>
            <field name="running_time_secs">5220</field>
            <field name="directors">Tim Burton</field>
            <field name="image_url">http://ia.media-imdb.com/images/M/MV5BMjI
                                    xODY3MjEwNV5BMl5BanBnXkFtZTcwOTMzNjc4Nw@@.
                                    _V1_SX400_.jpg
            </field>
            <field name="year">2012</field>
            <field name="actors">Winona Ryder</field>
            <field name="actors">Catherine O'Hara</field>
            <field name="actors">Martin Short</field>
        </hit>
        .
        .
        .
    </hits>
</results>

レスポンス形式の設定は、成功したリクエストのレスポンスのみに影響します。エラーレスポンスの形式は、エラーの発生元によって異なります。検索サービスによって返されるエラーは、常に JSON 形式で返されます。サーバーのタイムアウトと他のリクエストのルーティングの問題による 5xx エラーは XML 形式で返されます。リクエストがエラーコードを返す場合、エラーレスポンスの本文には、発生したエラーに関する情報が含まれています。リクエストボディの解析および検証中にエラーが発生した場合、エラーコードは 400 に設定され、レスポンス本文にエラーのリストとその発生場所が含まれます。

検索レスポンスのヘッダー

Content-Type

オブジェクトデータの形式を記述する標準 MIME タイプ。詳細については、「W3C RFC 2616 Section 14」を参照してください。

有効な値: 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) に送信します。提案サービスへのアクセスを制御する方法については、「configure access policies」を参照してください。

すべての候補リクエストで 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 コンソールの検索テスターを使用して、候補を取得することもできます。詳細については、「検索テスターによる検索」を参照してください。

重要

ドメインのドキュメントエンドポイントと検索エンドポイントは、ドメインが存在している間変わりません。すべてのアップロードリクエストや検索リクエストの前にエンドポイントを取得するのではなく、エンドポイントをキャッシュに保存してください。DescribeDomains すべてのリクエストの前に aws cloudsearch describe-domainsまたは を呼び出して Amazon CloudSearch 設定サービスをクエリすると、リクエストがスロットリングされる可能性があります。

デフォルトでは、Amazon はレスポンスを JSON で CloudSearch 返します。format パラメータを format=xml のように指定して、結果を XML 形式で取得できます レスポンス形式の設定は、成功したリクエストのレスポンスのみに影響します。エラーレスポンスの形式は、エラーの発生元によって異なります。検索サービスによって返されるエラーは、常に JSON 形式で返されます。サーバーのタイムアウトと他のリクエストのルーティングの問題による 5xx エラーは XML 形式で返されます。

候補

候補リクエスト

Amazon での提案構文 CloudSearch

GET /2013-01-01/suggest

Amazon での提案リクエストヘッダー CloudSearch

HOST

クエリ対象のドメインの検索リクエストエンドポイント。DescribeDomains を使用して、ドメインの検索リクエストエンドポイントを取得できます。

必須: はい

Amazon での提案リクエストパラメータ CloudSearch

q

候補を入手する文字列。

型: 文字列

必須: はい

suggester

一致候補を見つけるのに使用するサジェスタの名前。

型: 文字列

必須: はい

size

返される候補の最大数。

タイプ: 正の整数

デフォルト: 10

必須: いいえ

format

レスポンスのコンテンツタイプを指定します。

型: 文字列

有効な値: json|xml

デフォルト: 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 レスポンスを示しています。

<results>
   <status rid="/pSz580oDQr8pVk=" time-ms="2"/>
   <suggest query="oce" found="3">
      <suggestions>
         <item suggestion="Ocean's Eleven" score="0" id="tt0054135"/>
         <item suggestion="Ocean's Thirteen" score="0" id="tt0496806"/>
         <item suggestion="Ocean's Twelve" score="0" id="tt0349903"/>
      </suggestions>
   </suggest>
</results>

検索サービスのエラー

検索リクエストまたは候補リクエストは、3 種類のステータスコードを返します。

  • 5xx ステータスコードは、内部サーバーエラーが発生したことを示します。5xx エラーコードは、一般に一時的なエラー条件を表すため、すべてキャッチして再試行する必要があります。詳細については、「エラー処理」を参照してください。

  • 4xx ステータスコードは、リクエストの形式が正しくないことを示します。エラーを修正してリクエストを再送信してください。

  • 2xx ステータスコードは、リクエストが正常に処理されたことを示します。

エラーレスポンスの形式は、エラーの発生元によって異なります。検索サービスによって返されるエラーは、常に JSON 形式で返されます。サーバーのタイムアウトと他のリクエストのルーティングの問題による 5xx エラーは XML 形式で返されます。

検索サービスが返すエラーは次の情報を含みます。

error

検索サービスが返したエラーメッセージを含みます。各エラーには code および msg プロパティが含まれています。

code

エラーコードです。

msg

検索サービスが返したエラーの説明。