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

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

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

• 設定 API — 検索ドメインを設定および管理します。

• ドキュメントサービス API — 検索するデータを送信します。

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

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

重要

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

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

たとえば、次のリクエストは AWS CLI を使用して wolverine の単純なテキスト検索を送信し、一致ドキュメントの 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 形式で応答を返します。format パラメータを指定することで、結果を XML 形式で取得することができますレスポンス形式の設定は、成功したリクエストのレスポンスのみに影響します。エラーレスポンスの形式は、エラーの発生元によって異なります。検索サービスによって返されるエラーは、常に 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 へのアクセスの制御方法については、「アクセスポリシーの設定」を参照してください。リクエスト署名の詳細については、「AWS API リクエストの署名」を参照してください。

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

たとえば、次のリクエストは search-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch.amazonaws.com ドメインに構造化クエリを送信し、title フィールドのコンテンツを取得します。

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 エラーが発生します。

検索

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

検索構文

GET /2013-01-01/search

検索リクエストヘッダー

HOST

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

必須: はい

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

cursor

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

最初のカーソルを取得するには、最初のリクエストで 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 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 が関連性スコアを計算する際に各フィールドの相対重要度を制御できます。フィールドの重みを指定するには、フィールド名の後にキャレット記号（^）を付けて重みを指定します。たとえば、description フィールドに対する title フィールドの重要性を高めるには、fields: ['title^5','description'] と指定します。有効な値: 設定されたフィールド名と、オプションの正の数値。デフォルト: 静的に設定されたすべての text フィールドと text-array フィールド。デフォルトでは、動的フィールドと 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-array フィールドの単純な検索を実行します。デフォルトでは、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 パラメータのどちらかを指定できます。両者は相互に排他的です。詳細については、「結果をページ分割する」を参照してください。

タイプ: 正の整数

デフォルト: 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 CloudSearch は InvalidQueryString エラーを返します。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（協定世界時間）で指定されます。たとえば、1970 年 8 月 23 日午後 5 時は、UTC 形式では 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 オプションを指定することで、デフォルトで検索するフィールドを指定できます。

距離値は正の整数である必要があります。たとえば、plot フィールドに teenage と vampire が 10 単語以内の距離で出現するドキュメントをすべて見つけるには、距離値を 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-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 以下のすべてのドキュメントに一致します。

boost 値は、検索クエリのこのパートの重要性を他のパートに対して相対的に高くする正の数値です。

例:

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

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

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

日付と時刻は、IETF RFC3339: yyyy-mm-ddTHH:mm:ss.SSSZに従って、UTC（協定世界時間）で指定されます。たとえば、1970 年 8 月 23 日午後 5 時は、UTC 形式では 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 以下であるすべてのドキュメントに一致します。

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

日付と時刻は、IETF RFC3339: yyyy-mm-ddTHH:mm:ss.SSSZに従って、UTC（協定世界時間）で指定されます。たとえば、1970 年 8 月 23 日午後 5 時は、UTC 形式では 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 パラメータを使用できます。詳細については、「結果をページ分割する」を参照してください。

次の例は一般的な 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）に送信します。提案サービスへのアクセスを制御する方法については、「アクセスポリシーの設定」を参照してください。

すべての候補リクエストで 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 リクエストを送信することができます。ウェブブラウザにリクエスト URL を直接入力する、cURL を使用してリクエストを送信する、またはお気に入りの HTTP ライブラリを使用して HTTP 呼び出しを生成することができます。また、Amazon CloudSearch コンソールで検索テスターを使用して候補を取得することもできます。詳細については、「検索テスターによる検索」を参照してください。

重要

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

デフォルトでは、Amazon CloudSearch は JSON 形式で応答を返します。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

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