查詢和排序選項

若只使用查詢字串呼叫 Index.Search 方法，系統會根據預設的查詢選項傳回結果：

  • 以遞減順序排序傳回文件
  • 一次以 20 件為一組傳回文件
  • 擷取的文件包含其原始欄位

您可以使用 SearchOptions 結構體的例項做為 Search 的引數，以變更這些選項。

SearchOptions 結構可讓您指定一次要傳回多少文件，也可以讓您自訂所擷取文件的內容。您可以要求只傳回文件 ID，或要求文件只包含欄位子集。您也可以使用欄位運算式 (欄位值衍生自文件中的其他欄位)，在擷取的文件中建立自訂欄位。

除了查詢選項外，「SearchOptions」結構也包括 SortOptions 結構的例項。使用排序選項可以變更排序順序，也可以依多個索引鍵排序結果。

SearchOptions

這些屬性控制傳回結果的數量及順序。偏移選項和游標選項 (兩者互斥) 支援分頁。用於指定結果中要傳回哪些選定的文件。

屬性 說明 預設 上限
Limit 結果中傳回的文件數量上限。 20 1000
Offset 要傳回的第一份文件在結果中的位移量。 0。結果將包含所有符合的文件 (不超過上限) 1,000
Cursor 可使用游標取代偏移量，用於擷取一組組經過排序的文件。將游標傳入及傳出連續查詢時會更新游標，每次重新查詢時，都會從上一頁的結尾處往下接著進行。關於游標和位移的資訊，Go 搜尋參考資料頁面有相關討論。 空值。結果將包含所有符合的文件 (不超過上限) -
Sort 設定 SortOptions 結構體，用於控制搜尋結果的排序方式。SortOptions 的例項自有一組屬性，如下所述。 空值。以遞減順序排序文件。 -

這些屬性控制結果中顯示的文件欄位。

屬性 說明 預設
IDsOnly 設為 true 或 false。設為 true 時，結果中傳回的文件只包含 ID，不包含欄位。 false (傳回所有欄位)。
Fields 指定要在結果中包含哪些文件欄位。最多可指定 100 個欄位。 傳回所有文件欄位 (最多 100 個欄位)。
Expressions 欄位運算式，說明要將哪些經過運算的欄位新增至搜尋結果傳回的每份文件。這些欄位會新增至文件的運算式屬性。若要指定欄位值，需撰寫運算式，其中可能包含一或多個文件欄位。 無

SortOptions

SortOptions 的屬性可控制搜尋結果的排序和計分。

屬性 說明 預設
Expressions SortExpressions 的一部分，代表文件的多維度排序。 無
Scorer 選用的 Scorer。此屬性存在時，將會依據搜尋字詞的頻率，對文件進行計分。分數會在列在 _score 欄位中。對文件計分可能所費不貲，此為計費作業且需花費執行時間，並可能拖慢您的搜尋速度。請謹慎使用計分功能。 無
Limit 要計分和/或排序之物件的數量上限。不可超過 10,000。 1,000

依多個索引鍵排序

您可以依多個排序索引鍵排序搜尋結果。每個索引鍵可以是單純的欄位名稱，也可以是以多個欄位運算得出的值。這個運算式會根據下一節中的規則進行建構。

SortExpression 也會定義排序的方向，亦能在系統無法對某份文件計算運算式時，做為預設鍵值使用。以下列出所有的屬性：

屬性 說明 預設
Expr 排序每份符合文件的結果時，所要評估的運算式。 無
Reverse 如果 true 反轉搜尋結果的排序順序，則會以遞增 (而非預設的遞減) 順序顯示。 false
Default 運算式預設值，文件中若沒有出現此欄位，即無法計算。必須指定文字值才能排序文字。要排序數字則須指定數值。 無

依多值欄位排序

依特定類型的多值欄位排序時，只會使用指派至該欄位的第一個值。舉例來說，假設 DocA 和 DocB 這兩份文件都有一個名稱為「color」的文字欄位。系統會將兩個值按照順序 (red、blue) 指派給 DocA 的「color」欄位，並將兩個值按照順序 (green、red) 指派給 DocB。當您指定依文字欄位「color」執行排序時，系統會依「red」這個值排序 DocA，並依「green」這個值排序 DocB。其他欄位值不會用於排序。

排序與否

如果您沒有指定任何排序選項，系統會自動以遞減順序排序傳回的搜尋結果。此時，傳回的文件數量沒有限制。如果您有指定任何排序選項，則系統會在選取所有符合的文件後執行排序作業。有一個明確屬性 SortOptions.Limit 可控制排序的規模。需排序的文件不可超過 10,000 份，預設值是 1,000。如果符合的文件數量超過 SortOptions.Limit 指定的數量，則搜尋只會擷取、排序並傳回該限制數量。搜尋會從所有符合文件的清單中選取要排序的文件 (文件按遞減排列)。查詢所選出的符合文件可能會超過您可以排序的數量。若使用排序選項，且必須擷取所有符合文件，則應該設法確保查詢所傳回的文件不會超過您可以排序的數量。

撰寫運算式

運算式用於定義欄位運算式 (在 SearchOptions 中設定) 和排序運算式 (在 SortOptions 中設定)。這些運算式的撰寫形式是字串：

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

與數字欄位相關的運算式可以使用算術運算子 (+、-、*、/)，以及下方所列的內建數值函式。與地理點欄位相關的運算式可以使用地理點函式和距離函式。文字欄位和 HTML 欄位的運算式可以使用程式碼片段函式。

運算式也有可能包含下列特殊字詞：

詞彙 說明
_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 需要兩個數值引數。呼叫 pow(x, y) 會計算出 x 的 y 次方值。 pow(x, 2)
count 需以一個欄位名稱做為引數。會傳回文件中使用該名稱的欄位數量。請注意，一份文件可包含同名但類型不同的多個欄位。注意：count 只能用於 FieldExpressions。不能出現在 SortExpressions 中。 count(user)

地理點函式

這些函式可用於與地理點欄位相關的運算式。

函式 說明 範例
geopoint 以經緯度定義地理點。 geopoint(-31.3, 151.4)
distance 計算兩個地理點之間的距離 (單位為公尺)。請注意，這兩個引數都可以是地理點欄位的名稱，或地理點函式的叫用名稱。不過，只能有一個引數是欄位名稱。 distance(geopoint(23, 134), store_location)

文字片段

文字片段是指文字欄位的一個片段，該片段符合查詢字串且包括周圍文字。要建立文字片段，需呼叫 snippet 函式：

snippet(query, body, [max_chars])

query
加引號的查詢字串，指定要在欄位中尋找的文字。
body
文字、HTML 或 Atom 欄位的名稱。
max_chars
文字片段中傳回的字元數上限。這是選用引數；預設為 160 個字元。

此函式會傳回 HTML 字串。此字串包含由內文欄位值組成的文字片段，與查詢相符的文字會以粗體顯示。