クエリ文字列だけを使用して Index.Search メソッドを呼び出すと、デフォルトのクエリ オプションに応じて結果が返されます。
- ドキュメントはランクの降順に並べ替えられて返されます
- ドキュメントは一度に 20 個のグループで返されます
- 取得されるドキュメントには、そのドキュメントのオリジナルのフィールドがすべて含まれています
デフォルトのオプションを変更するには、SearchOptions 構造体のインスタンスを Search の引数として使用します。
SearchOptions 構造体を使用すると、同時に返されるドキュメント数を指定できます。また、取得するドキュメントのコンテンツをカスタマイズすることもできます。ドキュメントの識別子のみをリクエストすることも、フィールドのサブセットのみを含むドキュメントをリクエストすることもできます。さらに、フィールド式（ドキュメント内の別のフィールドから導出される値を含むフィールド）を使用して、取得したドキュメントにカスタム フィールドを作成することもできます。
クエリのオプションとは別に、SearchOptions 構造体には SortOptions 構造体のインスタンスを含めることもできます。並べ替えオプションを使用すると、並べ替え順序の変更や、複数のキーに基づく結果の並べ替えが可能になります。
SearchOptions
これらのプロパティは、返される結果の数と順序を制御します。offset オプションと cursor オプションは相互に排他的であり、ページ分割をサポートしています。これらのオプションにより、結果で返すドキュメントを選択します。
| プロパティ | 説明 | デフォルト | 最大値 |
|---|---|---|---|
Limit |
結果で返されるドキュメントの最大件数。 | 20 件 | 1000 |
Offset |
結果で返される最初のドキュメントのオフセット。 | 0: 一致するすべて（上限数以下）のドキュメントが結果に含まれます。 | 1,000 件 |
Cursor |
カーソルは、並べ替えられた順序でドキュメントのグループを取得するためにオフセットの代わりとして使用できます。カーソルは、連続するクエリに受け渡しされるときに更新されるため、前の検索の結果の最後から新しい検索を実行できます。カーソルとオフセットについての説明は、Go search リファレンス ページをご覧ください。 | NULL: 一致するすべて（上限数以下）のドキュメントが結果に含まれます。 | - |
Sort |
SortOptions 構造体は、検索結果の順序を制御する場合に設定します。SortOptions のインスタンスには、後述する独自のプロパティのセットがあります。 |
NULL: ドキュメント ランクの降順に並べ替えます。 | - |
次に示すプロパティでは、結果に示されるドキュメントのフィールドを制御します。
| プロパティ | 説明 | デフォルト |
|---|---|---|
IDsOnly |
true または false に設定します。true の場合、結果で返されるドキュメントには ID のみが含まれ、フィールドは含まれません。 |
false（すべてのフィールドを返します）。 |
Fields |
結果に含めるドキュメントのフィールドを指定します。100 個以下のフィールドを指定できます。 | ドキュメントのすべて（100 個以下）のフィールドを返します。 |
Expressions |
検索結果で返される各ドキュメントに追加する、計算されたフィールドを表すフィールド式。これらのフィールドは、ドキュメントの expressions プロパティに追加されます。フィールド値は、1 つ以上のドキュメントのフィールドを含む式の記述によって指定します。 | なし |
SortOptions
検索結果の順序とスコアは、SortOptions のプロパティで制御します。
| プロパティ | 説明 | デフォルト |
|---|---|---|
Expressions |
ドキュメントの多次元の並べ替えを表す SortExpressions のスライス。 |
なし |
Scorer |
オプションの Scorer。このオブジェクトが存在すると、検索キーワードの出現頻度に応じて、ドキュメントにスコアが付けられるようになります。このスコアは、_score フィールドとして利用できます。ドキュメントのスコア付けは、課金対象のオペレーションという意味でも、実行時間という意味でもコスト高になり、検索が遅くなることもあります。スコア付けは慎重に使用してください。 |
なし |
Limit |
スコア付けや並べ替えの対象にするオブジェクトの最大数。10,000 以下にしてください。 | 1,000 |
複数のキーに基づく並べ替え
検索結果は複数の並べ替えキーに基づいて順序付けできます。それぞれのキーは、単純なフィールド名、または複数のフィールドから計算される値になります。この式は、次のセクションで示されているルールに従って作成されます。
また、SortExpression では、並べ替えの方向と、ドキュメントに対して式が計算できない場合に使用するデフォルトのキー値も定義します。プロパティの完全なリストを次に示します。
| プロパティ | 説明 | デフォルト |
|---|---|---|
Expr |
一致するドキュメントごとに結果を並べ替える際に評価される式。 | なし |
Reverse |
true の場合、検索結果の順番が逆になります。デフォルトの昇順ではなく、降順で表示されます。 |
false |
Default |
フィールドが存在せず、ドキュメントに関する計算ができない場合の、式のデフォルト値。テキストの並べ替えの場合、テキスト値を指定する必要があります。数字の並べ替えの場合は、数値を指定してください。 | なし |
複数の値を持つフィールドに基づく並べ替え
特定のタイプの値を複数持つフィールドに基づく並べ替えを実行するときには、そのフィールドに割り当てられた最初の値のみが使用されます。たとえば、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 で指定した数よりも多くの一致するドキュメントが存在する場合、検索では、制限された数のドキュメントが取得され、並べ替えられて、返されます。並べ替えの対象のドキュメントは一致するすべてのドキュメントのリストから選択されます。このリストは、ランクの降順に並べられています。クエリによっては、並べ替え可能な数を超えるドキュメントが選択されることがあります。並べ替えオプションを使用している場合に、一致するすべてのドキュメントを取得することが重要な場合、並べ替え可能な数よりも多くのドキュメントがクエリで返されるようになっていないかを確認する必要があります。
式の記述
式は、SearchOptions で設定されるフィールド式と、SortOptions で設定される並べ替え式の定義に使用されます。これらの式は、次に示すように文字列として記述します。
"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"
数値のフィールドを含む式には、算術演算子（+、-、*、/）と、後述するリストに示されている組み込み数値関数を使用できます。地理的位置のフィールドを含む式には、geopoint 関数と distance 関数を使用できます。テキストのフィールドと HTML のフィールドの式には、snippet 関数を使用できます。
式には、次に示す特別な用語を含めることもできます。
| 用語 | 説明 |
|---|---|
_rank |
ドキュメントの rank プロパティ。フィールド式と並べ替え式で使用できます。 |
_score |
SortOptions に Scorer を含める場合にドキュメントに割り当てられるスコア。この用語は、並べ替え式でのみ使用できます。フィールド式では使用できません。 |
数値関数
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 フィールドの値のスニペットが含まれています。クエリと一致したテキストは太字体になっています。