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

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

必須: はい

大きな結果セットのページ分割に使用できるカーソル値を取得します。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

タイプ: 文字列

必須: いいえ

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

検索リクエストで複数の式を定義して使用することができます。例えば、次のリクエストは、結果のソートに使用する式を 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

タイプ: 文字列

必須: いいえ

ファセット情報を取得するフィールドを指定します — FIELD はフィールドの名前です。指定したフィールドは、ドメイン設定でファセットを有効にしておく必要があります。ファセットオプションは、JSON オブジェクトとして指定されます。JSON オブジェクトが空の場合 (facet.FIELD={})、ファセット数はすべてのフィールド値について計算され、ファセットはファセット数によってソートされ、上位 10 個のファセットが結果で返されます。

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

例えば、次のリクエストは 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"] と指定すると、ファセット数がすべてゼロになります。

タイプ: 文字列

必須: いいえ

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

タイプ: 文字列

有効な値: json|xml

デフォルト: json

必須: いいえ

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

タイプ: 文字列

必須: いいえ

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

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

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

タイプ: 文字列

必須: いいえ

使用できないインデックスパーティションがある場合に、部分的な結果を返すかどうかを制御します。検索インデックスが複数の検索インスタンスにまたがって分割されていると、デフォルトでは Amazon CloudSearch はすべてのパーティションがクエリできる場合にのみ結果を返します。つまり、1 つの検索インスタンスに障害が発生するだけで、エラー 5xx (内部サーバー) が発生します。partial=true を指定する場合。Amazon CloudSearch は、利用できる結果をすべて返し、検索されたドキュメントの割合を検索結果に含めます (percent-searched)。これにより、検索結果の品質低下を緩和することができます。例えば、結果を何も表示しないよりは、部分的な結果を表示し、一時的なシステム障害により結果が完全でないことを示すメッセージを表示する方が親切です。

型: ブール値

デフォルト: False

必須: いいえ

JSON 出力を読みやすいように整形します。

型: ブール値

デフォルト: False

必須: いいえ

リクエストの検索条件。検索条件の指定方法は、リクエストで使用するクエリパーサー、および、q.options パラメータで指定するパーサーオプションによって異なります。デフォルトでは、simple クエリパーサーがリクエストの処理に使用されます。structured、lucene、dismax の各クエリパーサーを使用するには、q.parser パラメータも指定する必要があります。検索条件の指定方法の詳細については、「Amazon CloudSearch でのデータの検索」を参照してください。

タイプ: 文字列

必須: はい

q.parser パラメータで指定したクエリパーサーのオプションを設定します。オプションは JSON オブジェクトとして、例えば q.options={defaultOperator: 'or', fields: ['title^5','description']} のように指定します。

設定できるオプションは、使用するパーサーに応じて変わります。

タイプ: JSON オブジェクト

デフォルト: 個々のオプションの説明を参照してください。

必須: いいえ

リクエストの処理に使用するクエリパーサーを指定します。値は simple、structured、lucene、dismax です。q.parser を指定しない場合、Amazon CloudSearch は simple クエリパーサーを使用します。

タイプ: 文字列

デフォルト: simple

必須: いいえ

レスポンスに含めるフィールドおよび式の値。カンマ区切りリストとして指定します。デフォルトでは、検索レスポンスは戻り値として使用できるすべてのフィールドを含みます (return=_all_fields)。一致するドキュメントのドキュメント ID のみを返すには、return=_no_fields を指定します。各ドキュメントに対して計算された関連性スコアを取得するには、return=_score を指定します。複数の戻り値フィールドはカンマ区切りリストとして指定します。例えば、return=title,_score は、一致する各ドキュメントのタイトルと関連性スコアのみを返します。

タイプ: 文字列

必須: いいえ

返される検索ヒットの最大数。

タイプ: 正の整数

デフォルト: 10

必須: いいえ

検索結果をソートするときに使用するフィールドまたはカスタム式のカンマ区切りリスト。各フィールドに対してソート方向 (asc または desc) を指定する必要があります。例えば、sort=year desc,title asc と指定します。最大 10 個のフィールドおよび式を指定できます。結果のソート時にフィールドを使用するには、ドメイン設定でそのフィールドによるソートを有効にしている必要があります。配列型のフィールドはソートに使用することができません。sort パラメータが指定されていない場合、結果はデフォルトの関連性スコアによって降順にソートされます (sort=_score desc)。ドキュメント ID (sort=_id) とバージョン (sort=_version) によってソートすることもできます。

タイプ: 文字列

必須: いいえ

戻り値として返す最初の検索ヒットのオフセット。リクエストで start または cursor パラメータのどちらかを指定できます。両者は相互に排他的です。詳細については、「Paginate the results」を参照してください。

タイプ: 正の整数

デフォルト: 0 (最初のヒット)

必須: いいえ

構文: 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 boost=N EXPRESSION EXPRESSION ... EXPRESSIONn)

指定した式がすべて一致する場合にのみドキュメントを含めます。(ブール型 AND 演算子。) 式には、構造化クエリ演算子または単純な検索文字列を含めることができます。検索文字列は一重引用符で囲む必要があります。検索するフィールドのいずれかで指定された用語を含むドキュメントに一致するためには、(and 'star' 'wars') のようにそれぞれの用語を別の式として指定する必要があります。(and 'star wars') と指定した場合、star と wars が同じフィールド内にある場合のみ一致とみなされます。

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

例:

(and title:'star' actors:'Harrison Ford' year:{,2000])

構文: matchall

ドメイン内のすべてのドキュメントが一致します。デフォルトでは、最初の 10 件を返します。size および start パラメータを使用して、結果をページ分割します。

構文: (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 boost=N EXPRESSION)

指定された式に一致するドキュメントを除外します。(ブール NOT 演算子)。式には、構造化クエリ演算子または単純な検索文字列を含めることができます。検索文字列は一重引用符で囲む必要があります。

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

例:

(not (or actors:'Harrison Ford' year:{,2010]))

構文: (or boost=N EXPRESSION1 EXPRESSION2 ... EXPRESSIONn)

指定した式のいずれかが一致する場合にドキュメントを含めます。(ブール OR 演算子)。式には、構造化クエリ演算子または単純な検索文字列を含めることができます。検索文字列は一重引用符で囲む必要があります。

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

例:

(or actors:'Alec Guinness' actors:'Harrison Ford' actors:'James Earl Jones')

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

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

例:

(prefix field=title 'star')

構文: (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 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: 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)

構文: +TERM

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

例: +star

構文: \CHAR

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

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

構文: TERM~N

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

例: stor~1

構文: "PHRASE"~N

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

例: "star wars"~4

構文: -TERM

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

例: star -wars

構文: |TERM

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

例: star |wars

構文: "PHRASE"

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

例: "star wars"

構文: (...)

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

例: +(war|trek)+star

構文: CHARS*

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

例: sta*

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

有効な値: application/json または application/xml

デフォルト: application/json

レスポンスの本文のバイト長。

リソース ID (rid) およびリクエストの処理にかかった時間 (time-ms) を含みます。

一致するドキュメントの数 (found)、レスポンスに含まれる最初のドキュメントのインデックス (start)、各ヒット項目のドキュメント ID とデータをリストした配列 (hit) を含みます。

検索結果を含みます。リクエストの処理中に発生したエラーは、info 要素のメッセージとして返されます。

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

必須: はい

候補を入手する文字列。

タイプ: 文字列

必須: はい

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

タイプ: 文字列

必須: はい

返される候補の最大数。

タイプ: 正の整数

デフォルト: 10

必須: いいえ

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

タイプ: 文字列

有効な値: json|xml

デフォルト: json

必須: いいえ

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

エラーコードです。

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