查詢字串

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

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

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

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

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

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

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

單值查詢

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

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

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

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

  • 包含與查詢中數字相等的值的數字欄位 (包含數值 5 的數字欄位與查詢「5」和「5.0」相符)
  • 包含與查詢中的數字相符之符記的文字或 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 欄位中的順序不拘。
  • 不同的值可以出現在不同的欄位中。
  • 只有當查詢字串不包含任何布林運算子 (ANDORNOT) 時,才會搜尋 Atom 欄位。整個查詢字串必須與 Atom 欄位完全相符。

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

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

文件 ID 文字欄位 1 文字欄位 2 Atom 欄位 註解
1 mighty like a rose one bud to bind them all thorn bush 相符值可以出現在不同的欄位中
2 wide like a river like a bud on a rose tumble weed 相符值可以出現在同一個文字或 HTML 欄位中,順序不拘,中間還可以插入文字
3 deep like the ocean the rose bud boys blue bonnet 相符值可以出現在同一個文字或 HTML 欄位中,順序不拘
4 tall like a mountain the beautiful garden rose bud Atom 欄位比對成功,因為其值與查詢字串完全相符

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

布林運算子

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

布林運算子的優先順序從最高到最低依序為 NOTORAND

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 欄位不支援詞幹分析。

查詢字串 註解
"weather=stormy"
"weather: stormy"
兩種形式的等號運算子都有效。擷取天氣 (weather) 欄位等於「stormy」的文件。
"Title: \"Tom&Jerry\""
"Couple: \"Fred and Ethel\""
"Version = \"1HCP(21.3)\""
如果要搜尋包含空格或特殊字元的 Atom 欄位,請用引號將值括住。
"Color = (red OR blue)"
"Color = (\"dark red\" OR \"bright blue\")"
您可以使用括號和邏輯運算子 OR 指定一連串替代欄位值。

查詢文字和 HTML 欄位

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

查詢字串註解
"Comment = great"
"Comment: great"
兩種形式的等號運算子都有效。擷取註解 (Comment) 欄位至少出現過一次「great」這個單字的文件。
"Comment = (great big ball)"
"Comment = (great AND big AND ball)"
若要在欄位中按照任何順序搜尋兩個或兩個以上的單字,請用括號括住這些單字。此查詢字串會擷取註解 (Comment) 欄位中包含這三個單字 (排列順序不拘),且三個單字之間還有其他單字 (數量不拘) 的文件。單字之間的空格隱含邏輯運算子 AND 的意涵,第二種形式的查詢字串則明確具有這個意涵。
"Comment = \"insanely great\"" 若要搜尋特定的文字字串,請用引號括住字串。這項查詢會擷取註解 (Comment) 欄位中包含「insanely great」這個字詞 (以及代碼化後具有相同意義的「insanely-great」一詞) 的文件。
"pet = ~dog" 詞幹運算子會比對寵物 (pet) 欄位「dog」這個單字的變體。
"Color = (red OR blue)" 若要在替代單字清單中搜尋相符項目,請用括號括住清單,並在替代單字之間加入關鍵字 OR。這項查詢會擷取色彩 (Color) 欄位包含「red」和/或「blue」的文件。
"weather = ((rain OR snow) AND cold)" 您可以使用邏輯運算子 OR 和 AND 再加上括號,用於指定較複雜的欄位值。
"weather = \"rain OR shine\"" 由於邏輯 OR 嵌入於加引號的字串中,因此不會被視為關係運算子。此查詢字串會擷取天氣 (weather) 欄位包含「rain or shine」字串的文件。

查詢數字欄位

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

"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」的地理點欄位。

查詢字串 註解
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" 搜尋與指定地理點距離不到 100 公尺的地標。
"distance(home, geopoint(35.2, 40.5)) > 100" 搜尋與指定地理點距離 100 公尺以上的住家。

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

查詢多個欄位

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

查詢字串 註解
"product=piano manufacturer=steinway"
"product=piano AND manufacturer=steinway"
這些查詢會擷取所有的 Steinway 鋼琴。字詞之間的空格隱含邏輯運算子 AND 的意涵,第二種形式的查詢字串則明確具有這個意涵。
"product=piano AND NOT manufacturer=steinway" 擷取所有不是 Steinway 的鋼琴。
"product=piano AND price<2000" 這項查詢會擷取價格便宜的鋼琴。

混合全域和欄位搜尋

查詢字串可包含任何數量的全域搜尋運算式和欄位搜尋運算式。運算式之間的空格會視為 AND。您也可以使用 ORAND 以及括弧表達更明確的意涵。處理每個運算式時,一律以該類字詞的相關規則為準。

查詢字串註解
"keyboard great price<5000"
"keyboard AND great AND price<5000"
擷取任何文字、HTML 或 Atom 欄位中出現單字「great」和「keyboard」,且其中一個價格 (price) 欄位在 5000 以下的文件。AND 在此處為隱含,第二種形式為對等查詢字串。
"keyboard OR product=piano" 擷取產品 (product) 欄位包含「piano」的文件,或者任何文字、HTML 或 Atom 欄位中包含「keyboard」的文件。
本頁內容對您是否有任何幫助?請提供意見:

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

這個網頁
Java 8 適用的 App Engine 標準環境