針對全文搜尋情境，Azure AI 搜尋服務 實作兩種基於 Lucene 的查詢語言，每種語言都對應於查詢解析器。 Simple Query Parser 是預設的。 它涵蓋常見的使用案例，並嘗試解讀即使請求不完美。 另一個解析器是 Lucene Query Parser ，支援更進階的查詢結構。
本文為簡單查詢解析器的查詢語法參考資料。
兩種解析器的查詢語法適用於傳入search的參數中的查詢表達式，不要與OData 語法混淆，後者在同一個請求中有自己針對filter和orderby表達式的語法和規則。
雖然簡單解析器基於 Apache Lucene 簡單查詢解析器類別，但其在 Azure AI 搜尋服務 中的實作排除了模糊搜尋。 如果你需要 模糊搜尋，可以考慮使用完整 Lucene 查詢語法。
範例（簡單語法）
此範例展示了一個簡單的查詢，藉由 "queryType": "simple" 和有效語法來區分。 雖然查詢類型設定於下方的列表中，但它是預設值，除非要從其它類型回到預設，否則不必特別設定。 以下範例是對獨立詞彙的搜尋，要求所有匹配文件都包含「pool」。
POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2025-09-01
{
"queryType": "simple",
"search": "budget hotel +pool",
"searchMode": "all"
}
此 searchMode 參數在此範例中相關。 當查詢中出現布林運算子時，通常應設定 searchMode=all 以確保 所有 條件都符合。 否則，你可以使用偏好回憶而非精確度的預設 searchMode=any 設定。
更多範例請參見 簡單查詢語法範例。 關於查詢請求及參數的詳細資訊，請參見搜尋文件（REST API）。
關鍵字搜尋詞彙與片語
傳遞給 search 參數的字串可以包含任何支援語言的術語或片語、布林運算子、優先順序運算子、「以」開頭查詢的萬用字元或前綴字元、跳脫字元，以及 URL 編碼字元。 這個 search 參數是可選的。 未指定時，搜尋（search=* 或 search=" "）會以任意（未排序）順序回傳前50份文件。
詞彙搜尋是一種對一個或多個詞彙的查詢，其中任何一個詞都被視為匹配。
短語搜尋是一個以引號
" "包圍的精確詞組。 例如，雖然Roach Motel（不加引號）會搜尋包含Roach和/或Motel任意順序的文件，"Roach Motel"（帶引號）只會將包含該整個片語的文件按該順序匹配（詞彙分析仍適用）。
根據你的搜尋客戶，你可能需要在詞語搜尋中省略引號。 例如，在 POST 請求中，請求主體中對 的 "Roach Motel" 短語搜尋可能會指定為 "\"Roach Motel\""。 如果你使用 Azure SDK，搜尋客戶端在序列化搜尋文字時會跳脫引號。 您的搜尋詞可以寄出為「Roach Motel」。
預設情況下，所有參數中 search 傳遞的字串都會進行詞彙分析。 務必了解你使用的分析器的標記化行為。 通常，當查詢結果出乎意料時，原因可追溯到查詢時詞彙的標記方式。 你可以 測試特定字串的分詞以確認輸出。
任何包含一個或多個詞彙的文字輸入，都被視為查詢執行的有效起點。 Azure AI 搜尋服務 會比對包含任何或全部術語的文件，包括在文本分析過程中發現的任何變異。
雖然聽起來很直接，但 Azure AI 搜尋服務 查詢執行中有一個面向是might會產生意想不到的結果，隨著輸入字串中加入更多詞彙和運算子，搜尋結果反而會增加而非減少。 這種擴展是否確實發生，取決於是否包含一個 NOT 運算子，以及與searchMode 參數設定如何結合，這決定了 NOT 是以AND 或OR 行為進行解釋。 欲了解更多資訊，請參閱NOT布林運算子下的運算元。
布林運算元
你可以在查詢字串中嵌入布林運算子，以提升匹配的精確度。 在簡單語法中，布林運算子是以字元為基礎的。 文字運算子，例如單字 AND，則不被支援。
| 角色 | 範例 | 使用情況 |
|---|---|---|
+ |
pool + ocean |
手術 AND 。 例如， pool + ocean 規定文件必須包含這兩個詞彙。 |
| |
pool | ocean |
當找到任一項時，OR 操作即視為匹配。 在範例中，查詢引擎會對包含其中一 pool 或 ocean 兩者的文件回傳匹配。 因為 OR 是預設的合取運算子，你也可以省略它，使得 pool ocean 等價 pool | ocean於 。 |
- |
pool – ocean |
NOT操作在不包含該術語的文件上回傳匹配。
searchMode查詢請求的參數控制一個帶有NOT運算子的詞彙是否與查詢中其他詞組AND或是OR(假設其他詞沒有布林運算子)。 有效的值包括 any 或 all。
searchMode=any 透過包含更多結果來提升查詢的召回率，且預設 - 會被解讀為「OR NOT」。 例如，pool - ocean會匹配包含pool這個詞或不包含ocean這個詞的文件。
searchMode=all 透過減少結果數量來提升查詢的精確度，且預設 - 會被解讀為「AND NOT」。 例如，使用searchMode=any，查詢pool - ocean會匹配包含「pool」這個詞的文件，以及所有不含「ocean」這個詞的文件。 這對操作員來說，可以說是更直覺的行為 - 。 因此，如果你想優化搜尋的精準度而非召回率，應該考慮使用 searchMode=all 代替 searchMode=any ， 而 使用者在搜尋時經常使用 Operator - 。 在決定某個 searchMode 選項時，請考慮各種應用程式中查詢的使用者互動模式。 搜尋資訊的使用者更可能在查詢中包含操作員，與擁有更多內建導覽結構的電子商務網站不同。 |
前綴查詢
對於「以」開頭的查詢，請加上後綴運算子（*）作為該詞剩餘部分的佔位符。 前綴查詢必須至少以一個純文字字元開頭，才能加上後綴運算子。
| 角色 | 範例 | 使用情況 |
|---|---|---|
* |
lingui* 在「語言學」或「linguini 義大利麵」中會相符 |
星號（*）代表一個或多個任意長度的字元，忽略大小寫。 |
與過濾器類似，前綴查詢尋找精確匹配。 因此，沒有相關性評分（所有結果的搜尋分數均為 1.0）。 請注意，前綴查詢可能較慢，尤其是當索引較大且前綴字元數較少時。 另一種方法論，如邊 n-gram 分詞化，可能會更快。 使用前綴搜尋的詞彙不能超過 1000 個字元。
簡單語法僅支援前綴匹配。 要執行詞尾或詞中間的後綴或中綴匹配，請使用完整的 Lucene 語法執行萬用字元搜尋。
逃逸搜尋運算子
在簡單語法中，搜尋運算子包含以下字元： + | " ( ) ' \
如果這些字元中有任何屬於索引中的標記，請在查詢中以一個反斜線\（）作為轉義。 舉例來說，假設你使用了自訂的整詞分詞分析器，而你的索引包含字串「Luxury+Hotel」。 要精確匹配此符號，請插入一個轉義符：search=luxury\+hotel。
為了讓較常見的情況更簡單，這條規則有兩個例外，不需要逃脫：
NOT 運算子
-只有在空白字符之後的第一個字元才需要跳脫。 如果 出現-在中間（例如在3352CDD0-EF30-4A2E-A512-3B30AF40F3FD），你可以跳過逃脫。只有當字尾運算子
*位於空白前的最後一個字元時，才需要跳脫。 若 出現*在中間（例如，在4*4=16中），則無需逃脫。
註
預設情況下，標準分析器在進行
在 URL 中編碼不安全和保留的字元
確保所有不安全且保留字元都編碼在 URL 中。 例如，「#」是不安全的字元，因為它是 URL 中的片段/錨點識別碼。 若在 URL 中使用字元，必須編碼為 %23 。 '&' 和 '=' 是保留字元的範例，因為它們在 Azure AI 搜尋服務 中界定參數並指定值。 欲了解更多資訊，請參閱RFC1738：統一資源定位器（URL）。
不安全字元為 " ` < > # % { } | \ ^ ~ [ ]。 保留字元為 ; / ? : @ = + &。
特殊角色
特殊字元可以是貨幣符號如「$」或「€」，或是表情符號。 許多分析器，包括預設標準分析器，會在索引時排除特殊字元，這表示它們不會被顯示在你的索引中。
如果你需要特殊的字元表示，可以指派一個分析器來保留這些字元：
空白分析器會將任何以空白分隔的字元序列視為標記（例如「」❤表情符號會被視為標記）。
語言分析器，例如Microsoft英語分析器（
en.microsoft），會將「$」或「€」字串作為標記。
為了確認，你可以 測試分析 器，看看某個字串產生了哪些標記。 如你所料，單一分析器可能無法完整地標記化。 一個變通方法是建立多個欄位，這些欄位包含相同內容，但使用不同的分析器進行處理（例如，將description_en、description_fr等配置為不同語言的分析器）。
使用 Unicode 字元時，請確保查詢網址中的符號正確轉義，例如 '❤' 會使用轉義序列 %E2%9D%A4+。 有些網頁客戶端會自動完成此轉換。
優先順序（群組）
你可以用括號來建立子查詢，包括括號內的運算子。 例如， motel+(wifi|luxury) 會搜尋包含「motel」這個詞和「wifi」或「luxury」（或兩者都有）的文件。
查詢大小限制
如果您的應用程式以程式方式產生搜尋查詢，我們建議設計成不會產生無限大小的查詢。
對於 GET 來說，URL 長度不能超過 8 KB。
對於 POST（及任何其他請求），請求內容包含
search及其他參數如filterorderby和 ，最大大小為 16 MB。 其他限制包括：- 搜尋子句的最大長度為 100,000 字元。
- 中
search（以 AND 或 OR 分隔的表達式）中子句數最多為 1024 個。 - 前綴搜尋的最大字元數為 1000 個字元。
- 查詢中每個詞的大小也有大約 32 KB 的限制。
欲了解更多查詢限制資訊，請參閱 API 請求限制。
下一步
如果你打算用程式化方式建構查詢，請參考 Azure AI 搜尋服務
您也可以參考以下文章，進一步了解查詢建構：
- 簡單搜尋的查詢範例
- 完整 Lucene 搜尋的查詢範例
- 搜尋文件 REST API
- Lucene 查詢語法
- 篩選與選擇（OData）表達式語法