注: Java 8 は、2024 年 1 月 31 日にサポートが終了しました。既存の Java 8 アプリケーションは引き続き実行され、トラフィックを受信します。ただし、サポート終了日を過ぎると、ランタイムを使用するアプリケーションの再デプロイが App Engine によってブロックされることがあります。サポートされている最新バージョンの Java に移行することをおすすめします。

クエリオプションと並べ替えオプション

クエリ文字列だけを使用して search() メソッドを呼び出すと、デフォルトのクエリオプションに応じて結果が返されます。

ドキュメントはランクの降順に並べ替えられて返されます
ドキュメントは一度に 20 個のグループで返されます
取得されるドキュメントには、そのドキュメントのオリジナルのフィールドがすべて含まれています

デフォルトのオプションを変更するには、Query クラスのインスタンスを search() の引数として使用します。

Query クラスを使用して、同時に返されるドキュメントの数を指定できます。また、取得するドキュメントのコンテンツをカスタマイズすることもできます。ドキュメントの識別子のみをリクエストすることも、フィールドのサブセットのみを含むドキュメントをリクエストすることもできます。さらに、スニペット（一致文字列の前後のテキストを示すテキストフィールドの断片）やフィールド式（ドキュメント内の別のフィールドから導出される値を含むフィールド）といったカスタムフィールドを、取得したドキュメント内に作成することもできます。

クエリオプションとは別に、Query クラスには SortOptions クラスのインスタンスを含めることもできます。並べ替えオプションを使用すると、並べ替え順序の変更や、複数のキーに基づく結果の並べ替えが可能になります。

Query クラスを使用した検索

Query クラスのインスタンスを使用して検索するときには、クラスのインスタンスを作成するための複数の手順が必要になります。一般的な手順は次のとおりです。

クエリ文字列を作成します。
必要に応じて SortOptions を作成します。
QueryOptions を作成します。
クエリ文字列と QueryOptions（省略可）を含む Query オブジェクトを作成します。
Query オブジェクトの検索メソッドを呼び出します。

各種クエリオプションと並べ替えオプションは、次の例に示すように、QueryOptions.Builder クラスと SortOptions.Builder クラスのインスタンスの setter メソッドを呼び出して指定します。

try {
  // Build the SortOptions with 2 sort keys
  SortOptions sortOptions =
      SortOptions.newBuilder()
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("price")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValueNumeric(0))
          .addSortExpression(
              SortExpression.newBuilder()
                  .setExpression("brand")
                  .setDirection(SortExpression.SortDirection.DESCENDING)
                  .setDefaultValue(""))
          .setLimit(1000)
          .build();

  // Build the QueryOptions
  QueryOptions options =
      QueryOptions.newBuilder()
          .setLimit(25)
          .setFieldsToReturn("model", "price", "description")
          .setSortOptions(sortOptions)
          .build();

  // A query string
  String queryString = "product: coffee roaster AND price < 500";

  //  Build the Query and run the search
  Query query = Query.newBuilder().setOptions(options).build(queryString);
  IndexSpec indexSpec = IndexSpec.newBuilder().setName(indexName).build();
  Index index = SearchServiceFactory.getSearchService().getIndex(indexSpec);
  Results<ScoredDocument> result = index.search(query);
  return result;
} catch (SearchException e) {
  // handle exception...
}

QueryOptions

QueryOptions.Builder を使用して、クエリオプションを設定する必要があります。ここに示すプロパティに、直接アクセスすることはできません。

これらのプロパティは、返される結果の数と順序を制御します。offset オプションと cursor オプションは相互に排他的であり、ページ分割をサポートしています。これらのオプションにより、結果で返すドキュメントを選択します。

プロパティ	説明	デフォルト	最大値
`Limit`	結果で返されるドキュメントの最大件数。	20 件	1000
`NumberFoundAccuracy`	このプロパティによって、`Results.getNumberFound()` から返される結果の精度が決まります。このプロパティでは実際にカウントされる一致数の上限を設定します。この上限に達した時点で検索が停止します。インデックスの一致数が上限以下の場合は、正確な件数が返されます。それ以外の場合は、検出された一致数とインデックスのサイズと構造に基づいて推定された件数になります。このプロパティに高い値を設定すると、検索オペレーションが複雑になることがあり、タイムアウトが発生する可能性があります。	指定しない場合、精度は `Limit` と同じ値に設定されます。	25,000
`Offset`	結果で返す最初のドキュメントのオフセット。	0: 一致するすべて（上限数以下）のドキュメントが結果に含まれます。	1,000 件
`Cursor`	カーソルは、並べ替えられた順序でドキュメントのグループを取得するためにオフセットの代わりとして使用できます。カーソルは、連続するクエリに受け渡しされるときに更新されるため、前の検索の結果の最後から新しい検索を実行できます。カーソルとオフセットについての説明は、結果の処理ページをご覧ください。	NULL: 一致するすべて（上限数以下）のドキュメントが結果に含まれます。	-
`SortOptions`	`SortOptions` オブジェクトは、検索結果の順序を制御する場合に設定します。`SortOptions` のインスタンスには、後述する独自のプロパティのセットがあります。	NULL: ドキュメントランクの降順に並べ替えます。	-

次に示すプロパティでは、結果に示されるドキュメントのフィールドを制御します。

プロパティ	説明	デフォルト
`ReturningIdsOnly`	`True` または `False` に設定します。`True` の場合、結果で返されるドキュメントには ID のみが含まれ、フィールドは含まれません。	`False`（すべてのフィールドを返します）。
`FieldsToReturn`	結果に含めるドキュメントのフィールドを指定します。100 個以下のフィールドを指定できます。	ドキュメントのすべて（100 個以下）のフィールドを返します。
`ExpressionsToReturn`	検索結果で返される各ドキュメントに追加する、計算されたフィールドを表すフィールド式。これらのフィールドは、ドキュメントの expressions プロパティに追加されます。フィールド値は、1 つ以上のドキュメントのフィールドを含む式の記述によって指定します。	なし
`FieldsToSnippet`	テキストフィールド名のリスト。フィールドごとにスニペットが生成されます。これは、検索結果に含まれるドキュメントの expressions プロパティに追加される、計算されたフィールドです。snippet フィールドには、ソースフィールドと同じ名前が付けられます。このオプションは 2 つの引数のみを指定した `snippet("query-string", field-name)` を暗黙的に使用します。これは、結果を取得する検索に使用したクエリ文字列に基づいて、最大でも 1 つの一致文字列でスニペットを作成します。また、明示的に snippet 関数を呼び出すフィールド式を追加すると、`ExpressionsToReturn` オプションでカスタマイズされたスニペットも作成できます。	なし

SortOptions

検索結果の順序とスコアは、SortOptions のプロパティで制御します。SortOptions.Builder を使用して、並べ替えオプションを設定する必要があります。ここに示すプロパティに、直接アクセスすることはできません。

検索結果の順序とスコアは、SortOptions のプロパティで制御します。

プロパティ	説明	デフォルト
`SortExpressions`	ドキュメントの多次元の並べ替えを表す `SortExpressions` のリスト。	なし
`MatchScorer`	オプションの `MatchScorer` オブジェクト。このオブジェクトが存在すると、検索キーワードの出現頻度に応じて、ドキュメントにスコアが付けられるようになります。このスコアは、`_score` フィールドとして利用できます。ドキュメントのスコア付けは、課金対象のオペレーションという意味でも、実行時間という意味でもコスト高になり、検索が遅くなることもあります。スコア付けは慎重に使用してください。	なし
`Limit`	スコア付けや並べ替えの対象にするオブジェクトの最大数。10,000 以下にしてください。	1,000

複数のキーに基づく並べ替え

検索結果は複数の並べ替えキーに基づいて順序付けできます。それぞれのキーは、単純なフィールド名、または複数のフィールドから計算される値になります。「式（expression）」という用語は、並べ替えオプションに関して複数の意味で使用されるので注意してください。たとえば、SortOption 自体に expressions 属性があります。この属性は、並べ替えキーに対応する SortExpression オブジェクトのリストです。最終的には、それぞれの SortExpression オブジェクトに含まれる expression 属性によって、並べ替えキーの値の計算方法が指定されます。この式は、次のセクションで示されているルールに従って作成されます。

また、SortExpression では、並べ替えの方向と、ドキュメントに対して式が計算できない場合に使用するデフォルトのキー値も定義します。プロパティの完全なリストを次に示します。

プロパティ	説明	デフォルト
`Expression`	一致するドキュメントごとに結果を並べ替える際に評価される式。	なし
`Direction`	検索結果の並べ替えの方向。`ASCENDING`（昇順）または `DESCENDING`（降順）のいずれかになります。	`DESCENDING`
`DefaultValue` `DefaultValueDate` `DefaultValueNumber`	フィールドが存在せず、ドキュメントに関する計算ができない場合の、式のデフォルト値。テキストの並べ替えの場合、テキスト値を指定する必要があります。数字の並べ替えの場合は、数値を指定してください。	なし

複数の値を持つフィールドに基づく並べ替え

特定のタイプの値を複数持つフィールドに基づく並べ替えを実行するときには、そのフィールドに割り当てられた最初の値のみが使用されます。たとえば、2 つのドキュメント DocA と DocB の両方に「color」という名前のテキストフィールドがあるとします。DocA の「color」フィールドに 2 つの値が（red、blue）の順に割り当てられていて、DocB には 2 つの値が（green、red）の順に割り当てられています。テキストフィールド「color」を指定した並べ替えを実行すると、DocA は値「red」で並べ替えられ、DocB は値「green」で並べ替えられます。並べ替えには、その他のフィールド値は使用されません。

並べ替えの適否

並べ替えオプションの指定を省略すると、検索結果は自動的にランクの降順に並べ替えられて返されます。この場合は、返されるドキュメント数に上限はありません。並べ替えオプションを指定すると、一致するドキュメントがすべて選択されてから並べ替えが実行されます。並べ替えのサイズを制御する明示的なプロパティ「SortOptions.limit」があります。10,000 件を超えるドキュメントは並べ替えできません。デフォルトは、1,000 件です。「SortOptions.limit」で指定した数よりも多くの一致するドキュメントが存在する場合、検索では、制限された数のドキュメントが取得され、並べ替えられて、返されます。並べ替えの対象のドキュメントは一致するすべてのドキュメントのリストから選択されます。このリストは、ランクの降順に並べられています。クエリによっては、並べ替え可能な数を超えるドキュメントが選択されることがあります。並べ替えオプションを使用している場合に、一致するすべてのドキュメントを取得することが重要な場合、並べ替え可能な数よりも多くのドキュメントがクエリで返されるようになっていないかを確認する必要があります。

式の記述

式は、QueryOptions で設定されるフィールド式と、SortOptions で設定される並べ替え式の定義に使用されます。これらの式は、次に示すように文字列として記述します。

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

数値のフィールドを含む式には、算術演算子（+、-、*、/）と、後述するリストに示されている組み込み数値関数を使用できます。地理的位置のフィールドを含む式には、geopoint 関数と distance 関数を使用できます。テキストのフィールドと HTML のフィールドの式には、snippet 関数を使用できます。

式には、次に示す特別な用語を含めることもできます。

用語	説明
`_rank`	ドキュメントの rank プロパティ。フィールド式と並べ替え式で使用できます。
`_score`	`SortOptions` に `MatchScorer` を含める場合にドキュメントに割り当てられるスコア。この用語は、並べ替え式でのみ使用できます。フィールド式では使用できません。

数値関数

FieldExpressions と SortExpressions の数値を定義する式には、次に示す組み込み関数を使用できます。引数は、数値またはフィールド名にするか、数値とフィールド名を使用する式にする必要があります。

関数	説明	例
`max`	引数のうち、最大の引数を返します。	`max(recommended_retail_price, discount_price, wholesale_price)`
`min`	引数のうち、最小の引数を返します。	`min(height, width, length)`
`log`	自然対数を返します。	`log(x)`
`abs`	絶対値を返します。	`abs(x)`
`pow`	2 つの引数を受け取ります。pow(x, y) を呼び出すと、x の y 乗の値が計算されます。	`pow(x, 2)`
`count`	引数としてフィールド名を受け取ります。その名前の付いたドキュメントに含まれるフィールドの数を返します。ドキュメントには、同じ名前を持つ異なるタイプのフィールドが複数含まれていることがある点に注意してください。注: `count` は `FieldExpressions` でのみ使用できます。`SortExpressions` には表示できません。	`count(user)`

地理的位置関数

次に示す関数は、地理的位置型のフィールドが含まれる式に使用できます。

関数	説明	例
`geopoint`	緯度と経度を指定して地理的位置を定義します。	`geopoint(-31.3, 151.4)`
`distance`	2 つの地理的位置の距離をメートル単位で計算します。2 つの引数は、地理的位置型のフィールド名または geopoint 関数の呼び出しになります。ただし、フィールド名にすることができる引数は 1 つのみです。	`distance(geopoint(23, 134), store_location)`

スニペット

スニペットとはクエリ文字列に一致するテキストフィールドと、その前後のテキストを含むテキストフィールドの断片です。スニペットは、次に示すように snippet 関数を呼び出して作成します。

snippet(query, body, [max_chars])

query: フィールド内で検索するテキストを指定する、引用符で囲まれたクエリ文字列。
body: テキストフィールド、HTML フィールド、Atom フィールドの名前。
max_chars: スニペットで返す最大文字数。この引数は省略可能です。デフォルトは 160 文字です。

この関数は、HTML 文字列を返します。この文字列に、body フィールドの値のスニペットが含まれています。クエリと一致したテキストは太字体になっています。