Azure AI 搜尋服務中的 Lucene 查詢語法

發行項
09/19/2024

在 Azure AI 搜尋中建立查詢時，您可以選擇採用完整的 Lucene 查詢剖析器語法，以建立特製化查詢表單：萬用字元、模糊搜尋、鄰近搜尋、規則運算式。 Lucene 查詢剖析器語法大多會原封不動地實作到 Azure AI 搜尋服務中，但「範圍搜尋」除外，範圍搜尋會透過 $filter 運算式來建構。

若要使用完整的 Lucene 語法，請將 queryType 設定為「full」，並傳入針對萬用字元、模糊搜尋或完整語法所支援的其他查詢表單之一來設計模式的查詢運算式。 REST 會於搜尋文件 (REST API) 要求的 search 參數中提供查詢運算式。

範例 (完整語法)

下列範例是使用完整語法所建構的搜尋要求。這個特殊範例會顯示欄位中搜尋和字詞提升。其會尋找類別欄位包含「budget」一詞的旅館。任何包含 "recently renovated" 片語的文件會因為字詞提升值 (3) 而排在比較前面。

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

雖然 searchMode 參數未專屬於任何查詢類型，但在此範例中，這個參數有其意義。每當在查詢上使用運算子時，您通常都應設定 searchMode=all，以確保所有的準則均相符。

如需更多範例，請參閱 Lucene 查詢語法範例。如需查詢要求和參數的詳細資訊 (包括 searchMode)，請參閱搜尋文件 (REST API)。

語法基礎

下列語法基礎適用於所有使用 Lucene 語法的查詢。

內容中的運算子評估

位置會決定一個符號應解譯為運算子，或只是字串中的另一個字元。

例如，在 Lucene 完整語法中，波狀符號 (~) 可用於模糊搜尋與鄰近搜尋。「~」放在加上引號的片語後面時，將會叫用鄰近搜尋。「~」放在字詞結尾處時，則會叫用模糊搜尋。

在詞彙中，例如 business~analyst，字元將不會被評估為運算子。在此情況下，假設查詢是術語或片語查詢，則使用語彙分析的全文檢索搜尋將會去除 ~ 並將 business~analyst 一詞分為兩部分：business 或 analyst。

上述範例說明的是波狀符號 (~)，但每個運算子都適用相同原則。

逸出特殊字元

若要在搜尋文字中使用任何搜尋運算子，請在字元前面加上單一反斜線 (\) 來逸出字元。例如，在 https:// 上進行萬用字元搜尋時，:// 是查詢字串的一部分，因此您會指定 search=https\:\/\/*。同樣地，逸出的電話號碼模式看起來可能會像這樣：\+1 $800$ 642\-7676。

需要逸出的特殊字元包括下面這些：
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

注意

雖然逸出會將權杖保持在一起，但索引編製期間的語彙分析可能會將其去除。例如，標準 Lucene 分析器會中斷連字號、空白字元和其他字元上的單字。如果您需要在查詢字串中使用特殊字元，則可能需要會在索引中保留特殊字元的分析器。選項包括 Microsoft 自然語言分析器 (其會保留有連字號的字組)，或可處理更複雜模式的自訂分析器。如需詳細資訊，請參閱部分字詞、模式和特殊字元。

為 URL 中的 Unsafe 字元和保留字元編碼

請確定所有 Unsafe 字元和保留字元在 URL 中都已編碼。例如，「#」是 Unsafe 字元，因為這是 URL 中的片段/錨點識別碼。此字元在 URL 中使用時必須編碼為 %23。「&」和「=」是保留字元的範例，因為它們用來分隔參數，以及指定 Azure AI 搜尋服務中的值。請參閱 RFC1738：統一資源定位器 (URL)，以取得詳細資訊。

Unsafe 字元包括 " ` < > # % { } | \ ^ ~ [ ]。保留字元包括 ; / ? : @ = + &。

布林運算子

您可以在查詢字串中內嵌布林運算子，以提升相符項目的精確度。除了字元運算子外，完整的語法還支援文字運算子。文字布林運算子 (AND、OR、NOT) 須一律全部以大寫指定。

文字運算子	字元	範例	使用方式
且	`+`	`wifi AND luxury`	指定相符項目必須包含的字詞。在範例中，查詢引擎會尋找包含 `wifi` 和 `luxury` 的文件。您也可以直接在字詞前面使用加號字元 (`+`)，使該字詞成為必要項目。例如，`+wifi +luxury` 會指定這兩個字詞必須出現單一文件的某個欄位中。
OR	(無) ¹	`wifi OR luxury`	找到任一字詞時，尋找相符項目。在範例中，查詢引擎會針對包含 `wifi` 和 (或) `luxury` 的文件傳回相符項目。 OR 是預設的連接運算子，所以您也可以將其省略，因此 `wifi luxury` 相當於 `wifi OR luxury`。
NOT	`!`, `-`	`wifi –luxury`	針對排除字詞的文件傳回相符項目。例如，`wifi –luxury` 會搜尋含有 `wifi` 字詞，但不含 `luxury` 的文件。

¹ OR 運算不支援 | 字元。

NOT 布林運算子

重要

NOT 運算子 (NOT、! 或 -) 在完整語法中的行為與在簡單語法中不同。

在簡單語法中，具有否定的查詢一律會自動新增萬用字元。例如，查詢 -luxury 會自動展開至 -luxury *。
在完整語法中，具有否定的查詢無法與萬用字元結合。例如，不允許查詢 -luxury *。
在完整語法中，不允許具有單一否定的查詢。例如，不允許查詢 -luxury。
在完整語法中，無論搜尋模式為何，否定都將被視為始終與查詢進行 AND 操作。
- 例如，完整語法中的完整語法查詢 wifi -luxury 只會擷取包含字詞 wifi 的文件，然後將否定 -luxury 套用至這些文件。
如果您想要使用否定來搜尋索引中的所有文件，建議使用 any 搜尋模式的簡單語法。
如果您想要使用否定來搜尋索引中文件的子集，建議使用所有搜尋模式的完整語法或簡單語法。

查詢類型	搜尋模式	範例查詢	行為
簡單	任意	`wifi -luxury`	傳回索引中的所有文件。具有「wifi」一詞的文件或遺漏「luxury」一詞的文件，排名會比其他文件高。查詢會展開至 `wifi OR -luxury OR *`。
簡單	全部	`wifi -luxury`	只傳回索引中含有「wifi」一詞且不包含「luxury」一詞的文件。查詢會展開至 `wifi AND -luxury AND *`。
完整	任意	`wifi -luxury`	只傳回索引中包含「wifi」字詞的文件，然後會從結果中移除包含「luxury」一詞的文件。
完整	全部	`wifi -luxury`	只傳回索引中包含「wifi」字詞的文件，然後會從結果中移除包含「luxury」一詞的文件。

欄位搜尋

您可以使用 fieldName:searchExpression 語法定義欄位搜尋運算，其中，搜尋運算式可以是單一字組或片語，或用括號括住的更複雜運算式，也可以選擇性地使用布林運算子。部分範例包括以下內容：

genre:jazz NOT history
artists:("Miles Davis" "John Coltrane")

如果您想要將字串視為單一實體評估，請務必將多個字串放在引號中，就此案例而言，即搜尋 artists 欄位中的兩個不同藝人。

fieldName:searchExpression 中指定的欄位必須是 searchable 欄位。如需欄位定義中索引屬性使用方式的詳細資訊，請參閱建立索引。

注意

使用欄位搜尋運算式時，您不需要使用 searchFields 參數，因為每個欄位搜尋運算式都會明確指定欄位名稱。不過，如果您想要執行的查詢會將某些部分的範圍限定在特定欄位，其餘部分則套用至數個欄位，則還是可以使用 searchFields 參數。例如，search=genre:jazz NOT history&searchFields=description 查詢只會將 jazz 與 genre 欄位進行比對，而將 NOT history 與 description 欄位進行比對。 fieldName:searchExpression 中提供的欄位名稱的優先權一律高於 searchFields 參數，因此在這個範例中，我們不需要在 searchFields 參數中包含 genre。

模糊搜尋

模糊搜尋會在具有類似建構的字詞中尋找相符項目，並將字詞擴充到最多 50 個符合兩個以下距離條件的字詞。如需詳細資訊，請參閱模糊搜尋。

若要執行模糊搜尋，請在單一文字結尾使用波狀符號「~」，加上選擇性參數，介於 0 和 2 (預設值) 之間且指定編輯距離的數值。例如，blue~ 或 blue~1 會傳回 blue、blues 與 glue。

模糊搜尋只能套用至字詞，不能套用至引號括住的片語，但您可以在由多個部分組成的名稱或片語中，為每個字詞個別附加波狀符號。例如，Unviersty~ of~ Wshington~ 會符合 University of Washington。

鄰近搜尋

鄰近搜尋可用來尋找文件中彼此相近的詞彙。在片語的結尾插入波狀符號「~」，後面加上建立鄰近界限的字數。例如，"hotel airport"~5 可在文件中找到彼此相距不超過 5 個字組的字詞 hotel 和 airport。

字詞提升

字詞提升指的是如果某個文件包含提升的字詞，便會比未包含該字詞的文件獲得更高的順位。這與評分設定檔的不同之處在於評分設定檔會提升特定欄位，而不是特定詞彙。

下列範例可協助說明差異。假設有一個評分設定檔可提升特定欄位中的相符項目，例如 musicstoreindex 範例中的 genre。詞彙提升可用來進一步提升某些搜尋詞彙，使其高於其他詞彙。例如，rock^2 electronic 可提升包含搜尋字詞的文件﹐使其在內容類型欄位中高於索引中的其他可搜尋欄位。此外，包含搜尋字詞 rock 的文件排名會比另一個搜尋字詞 electronic 還高，此為字詞提升值 (2) 的結果。

若要提升字詞，請使用插入號「^」，並在搜尋字詞的結尾加上提升係數 (數字)。您也可以提升片語。提升係數越高，該詞彙相對於其他搜尋詞彙的關聯性也越高。提升因素預設為 1。雖然提升係數必須是正數，但是它可能會小於 1 (例如，0.20)。

規則運算式搜尋

規則運算式搜尋會根據 Apache Lucene 下有效的模式來尋找相符項目，如 RegExp 類別中所述。在 Azure AI 搜尋中，規則運算式會以兩個正斜線 / 括住。

例如，若要尋找包含 motel 或 hotel 的檔案，請指定 /[mh]otel/。規則運算式搜尋會比對單字。

除了 Azure AI 搜尋施加的逸出規則之外，某些工具和語言也施加了額外的逸出字元需求。在 JSON 中，包含正斜線的字串會以反斜線逸出：microsoft.com/azure/ 會變成 search=/.*microsoft.com\/azure\/.*/，其中 search=/.* <string-placeholder>.*/ 會設定規則運算式，而且 microsoft.com\/azure\/ 是使用已逸出正斜線的字串。

Regex 查詢中的兩個常見符號為 . 和 *。 . 會比對任何一個字元，* 會比對上一個字元零次或多次。或例如，/be./ 符合字詞 bee 和 bet，而 /be*/ 將符合 be、bee 和 beee，但不符合 bet。一起使用時，.* 可讓您比對任何連串字元，因此 /be.*/ 會比對任何開頭為「be」的字詞，例如「better」。

如果您在規則運算式中收到語法錯誤，請檢閱特殊字元的逸出規則。您也可以嘗試不同的客戶端來確認問題是否針對特定工具。

萬用字元搜尋

您可以使用一般辨識語法來進行多字元 (*) 或單一字元 (?) 的萬用字元搜尋。完整 Lucene 語法支援前置詞和中置詞比對。使用規則運算式語法進行後置詞比對。

請注意，Lucene 查詢剖析器支援搭配使用這些符號與單一詞彙，而不是片語。

詞綴類型	描述和範例
prefix	字詞片段出現在 `` 或 `?` 之前。例如，傳回 `alphanumeric` 或 `alphabetical` 的 `search=alpha` 查詢運算式。簡單語法和完整語法都支援前置詞比對。
尾碼	字詞片段位於 `` 或 `?` 之後，並以正斜線分隔建構。例如 `search=/.numeric/` 會傳回 `alphanumeric`。
中置	字詞片段括住 `` 或 `?`。例如 `search=nonal` 會傳回 `non-numerical` 和 `nonsensical`。

您可以在一個運算式中合併多個運算子。例如，980?2* 會與 98072-1222 和 98052-1234 進行比對，其中 ? 會與單一 (必要) 字元進行比對，* 會與其後任意長度的字元進行比對。

後置詞比對需要規則運算式正斜線 / 分隔符號。一般而言，您無法在沒有 / 的情況下使用 * 或 ? 符號作為字詞的第一個字元。也請務必注意，* 在 RegEx 查詢之外使用時會有不同的行為。在 RegEx 正斜線 / 分隔符號之外，* 是萬用字元，而且會與任何連串字元進行比對，情況很像 RegEx 中的 .*。例如，search=/non.*al/ 會產生與 search=non*al 相同的結果集。

注意

作為規則，模式比對的速度很慢，因此您可能會想要探索替代方法，例如會為字詞中的字元序列建立語彙基元的「邊緣 n-gram Token 化」。使用 n-gram Token 化時，索引會較大，但視您要編製索引的模式建構和字串長度而定，查詢可能會執行得更快。如需詳細資訊，請參閱部分字詞搜尋和具有特殊字元的模式。

分析器對萬用字元查詢的效果

在剖析查詢的期間，以前置詞、後置詞、萬用字元或規則運算式的形式制訂的查詢會原封不動地傳遞至查詢樹狀結構，不進行語彙分析。只有在索引包含查詢所指定格式的字串時，才會找到相符項目。在大部分情況下，您在編製索引期間需要分析器來保留字串完整性，讓部分字詞和模式比對能夠成功。如需詳細資訊，請參閱 Azure AI 搜尋服務查詢中的部分字詞搜尋。

假設您可能想要搜尋查詢 terminal* 傳回包含 terminate、termination 和 terminates 等字詞的結果。

如果您使用 en.lucene (English Lucene) 分析器，其會套用每個字詞的主動詞幹分析。例如，terminate、termination、terminates 都將權杖化為索引中的權杖 termi。另一方面，在使用萬用字元或模糊搜尋的查詢中，則完全不會分析字詞，因此沒有任何結果符合 terminat* 查詢。

另一方面，Microsoft 分析器 (在此案例中為 en.microsoft 分析器) 會更進階，並使用詞形歸併還原，而不是詞幹分析。這表示所有產生的語彙基元應該都是有效的英文字組。例如，terminate、terminates 和 termination 大部分都會完整留在索引中，而且對於依賴許多萬用字元和模糊搜尋的案例來說，會是較好的選擇。

萬用字元和 RegEx 查詢的評分

Azure AI 搜尋服務會對文字查詢使用以頻率為基礎的評分 (BM25)。不過，針對字詞範圍可能很廣泛的萬用字元和 regex 查詢，則會忽略頻率因素，以防止罕見字詞的相符項目誤獲較高的排名。系統對於萬用字元和 regex 搜尋的所有相符項目，會同等視之。

特殊字元

在某些情況下，您可能會想要搜尋特殊字元，例如「❤」表情符號或「€」符號。在這種情況下，請確定您使用的分析器不會篩選出這些字元。標準分析器會略過許多特殊字元，將其從您的索引中排除。

會將特殊字元權杖化的分析器包括空白字元分析器，其會將以空白字元分隔的任何字元序列視為語彙基元 (因此，會將 ❤ 字串視為權杖)。此外，Microsoft 英文分析器 (「en.microsoft」) 之類的語言分析器會將「€」字串作為語彙基元。您可以測試分析器，以了解其會針對指定查詢產生什麼語彙基元。

使用 Unicode 字元時，請確定查詢 URL 中的符號有正確逸出 (例如，❤ 會使用逸出序列 %E2%9D%A4+)。某些 REST 用戶端會自動執行此翻譯。

優先順序 (分組)

您可以使用括號，在加上括號的陳述式內加入運算子，以建立子查詢。例如，motel+(wifi|luxury) 會搜尋包含 motel 字詞以及 wifi 或 luxury (或兩者) 的文件。

欄位分組也相類似，但分組的範圍會限定於單一欄位。例如，hotelAmenities:(gym+(wifi|pool)) 會在欄位 hotelAmenities 中搜尋 gym 和 wifi，或 gym 和 pool。

查詢大小限制

Azure AI 搜尋服務會對查詢大小和組合施加限制，因為未繫結的查詢可能會讓搜尋服務變得不穩定。查詢大小和組合 (子句數目) 會有限制。前置詞搜尋的長度以及 Regex 搜尋和萬用字元搜尋的複雜度也有限制。如果您的應用程式以程式設計方式產生搜尋查詢，建議您依照此方式設計，以避免產生無大小限制的查詢。

如需查詢限制的詳細資訊，請參閱 API 要求限制。

共用方式為