查詢字串

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

字串包含 Unicode 字元。查詢字串的長度上限為 2000 個字元。所有查詢字串都包含至少一個欄位值。由於 Atom、文字和 HTML 欄位的搜尋不區分大小寫，且查詢字串也可包含以大寫表示的布林運算子 AND、OR 和 NOT，因此建議以小寫字元寫入欄位值。

出現在查詢字串中的逗號只能用於分隔函式引數，例如 distance(home, geopoint(35.2, 40.5)) > 100，或加引號字串的一部分。

查詢字串可以採用多種形式。建構查詢的方式主要分為兩種：包含及不包含欄位名稱。「全域搜尋」使用僅包含欄位值的查詢字串：

query = "blue"
query = "NOT white"
query = "blue OR red"
query = "blue guitar"

「欄位搜尋」使用包含一或多個指定欄位名稱和欄位值的運算式：

query = "model:gibson date < 1965-01-01"
query = "title:\"Harry Potter\" AND pages<500"
query = "beverage:wine color:(red OR white) NOT country:france"

本文件說明如何建構全域搜尋和欄位搜尋的查詢字串，以及各種情況下的搜尋邏輯運作方式。

如果您想記錄已執行的查詢，建議您在應用程式中記錄查詢字串。

全域搜尋

全域搜尋可用於指定可能出現在「任何」文件欄位中的值，以利搜尋文件。如要執行全域搜尋，您需要撰寫包含一或多個欄位值的查詢字串。搜尋演算法會辨識每個值的類型，並搜尋所有可能包含該值的文件欄位。

單值查詢

要使用包含單值的查詢字串進行搜尋，必須掌握以下規則：

如果查詢字串是一個單字 (red) 或一個加引號的字串 ("red rose")，搜尋會擷取索引中包含以下內容的所有文件：

• 包含該單字或加引號字串的文字或 HTML 欄位 (比對不區分大小寫)
• 包含與該單字或加引號字串相符的值的 Atom 欄位 (比對不區分大小寫)

如果查詢字串是一個數字 (「3.14159」)，搜尋會擷取包含以下內容的所有文件：

• 包含與查詢中的數字相符之符記的文字或 HTML 欄位 (文字欄位「he took 5 minutes」與查詢「5」相符，但與「5.0」不相符)。
• 與出現在查詢中的數字完全相符的 Atom 欄位

如果查詢字串是採用「yyyy-mm-dd」格式的日期，搜尋會擷取包含以下內容的所有文件：

• 值等於該日期的日期欄位 (查詢字串可加亦可不加前置的零，「2012-07-04」和「2012-7-4」是指同一天)。
• 包含與查詢中日期相符之符記的文字或 HTML 欄位。
• 與出現在查詢中的日期完全相符的 Atom 欄位。

您可以在單字查詢的前面加入 NOT 布林運算子 (大寫)。根據相同的規則，結果將會產生沒有任何欄位與查詢值相符的文件清單。因此，查詢 NOT red 會擷取所有的文件，且在這些文件當中無任何文字、內含「red」的 HTML 欄位，或是具有 red 值的任何 Atom 欄位。

您可能已經注意到，本文並未提及地理點欄位。目前您仍無法將原始的地理點值指定為字串，因此地理點並不能出現在全域搜尋中。

多值查詢

您可以在全域搜尋字串中指定多個值 (以空格分隔)。單字、加引號字串、數字與日期之間的空格均視同隱式 AND 運算子。以下兩個搜尋字串「幾乎」相同；唯一的差別在於全域搜尋處理 Atom 欄位的方式，詳見下方說明：

query = "small red"
query = "small AND red"

使用多個值執行全域搜尋時，會根據字串中的每個值獨立完成欄位比對，但 Atom 欄位的比對方式則不一樣，特別是：

• 查詢值出現在文字或 HTML 欄位中的順序不拘。
• 不同的值可以出現在不同的欄位中。
• 只有當查詢字串不包含任何布林運算子 (AND、OR、NOT) 時，才會搜尋 Atom 欄位。整個查詢字串必須與 Atom 欄位完全相符。

請注意第三項關於 Atom 欄位的處理規則。由於查詢字串「red small」不含布林運算子 AND (即使其是隱式運算子)，因此搜尋會嘗試尋找相符的 Atom 欄位。由於查詢字串「red AND small」包含布林運算子，因此搜尋不會嘗試比對查詢字串與 Atom 欄位。

以下範例說明使用查詢字串「rose bud」擷取的四個文件。每個文件各有兩個文字欄位和一個 Atom 欄位。註解欄說明各文件符合查詢條件的原因。

請注意，如果將查詢中的值顛倒過來，改為搜尋「bud rose」，文件 1、2 和 3 仍會傳回相符結果，但文件 4 不會。若要在 Atom、文字和 HTML 欄位中搜尋字元完全相符的字串，請將查詢字串中的字串加上引號。若以 "rose bud" 執行搜尋，只會傳回範例中的文件 3 和 4。

布林運算子

您可以在值的前面加入布林運算子 NOT，也可以在值之間加入布林運算子 AND 和 OR，以此方式指定較複雜的全域搜尋。請注意，這些運算子必須以大寫表示。如果出現在加引號的字串中，這些運算子視同欄位值的一部分，而不會視為運算子。若要讓邏輯更清晰，您可以在查詢字串中使用括號。

布林運算子的優先順序從最高到最低依序為 NOT、OR、AND：

NOT cat AND dogs OR horses --> (NOT cat) AND (dogs OR horses)
NOT cat OR dogs AND horses --> ((NOT cat) OR dogs) AND horses

詞幹提取

若要搜尋常見的單字變體，如複數和動詞結尾，請使用 ~ 詞幹運算子 (波浪號)。這是一個前綴運算子，必須放在值之前，而且中間不可以有空格。值 ~cat 會與「cat」或「cats」相符，同樣地，~dog 會與「dog」或「dogs」相符。字根處理演算法並非萬無一失，例如，值 ~care 會與「care」和「caring」相符，但卻不會與「cares」或「cared」相符。詞幹分析只適合用於搜尋文字和 HTML 欄位。

代碼化

將文件編入索引後，其欄位會代碼化。同樣地，查詢字串中的值也會代碼化。也就是說，看起來像是單值的查詢，實際上會視為是多值查詢。例如：

"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"

欄位搜尋

欄位搜尋會按照欄位名稱在指定的文件欄位中搜尋值。欄位搜尋查詢字串由一或多個指定「欄位名稱」、「關係運算子」和「欄位值」的運算式組成。可用的關係運算子需視欄位類型而定。以一個冒號或等號表示的等號運算子可用於所有欄位類型。以下為一些不同類型欄位的欄位查詢字串：

query = "pet = dog"
query = "author = \"Ray Bradbury\""
query = "color:red"
query = "NOT color:red"
query = "price < 500"
query = "birthday>=2011-05-10"

請注意，您可以自由決定是否要在關係運算子的任何一邊加入空格。如同使用全域搜尋查詢字串，您可以為文字、HTML 或 Atom 欄位的值加上引號，以利指定字串，同時，您也可以透過在欄位值運算式前面加上大寫 NOT 的方式表示否定。

查詢 Atom 欄位

Atom 欄位的值是字元字串。Atom 欄位查詢不區分大小寫。如果您的查詢指定含有空格或標點符號的欄位值，請務必要將查詢字串中的值加上引號。Atom 欄位唯一有效的關係運算子是等號運算子。Atom 欄位的內容必須全部與查詢值相符；包括欄位中的任何 Unicode 組合字元或重音字元。Atom 欄位不支援詞幹分析。

查詢文字和 HTML 欄位

文字和 HTML 欄位唯一有效的關係運算子是等號運算子。在此案例中，運算子代表的意義是「欄位包含值」，而不是「欄位等於值」。您可以使用詞幹分析運算子搜尋單字變體。您也可以使用 OR 和 AND 運算子為欄位值指定複雜的布林運算式。如果布林運算子出現在加引號的字串中，不會有特殊的處理方式，只會被視為要進行比對的一段字元字串。請記住，搜尋 HTML 欄位時會略過 HTML 標記標籤中的文字。文字和 HTML 欄位查詢不區分大小寫。將這些欄位編入索引後，欄位中的任何 Unicode 組合字元和重音字元都會「正規化」為無重音的對等字元。而查詢字串中關於這些欄位組合字元和重音字元也會「正規化」，因此，查詢中的字元不論是否包含重音，均不會影響結果，而且會比對這兩種形式的欄位。

查詢數字欄位

數字欄位值可以寫為整數、小數或指數。數字欄位的有效關係運算子包括等號運算子及小於/大於運算子 (<、<=、>、>=)。請注意，不支援不等於 (!=) 運算子。以下舉例說明數字欄位的查詢字串：

"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"

查詢日期欄位

日期欄位值的格式必須是 yyyy-mm-dd form。個位數的月份和日期可加上前置零，也可不加。日期欄位的有效關係運算子包括等號運算子及小於/大於運算子 (<、<=、>、>=)。請注意，不等於運算子不支援。您可以在運算式前面加入 NOT 運算子，表示否定。以下舉例說明日期欄位的查詢字串：

"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"

查詢地理點欄位

地理點欄位沒有適用的關係運算子，因此無法在查詢字串中直接命名。Search API 提供兩種可用於查詢地理點相關欄位的特殊函式：

geopoint(lat,long)

以經緯度定義地理點。

distance(point1, point2)

計算兩個地理點之間的距離 (單位為公尺)。您可以透過使用地理點欄位名稱或叫用地理點函式的方式指定每個地理點。請注意，您不能提供兩個欄位名稱當成這個函式的引數。至少其中一個引數必須為常數。

若要針對擷取相對於固定位置的位置建構查詢，可以使用這些函式。以下範例假設索引包含的文件中有名為「survey_marker」和「home」的地理點欄位。

使用地理定位功能的應用程式通常會接收來自瀏覽器的資訊。如果使用者允許，系統可以利用其 IP 位址推斷出使用者的位置，也可以由使用者輸入郵遞區號。位置也可能來自其他類似 API，例如 Google 地圖地理定位 API。

查詢多個欄位

您可以在一個查詢中組合多個欄位查詢運算式，方法是依序列出這些運算式並以空格分隔。運算式之間的空格隱含 AND 的意涵，因此擷取的文件必須同時符合全部的運算式。若要讓邏輯更清晰，您也可以在運算式之間加入 AND 和 OR 運算元及使用括弧。

混合全域和欄位搜尋

查詢字串可包含任何數量的全域搜尋運算式和欄位搜尋運算式。運算式之間的空格會視為 AND。您也可以明確使用 OR 和 AND，並搭配括號。處理每個運算式時，一律以該類字詞的相關規則為準。