查詢和排序選項

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

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

您可以使用 查詢類別的執行個體做為 search() 的引數，以變更這些選項。

Query 類別可用於指定一次傳回多少文件，也可以讓您自訂所擷取文件的內容。您可以要求只傳回文件 ID，或要求文件只包含欄位子集。您也可以在擷取的文件中建立自訂欄位：文字片段 (文字欄位片段，顯示相符字串周圍的文字)，以及欄位運算式 (欄位值會從文件中的其他欄位衍生)。

除了查詢選項外，Query 類別也可以包含 SortOptions 類別的例項。使用排序選項可以變更排序順序，也可以依多個索引鍵排序結果。

使用 Query 類別搜尋

使用 Query 類別的執行個體搜尋時，需分為數個步驟建構該類別的執行個體。一般順序如下：

  1. 建立查詢字串。
  2. 視需要建立 SortOptions。
  3. 建立 QueryOptions。
  4. 建立一個包含查詢字串與 (可選) QueryOptions 的 Query 物件。
  5. 對該 Query 物件呼叫搜尋方法。

QueryOptions 和 SortOptions 建構函式使用具名引數，如以下範例所示：

def query_options():
    index = search.Index('products')
    query_string = "product: piano AND price < 5000"

    # Create sort options to sort on price and brand.
    sort_price = search.SortExpression(
        expression='price',
        direction=search.SortExpression.DESCENDING,
        default_value=0)
    sort_brand = search.SortExpression(
        expression='brand',
        direction=search.SortExpression.DESCENDING,
        default_value="")
    sort_options = search.SortOptions(expressions=[sort_price, sort_brand])

    # Create field expressions to add new fields to the scored documents.
    price_per_note_expression = search.FieldExpression(
        name='price_per_note', expression='price/88')
    ivory_expression = search.FieldExpression(
        name='ivory', expression='snippet("ivory", summary, 120)')

    # Create query options using the sort options and expressions created
    # above.
    query_options = search.QueryOptions(
        limit=25,
        returned_fields=['model', 'price', 'description'],
        returned_expressions=[price_per_note_expression, ivory_expression],
        sort_options=sort_options)

    # Build the Query and run the search
    query = search.Query(query_string=query_string, options=query_options)
    results = index.search(query)
    for scored_document in results:
        print(scored_document)

QueryOptions

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

屬性 說明 預設 上限
limit 結果中傳回的文件數量上限。 20 1000
number_found_accuracy 此屬性決定 SearchResults.number_found() 傳回結果的準確率。會針對實際列入計算的符合結果數量設限，達到上限即停止搜尋。

如果索引中符合的數量少於或等於上限，則會傳回確切的數目。若非如此，傳回的數目會是估計值，依據找到的符合結果，以及索引的大小與結構而定。請注意，此屬性的值越高，越易影響搜尋作業的複雜程度，可能會導致逾時。		 如果未指定或設定為 None，準確度會設為與 limit 相同的值 25000
offset 要傳回的第一份文件在結果中的偏移量。 0。結果將包含所有符合的文件 (不超過上限) 1,000
cursor 可使用游標取代偏移量，用於擷取一組組經過排序的文件。將游標傳入及傳出連續查詢時會更新游標，每次重新查詢時，都會從上一頁的結尾處往下接著進行。關於游標和偏移的討論，請參閱處理結果頁面。 空值。結果將包含所有符合的文件 (不超過上限) -
sort_options 設定 SortOptions 物件，用於控制搜尋結果的排序方式。SortOptions 的例項自有一組屬性，如下所述。 空值。以遞減順序排序文件。 -

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

屬性 說明 預設
ids_only 設為 True 或 False。設為 True 時，結果中傳回的文件只包含 ID，不包含欄位。 False (傳回所有欄位)。
returned_fields 指定要在結果中包含哪些文件欄位。最多可指定 100 個欄位。 傳回所有文件欄位 (最多 100 個欄位)。
returned_expressions 欄位運算式，說明要將哪些經過運算的欄位新增至搜尋結果傳回的每份文件。這些欄位會新增至文件的運算式屬性。若要指定欄位值，需撰寫運算式，其中可能包含一或多個文件欄位。 無
snippeted_fields 文字欄位名稱清單。會為每個欄位產生一個程式碼片段。這是經過運算的欄位，會新增至搜尋結果文件中的運算式屬性。程式碼片段欄位的名稱與其來源欄位名稱相同。

這個選項使用程式碼片段函式加上兩個引數，間接建立最多包含一個相符字串的程式碼片段，其準據是搜尋用於擷取結果的查詢字串：snippet("query-string", field-name)。

您也可以新增會明確呼叫程式碼片段函式的欄位運算式，以使用 returned_expressions 選項建立自訂的程式碼片段。		 無

SortOptions

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

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

依多個索引鍵排序

您可以依多個排序索引鍵排序搜尋結果。每個索引鍵可以是單純的欄位名稱，也可以是以多個欄位運算得出的值。請注意，談及排序選項時，「運算式」一詞具有多種意義：SortOption 本身具有「運算式屬性」。此屬性是對應排序索引鍵的 SortExpression 物件清單。最後，每個 SortExpression 物件各包含一個「運算式屬性」，用於指定計算排序索引鍵值的方式。這個運算式會根據下一節中的規則進行建構。

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

屬性 說明 預設
expression 排序每份符合文件的結果時，所要評估的運算式。 無
direction 搜尋結果的排序方向，為 ASCENDING 或 DESCENDING。 DESCENDING
default_value 運算式預設值，文件中若沒有出現此欄位，即無法計算。必須指定文字值才能排序文字。要排序數字則須指定數值。 無

依多值欄位排序

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

排序與否

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

撰寫運算式

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

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

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

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

詞彙 說明
_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 需要兩個數值引數。呼叫 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 字串。此字串包含由內文欄位值組成的文字片段，與查詢相符的文字會以粗體顯示。