查詢和排序選項

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

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

您可以使用查詢類別的執行個體做為 search() 引數,以變更這些選項。Query 類別可用於指定一次傳回多少文件,也可以讓您自訂所擷取文件的內容。您可以要求只傳回文件 ID,或要求文件只包含欄位子集。您也可以在擷取的文件中建立自訂欄位:文字片段 (文字欄位片段,顯示相符字串周圍的文字),以及欄位運算式 (欄位值會從文件中的其他欄位衍生)。

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

使用 Query 類別搜尋

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

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

QueryOptionsSortOptions 建構函式使用具名引數,如以下範例所示:

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 設為 TrueFalse。設為 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 搜尋結果的排序方向,為 ASCENDINGDESCENDING 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 時指派給文件的分數。此字詞只能出現在排序運算式中,不能用於欄位運算式。

數值函式

用於定義 FieldExpressionsSortExpressions 之數值的運算式可以使用這些內建函式。引數必須是數字、欄位名稱或是使用數字和欄位名稱的運算式。

函式 說明 範例
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 字串。此字串包含由內文欄位值組成的文字片段,與查詢相符的文字會以粗體顯示。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Python 2 適用的 App Engine 標準環境