Azure AI 搜尋中的 Lucene 查詢語法
在 Azure AI 搜尋中建立查詢時,您可以針對特殊查詢表單選擇完整的 Lucene 查詢剖析器 語法:通配符、模糊搜尋、鄰近搜尋、正則表示式。 除了透過表達式建構$filter
的 *range 搜尋之外,Azure AI 搜尋中大部分 Lucene 查詢剖析器語法都完整地實作。
若要使用完整的 Lucene 語法,請將 queryType 設定為 full
,並傳入以通配符、模糊搜尋模式的查詢表達式,或完整語法所支援的其他查詢表單之一。 在 REST 中,查詢表示式是在搜尋檔 (REST API) 要求的 參數中search
提供。
範例(完整語法)
下列範例是使用完整語法建構的搜尋要求。 此特定範例會顯示現場搜尋和字詞提升。 它會尋找類別欄位包含字詞 budget
的旅館。 由於字詞提升值 (3) 的結果,包含片語 "recently renovated"
的任何檔會排名較高。
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
"queryType": "full",
"search": "category:budget AND \"recently renovated\"^3",
"searchMode": "all"
}
雖然不是任何查詢類型特有的, searchMode
但參數在此範例中是相關的。 每當運算子在查詢上時,您通常都應該設定 searchMode=all
以確保 所有 準則都相符。
如需更多範例,請參閱 Lucene 查詢語法範例。 如需查詢要求和參數的詳細資訊,包括 searchMode,請參閱 搜尋檔 (REST API) 。
語法基本概念
下列語法基本概念適用於所有使用 Lucene 語法的查詢。
內容中的運算子評估
Placement 會決定符號是解譯為運算符,還是只解譯字串中的另一個字元。
例如,在 Lucene 完整語法中,tilde (~
) 用於模糊搜尋和鄰近搜尋。 放在引號片語之後時, ~
會叫用鄰近搜尋。 當放在字詞結尾時, ~
會叫用模糊搜尋。
在詞彙中,例如 business~analyst
,不會將字元評估為運算符。 在此情況下,假設查詢是字詞或片語彙分析的全文搜尋會去除 ~
,並以兩者分隔字詞business~analyst
: business
OR analyst
。
上述範例是底圖 (~
),但相同的原則適用於每個運算符。
逸出特殊字元
若要使用任何搜尋運算符做為搜尋文字的一部分,請使用單一反斜杠前置詞來逸出字元。\
例如,針對上的 https://
通配符搜尋,其中 ://
是查詢字串的一部分,您會指定 search=https\:\/\/*
。 同樣地,逸出電話號碼模式看起來可能像這樣 \+1 \(800\) 642\-7676
。
需要逸出的特殊字元包括:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /
注意
雖然逸出會將令牌保持在一起, 但索引編製期間的語彙分析 可能會將其去除。例如,標準 Lucene 分析器會中斷連字元、空格符和其他字元上的單字。 如果您需要查詢字串中的特殊字元,您可能需要分析器,以在索引中保留它們。 某些選擇包括 Microsoft 自然 語言分析器,可保留連字元字組,或自定義分析器以取得更複雜的模式。 如需詳細資訊,請參閱 部分字詞、模式和特殊字元。
在 URL 中編碼不安全和保留字元
確定所有不安全和保留的字元都會在URL中編碼。 例如, #
是不安全的字元,因為它是URL中的片段/錨點標識碼。 如果在網址中使用,字元必須編碼為 %23
。 &
和 =
是保留字元的範例,因為它們會分隔參數,並在 Azure AI 搜尋服務中指定值。 如需詳細資訊,請參閱RFC1738:統一資源定位器(URL)。
不安全的字元為 " ` < > # % { } | \ ^ ~ [ ]
。 保留字元為 ; / ? : @ = + &
。
布林運算子
您可以在查詢字串中內嵌布爾運算元,以改善相符項目的精確度。 除了字元運算子之外,完整語法還支援文字運算符。 請一律在所有大寫中指定文字布爾運算子 (AND、OR、NOT)。
文字運算子 | 字元 | 範例 | 使用方式 |
---|---|---|---|
且 | + |
wifi AND luxury |
指定相符項目必須包含的字詞。 在此範例中,查詢引擎會尋找同時包含 wifi 和 luxury 的檔。 加號字元 (+ ) 也可以直接在字詞前面使用,使其成為必要專案。 例如, +wifi +luxury 規定這兩個詞彙都必須出現在單一檔的欄位中。 |
OR | ( 無) 1 | wifi OR luxury |
找到任一字詞時,尋找相符專案。 在此範例中,查詢引擎會在包含 或 luxury 兩者wifi 的檔上傳回相符專案。 因為 OR 是預設的結合運算元,所以您也可以將其排除,因此 wifi luxury 相當於 wifi OR luxury 。 |
NOT | ! , - |
wifi –luxury |
傳回排除字詞之檔的相符專案。 例如, wifi –luxury 搜尋具有 wifi 字詞但不是 luxury 的檔。 |
1|
OR 作業不支援字元。
NOT Boolean 運算符
重要
NOT 運算子 (NOT
、 !
或 -
) 在完整語法中的行為與簡單語法不同。
- 在簡單語法中,具有否定的查詢一律會自動新增通配符。 例如,查詢
-luxury
會自動展開至-luxury *
。 - 在完整語法中,具有否定的查詢無法與通配符結合。 例如,不允許查詢
-luxury *
。 - 在完整語法中,不允許具有單一否定的查詢。 例如,不允許查詢
-luxury
。 - 在完整的語法中,不論搜尋模式為何,否定的行為就如同一律會向查詢進行 AND。
- 例如,完整語法中的完整語法查詢
wifi -luxury
只會擷取包含字詞wifi
的檔,然後將否定-luxury
套用至這些檔。
- 例如,完整語法中的完整語法查詢
- 如果您想要使用否定來搜尋索引中的所有文件,建議使用搜尋模式的
any
簡單語法。 - 如果您想要使用否定來搜尋索引中檔的子集,建議使用所有搜尋模式的完整語法或簡單語法。
查詢類型 | 搜尋模式 | 範例查詢 | 行為 |
---|---|---|---|
簡單 | 任意 | wifi -luxury |
傳回索引中的所有檔。 具有 「wifi」 一詞的檔或遺漏「豪華」一詞的檔,會比其他檔排名高。 查詢會展開至 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
欄位,而查詢會與 description
欄位相符NOT history
。 中 fieldName:searchExpression
提供的功能變數名稱一律優先於 searchFields
參數,這就是為什麼在此範例中,我們不需要包含在 genre
參數中 searchFields
。
模糊搜尋
模糊搜尋會根據具有類似建構的詞彙尋找相符專案,將詞彙擴充到最多50個符合兩個或更少距離準則的字詞。 如需詳細資訊,請參閱 模糊搜尋。
若要進行模糊搜尋,請使用單一單字結尾的波浪 ~
符號搭配選擇性參數,數位介於0到2之間(預設值),以指定編輯距離。 例如, blue~
或 blue~1
會傳回 blue
、 blues
與 glue
。
模糊搜尋只能套用至字詞,而非以引號括住的片語,但您可以在多部分名稱或片語中個別地將底圖附加至每個字詞。 例如, Unviersty~ of~ Wshington~
會在上比對 University of Washington
。
鄰近搜尋
鄰近搜尋可用來尋找檔中彼此接近的字詞。 在片語結尾插入圖文 ~
符號,後面接著建立鄰近界限的字數。 例如, "hotel airport"~5
在文件中尋找字詞 hotel
,並在 airport
彼此的五個字內。
字詞提升
字詞提升是指如果檔包含提升字詞,則是指相對於不包含字詞的檔,將檔排名更高。 這與評分配置檔不同,因為評分配置檔會提升特定欄位,而不是特定字詞。
下列範例有助於說明差異。 假設有一個評分配置檔可提升特定欄位中的相符專案,例如 musicstoreindex 範例中的內容類型。 字詞提升可用來進一步提升某些搜尋字詞高於其他字詞。 例如, rock^2 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
。
如果您在正則表示式中收到語法錯誤,請檢閱 特殊字元的逸出規則 。 您也可以嘗試不同的客戶端來確認問題是否為特定工具。
萬用字元搜尋
您可以針對多個 () 或單一 (*
?
) 字元通配符搜尋使用一般辨識的語法。 Full Lucene 語法支援前置詞、infix 和後綴比對。
請注意,Lucene 查詢剖析器支援將這些符號與單一字詞搭配使用,而不是片語。
Affix 類型 | 描述和範例 |
---|---|
prefix | 字詞片段在 或 ? 之前* 。 例如,傳回 alphanumeric 或alphabetical 的search=alpha* 查詢表達式。 簡單和完整語法都支援前置詞比對。 |
尾碼 | 字詞片段是在 或 ? 之後* ,使用正斜線來分隔建構。 例如 search=/.*numeric/ 會傳回 alphanumeric 。 |
中綴 | 字詞片段會括住 * 或 ? 。 例如, search=non*al 會傳 non-numerical 回 和 nonsensical 。 |
您可以在一個運算子中結合運算子。 例如,980?2*
在和98052-1234
上98072-1222
比對 ,其中?
會比對單一(必要)字元,並*
符合後續任意長度的字元。
後綴比對需要正則表達式正斜線 /
分隔符。 一般而言,您無法使用 或 ?
符號作為字詞的第一個字元,而不使用 。*
/
也請務必注意, *
在 regex 查詢外部使用 時,的行為會不同。 在 regex 正斜線 /
分隔符之外,是通配符, *
且符合任何一系列的字元,就像在 regex 中一樣 .*
。 例如, search=/non.*al/
會產生與 search=non*al
相同的結果集。
注意
根據規則,模式比對速度很慢,因此您可能會想要探索替代方法,例如邊緣 n-gram 標記化,以在詞彙中建立字元序列的標記。 使用 n-gram 標記化時,索引會比較大,但查詢可能會執行得更快,視您編製索引的模式建構和字元串長度而定。 如需詳細資訊,請參閱 部分字詞搜尋和具有特殊字元的模式。
分析器對通配符查詢的影響
在查詢剖析期間,以前置詞、後綴、通配符或正則表示式形式所制定的查詢會依原狀傳遞至查詢樹狀結構,略 過語彙分析。 只有在索引包含查詢所指定格式的字串時,才會找到相符專案。 在大部分情況下,您需要在編製索引期間分析器,以保留字串完整性,讓部分詞彙和模式比對成功。 如需詳細資訊,請參閱 Azure AI 搜尋查詢中的部分字詞搜尋。
假設您可能想要搜尋查詢terminal*
傳回包含、 termination
和 terminates
等terminate
字詞的結果。
如果您要使用 en.lucene (English Lucene) 分析器,則會套用每個字詞的激進詞幹。 例如,、 terminate
termination
terminates
會將所有令牌化為索引中的令牌termi
。 另一方面,使用通配符或模糊搜尋的查詢中的詞彙完全不會分析,因此不會有符合 terminat*
查詢的結果。
另一方面,Microsoft 分析器(在此案例中為 en.microsoft 分析器)更進階,並使用詞幹化,而不是詞幹分析。 這表示所有產生的令牌都應該是有效的英文單字。 例如, terminate
、 terminates
和 termination
大部分都會留在索引中,而且對於視通配符和模糊搜尋而定的案例,最好選擇 。
評分通配符和 regex 查詢
Azure AI 搜尋會針對文字查詢使用頻率型評分 (BM25)。 不過,對於字詞範圍可能很廣的通配符和 regex 查詢,會忽略頻率因數,以防止排名偏向罕見字詞的相符專案。 所有相符項目都會平均處理通配符和 regex 搜尋。
特殊字元
在某些情況下,您可能會想要搜尋特殊字元,例如 '❤' emoji 或 '€' 符號。 在這種情況下,請確定您使用的分析器不會篩選出這些字元。標準分析器會略過許多特殊字元,將其從索引中排除。
標記化特殊字元的分析器包括空格符分析器,其會將以空格符分隔的任何字元序列視為令牌(因此 ❤
字串會視為令牌)。 此外,Microsoft 英文分析器(“en.microsoft”) 之類的語言分析器會採用 “€” 字串作為令牌。 您可以 測試分析器 ,以查看它針對指定查詢所產生的令牌。
使用 Unicode 字元時,請確定查詢 URL 中已正確逸出符號(例如 ❤
的 會使用逸出序列 %E2%9D%A4+
)。 某些 REST 用戶端會自動執行此轉譯。
優先權 (群組)
您可以使用括弧來建立子查詢,包括括弧語句內的運算符。 例如, motel+(wifi|luxury)
搜尋包含 motel
字詞的檔,以及 wifi
或 luxury
(或兩者)。
欄位群組很類似,但會將群組範圍限定為單一字段。 例如,hotelAmenities:(gym+(wifi|pool))
搜尋和 的wifi
欄位hotelAmenities
gym
, 或 gym
與 pool
。
查詢大小限制
Azure AI 搜尋會對查詢大小和組合施加限制,因為未系結的查詢可能會破壞搜尋服務的穩定性。 查詢大小和組合有限制(子句數目)。 前置詞搜尋的長度以及 regex 搜尋和通配符搜尋的複雜度也有限制。 如果您的應用程式以程式設計方式產生搜尋查詢,建議您以這種方式設計它,使其不會產生未繫結大小的查詢。
如需查詢限制的詳細資訊,請參閱 API 要求限制。