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

針對全文檢索搜尋案例，Azure AI 搜尋會實作兩種 Lucene 型查詢語言，每個語言都與查詢剖析器一致。 簡單查詢剖析器是預設項目。 這涵蓋常見的使用案例，並嘗試解譯要求，即使這並未撰寫完成也一樣。 另一個剖析器是 Lucene 查詢剖析器，這支援更進階的查詢建構。

本文是簡單查詢剖析器查詢語法參考。

這兩個剖析器的查詢語法適用於在查詢要求的 search 參數中傳遞的查詢表達式，而不是與 OData 語法混淆，而 filter 和 orderby 運算式在相同要求中有各自的語法和規則。

雖然簡單的剖析器是以 Apache Lucene Simple Query Parser 類別為基礎，但其在 Azure AI 搜尋中的實作會排除模糊搜尋。 如果您需要模糊搜尋，請考慮改用替代的完整 Lucene 查詢語法。

範例 (簡單語法)

此範例示範簡單的查詢，其與 "queryType": "simple" 和有效的語法區分。 雖然查詢類型設定如下，但除非您從替代類型還原，否則該類型為預設值且可省略。 下列範例是獨立字詞的搜尋，並要求所有相符的文件都包含「pool」。

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2024-07-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

searchMode 參數在此範例中具有相關性。 每當在查詢上使用布林運算子時，您通常都應設定 searchMode=all，以確保所有的準則均相符。 否則，您可以使用偏好召回率勝於精確度的預設值 searchMode=any。

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

關鍵字搜尋字詞和片語

傳遞至 search 參數的字串可以包含任何支援語言、布林運算子、優先順序運算子、萬用字元或前置詞字元的字詞或片語，適用於「starts with」查詢、逸出字元和 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 搜尋服務中執行查詢時，有一個層面可能會產生非預期的結果，會隨著在輸入字串中新增字詞和運算子而增加 (而非減少) 搜尋結果。 是否進行此擴充實際上取決於是否加入了 NOT 運算子，以及決定如何對 NOT 解譯其 AND 或 OR 行為的 searchMode 參數設定。 如需詳細資訊，請參閱布林運算子下的 NOT 運算子。

布林運算子

您可以在查詢字串中內嵌布林運算子，以提升相符項目的精確度。 在簡單語法中，布林運算子是以字元為基礎。 不支援文字運算子，例如 AND 一詞。

前置詞查詢

對於「開頭」查詢，請將後置詞運算子新增 (*) 為字詞其餘部分的預留位置。 前置詞查詢必須以至少一個英數位元開頭，才能新增尾碼運算子。

與篩選類似，前置詞查詢會尋找完全相符的項目。 因此，沒有任何相關性評分 (所有結果都會收到 1.0 的搜尋分數)。 請注意，前置詞查詢可能會變慢，特別是當索引巨大且前置詞僅包含少量字元時。 邊緣 n-gram 權杖化之類的替代方法可能會執行地更快。 使用前置詞搜尋的字詞不能超過 1000 個字元。

簡單語法僅支援前置詞比對。 若要針對字詞結尾或中間的後置詞或字尾比對，請使用完整的 Lucene 語法進行萬用字元搜尋。

逸出搜尋運算子

在簡單語法中，搜尋運算子包含下列字元：+ | " ( ) ' \

如果這些字元是索引中權杖的一部分，請在查詢中加上單一反斜線 (\) 前置詞，以將其逸出。 例如，假設您使用自訂分析器對整個詞彙進行標記化，而您的索引包含字串「Luxury+Hotel」。 若要取得此權杖的完全相符項目，請插入逸出字元：search=luxury\+hotel。

若要簡化一般案例下的作業，此規則有兩個不需使用逸出的例外情形：

• NOT 運算子 - 只有在作為空白字元後面的第一個字元時，才需要逸出。 若 - 位於字詞的中間 (例如 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD 中)，則您可以略過逸出。

• 尾碼運算子 * 只有在作為空白字元前的最後一個字元時，才需要逸出。 若 * 位於字詞的中間 (例如 4*4=16 中)，則無須逸出。

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

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

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

特殊字元

特殊字元的範圍可以從「$」或「€」等貨幣符號到表情符號。 許多分析器包括預設標準分析器，都會在編制索引期間排除特殊字元，這表示這些字元不會在您的索引中表示。

如果您需要特殊字元標記法，您可以指派保留這些字元的分析器：

• 空白字元分析器會將空白字元分隔的任何字元序列視為權杖 (因此「❤」表情符號會被視為權杖)。

• 此外，Microsoft 英文分析器 (en.microsoft) 之類的語言分析器會將「$」或「€」字串作為權杖。

如需確認，您可以測試分析器，以查看系統會為指定的字串產生哪些權杖。 如您所預期，您可能無法從單一分析器取得完整權杖化。 因應措施是建立包含相同內容的多個欄位，但使用不同的分析器指派 (例如，description_en、description_fr，以此類推，適用於語言分析器)。

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

優先順序 (分組)

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

查詢大小限制

如果您的應用程式以程式設計方式產生搜尋查詢，建議您依照此方式設計，以避免產生無大小限制的查詢。

• 針對 GET，URL 的長度不能超過 8 KB。

• 對於 POST (和任何其他要求) ，其中要求本文包含 search 和其他參數 (例如 filter 和 orderby)，則大小上限為 16 MB。 其他限制包括：

  • 搜尋子句的最大長度為 100,000 個字元。
  • search 中的子句數目上限 (以 AND 或 OR 分隔的運算式) 為 1024。
  • 前置詞搜尋的搜尋字詞大小上限為 1000 個字元。
  • 此外，查詢中任何個別字詞的大小也有約 32 KB 的限制。

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

下一步

如果您要以程式設計方式建構查詢，請檢閱 Azure AI 搜尋中的全文檢索搜尋，以了解查詢處理階段和文字分析的影響。

您也可以檢閱下列文章，以深入了解查詢建構：

• 簡單搜尋的查詢範例
• 完整 Lucene 搜尋的查詢範例
• 搜尋文件 REST API
• Lucene 查詢語法
• 篩選並選取 (OData) 運算式語法