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

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

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

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

Amazon CloudSearch を操作するために使用するその他の API は次のとおりです。

Amazon CloudSearch での検索リクエストの送信

検索リクエストを送信するには、AWS SDK または AWS CLI を使用することをお勧めします。SDK と AWS CLI は、リクエストの署名を処理し、すべての Amazon CloudSearch アクションを簡単に実行できるようにします。Amazon CloudSearch コンソールの検索テスターを使用して、データの検索、結果の参照、生成されたリクエスト URL、JSON および XML レスポンスの表示を行うこともできます。詳細については、「検索テスターによる検索」を参照してください。

重要

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

  • IP アドレスDO変更: ドメインの IP アドレスできるは時間の経過とともに変化するので、コンソールに示されているようにエンドポイントをキャッシュし、aws cloudsearch describe-domainsコマンドを使用したり、IP アドレスを使用したりします。また、エンドポイント DNS を IP アドレスに再解決する必要があります。詳細については、「」を参照してください。DNS 名参照用の JVM TTL の設定。

たとえば、次のリクエストは、wolverineを呼びAWS、一致するドキュメントの ID だけを返します。 

aws cloudsearchdomain --endpoint-url http://search-movies-y6gelr4lv3jeu4rvoelunxsl2e.us-east-1.cloudsearch.amazonaws.com search --search-query wolverine  --return _no_fields
{
    "status": {
        "rid": "/rnE+e4oCAqfEEs=", 
        "time-ms": 6
    }, 
    "hits": {
        "found": 3, 
        "hit": [
            {
                "id": "tt1430132"
            }, 
            {
                "id": "tt0458525"
            }, 
            {
                "id": "tt1877832"
            }
        ], 
        "start": 0
    }
}

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

注記

AWS SDK はフィールドを配列として返します。単一値フィールドは、次のような 1 つの要素を持つ配列として返されます。

"fields": {
  "plot": ["Katniss Everdeen reluctantly becomes the symbol of a mass rebellion against the autocratic Capitol."]
}

開発およびテストの目的で、ドメインの検索サービスへの匿名アクセスを許可し、署名されていない HTTP GET または POST リクエストをドメインの検索エンドポイントに直接送信できます。実稼働環境では、ドメインへのアクセスを特定の IAM ユーザー、グループ、またはロールに制限し、AWS SDK または AWS CLI を使用して署名付きリクエストを送信します。Amazon CloudSearch のアクセスの制御については、「」を参照してください。configure access policies。リクエストの署名の詳細については、「」を参照してください。AWS API リクエストの署名。

HTTP リクエストをドメインの検索エンドポイントに直接送信する任意の方法を使用できます。Web ブラウザに直接リクエスト URL を入力するか、cURL を使用してリクエストを送信するか、お気に入り HTTP ライブラリを使用して HTTP 呼び出しを生成できます。検索条件を指定するには、検索の制約と応答で取得する内容を指定するクエリ文字列を指定します。クエリ文字列は、URL でエンコードされている必要があります。GET 経由で送信される検索リクエストの最大サイズは、HTTP メソッド、URI、プロトコルのバージョンを含め 8190 バイトです。HTTP POST を使用して大きなリクエストを送信できますが、大規模で複雑なリクエストの処理に時間がかかり、タイムアウトする可能性が高くなります。詳細については、「Amazon CloudSearch での検索リクエストのパフォーマンスのチューニング」を参照してください。

たとえば、次のリクエストは、構造化クエリをsearch-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch.amazonaws.comドメインの内容を取得し、titlefield。 

http://search-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch.
amazonaws.com/2013-01-01/search?q=(and+(term+field%3Dtitle+'star')
(term+field%3Dyear+1977))&q.parser=structured&return=title
重要

クエリ文字列の特殊文字は、URL でエンコードする必要があります。たとえば、エンコードする必要があります、=演算子を、構造化クエリの%3D: (term+field%3Dtitle+'star')。検索リクエストを送信するときに特殊文字をエンコードしないと、InvalidQueryStringエラー。

Search

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

  • 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|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-arrayfields。デフォルトでは、動的フィールドと literal フィールドは検索されません。有効なパサーサー: simple、structured、lucene, およびdismax。

  • operators-simple クエリパーサーで無効にする演算子または特殊文字の配列。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。もしq.parserが指定されていない場合、Amazon CloudSearch はsimpleクエリパーサー。

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

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

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

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

タイプ: 文字列

デフォルト:simple

必須 いいえ

return

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

タイプ: 文字列

必須 いいえ

size

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

タイプ: 正の整数

デフォルト: 10

必須 いいえ

sort

検索結果をソートするときに使用するフィールドまたはカスタム式のカンマ区切りリスト。各フィールドに対してソート方向（desc または asc）を指定する必要があります。例: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'). Amazon CloudSearch はInvalidQueryStringエラーは、特殊文字が URL エンコードされていない場合に発生します。URL エンコードの詳細については、W3C の「HTML URL エンコードリファレンス」を参照してください。

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

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

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

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

FIELD

構文: FIELD: 'STRING'|value

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

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

日付と時刻は、UTC（協定世界時）で指定されます。IETF RFC3339: yyyy-mm-ddTHH:mm:ss.SSSZ。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 が同じフィールド内にある場合のみ一致とみなされます。

boost 値は正の数値で、検索クエリのこの部分の重要度を他の部分よりも高くします。

例: 

(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オプション。

距離値は正の整数である必要があります。たとえば、すべてのドキュメントを検索するには十代の10単語以内に発生する吸血()plotフィールドで、距離の値として 10 を指定します。(near field=plot distance=10 'teenage vampire')。

boost 値は正の数値で、検索クエリのこの部分の重要度を他の部分よりも高くします。

例: 

(near field=plot distance=10 'teenage vampire')
not

構文: (not boost=N EXPRESSION)

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

boost 値は正の数値で、検索クエリのこの部分の重要度を他の部分よりも高くします。

例: 

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

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

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

boost 値は正の数値で、検索クエリのこの部分の重要度を他の部分よりも高くします。

例: 

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

構文: (phrase field=FIELD boost=N 'STRING')

検索しますtextまたはtext-arrayfield。省略すると、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 以下のすべてのドキュメントに一致します。

boost 値は正の数値で、検索クエリのこの部分の重要度を他の部分よりも高くします。

例: 

(phrase field=plot 'teenage girl')
prefix

構文: (prefix field=FIELD boost=N 'STRING')

検索しますtext、text-array、literal, またはliteral-arrayフィールドには、指定したプレフィックスとその後に 0 またはいくつかの文字が含まれます。省略すると、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 以下のすべてのドキュメントに一致します。

boost 値は正の数値で、検索クエリのこの部分の重要度を他の部分よりも高くします。

注記

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

例: 

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

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

日付と時刻は、UTC（協定世界時）で指定されます。IETF RFC3339: yyyy-mm-ddTHH:mm:ss.SSSZ。UTC 形式で、たとえば、1970 年 8 月 23 日午後 5 時は、1970-08-23T17:00:00Z。UTC で時刻を指定する場合は、小数秒を指定することもできます。例:1967-01-31T23:20:50.650Z.

boost 値は正の数値で、検索クエリのこの部分の重要度を他の部分よりも高くします。

例: 

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

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

日付と時刻は、UTC（協定世界時）で指定されます。IETF RFC3339: yyyy-mm-ddTHH:mm:ss.SSSZ。UTC 形式で、たとえば、1970 年 8 月 23 日午後 5 時は、1970-08-23T17:00:00Z。UTC で時刻を指定する場合は、小数秒を指定することもできます。例:1967-01-31T23:20:50.650Z.

boost 値は正の数値で、検索クエリのこの部分の重要度を他の部分よりも高くします。

例: 

(term field=title 'star')
(term field=year 2000)

単純検索の構文

Amazon CloudSearch の単純検索の構文は、検索条件を定義するときに使用します。simpleクエリパーサー。simple クエリパーサーは、q.parser パラメータを指定しない場合にデフォルトで使用されます。

simple クエリパーサーは、個々の用語またはフレーズを検索するときに使用します。デフォルトでは、静的に設定されたすべての text および text-array フィールドが検索されます。デフォルトでは、動的フィールドと literal フィールドは検索されません。q.options パラメータを使用して、検索するフィールドの指定、検索文字列で個々の用語を組み合わせるときに使用するデフォルト演算子の変更、または simple パーサー演算子の無効化を実行できます（and、escape、fuzzy、near、not、or’phrase、precedence、prefix、whitespace）。

simple クエリパーサーの使用法の詳細については、「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 バージョンを指定する必要があり、そのバージョンはドメインを作成したときに指定されたバージョンと一致している必要があります。

たとえば、次のリクエストは、title というサジェスタを使用して search-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch.amazonaws.com ドメインからクエリ文字列 oce の候補を取得します。 

http://search-imdb-hd6ebyouhw2lczkueyuqksnuzu.us-west-2.cloudsearch.amazonaws.com/2013-01-01/suggest -d"q=oce&suggester=suggest_title"

GET リクエストをドメインの検索エンドポイントに送信する任意の方法を使用できます。Web ブラウザに直接リクエスト URL を入力するか、cURL を使用してリクエストを送信するか、お気に入り HTTP ライブラリを使用して HTTP 呼び出しを生成できます。また、Amazon CloudSearch コンソールで検索テスターを使用して、候補を取得することもできます。詳細については、「検索テスターによる検索」を参照してください。

重要

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

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

Suggest

候補リクエスト

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

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