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

發行項
10/16/2024

針對全文檢索搜尋案例，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 一詞。

字元範例使用方式

+ pool + ocean AND 作業。例如，pool + ocean 要求文件必須包含這兩個詞彙。

| pool | ocean OR 運算會在找到任一字詞時，尋找相符項目。在範例中，查詢引擎會針對包含 pool 和 (或) ocean 的文件傳回相符項目。 OR 是預設的連接運算子，所以您也可以將其省略，因此 pool ocean 相當於 pool | ocean。

字元	範例	使用方式
`+`	`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`。在決定 `searchMode` 設定時，請考慮各種應用程式中查詢的使用者互動模式。搜尋資訊的使用者比較有可能在查詢中包含運算子，而不是具有更多內建導覽結構的電子商務網站。

-

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。

在決定 searchMode 設定時，請考慮各種應用程式中查詢的使用者互動模式。搜尋資訊的使用者比較有可能在查詢中包含運算子，而不是具有更多內建導覽結構的電子商務網站。

前置詞查詢

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

字元	範例	使用方式
`*`	`lingui*` 將會比對「linguistic」或「linguini」	星號 (`*`) 代表任意長度的一或多個字元，忽略大小寫。

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

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

逸出搜尋運算子

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

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

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

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

注意

根據預設，標準分析器會在語彙分析期間刪除和中斷連字號、空白字元、連字號和其他字元上的單字。如果您需要在查詢字串中保留特殊字元，則可能需要會在索引中保留特殊字元的分析器。選項包括 Microsoft 自然語言分析器 (其會保留有連字號的字組)，或可處理更複雜模式的自訂分析器。如需詳細資訊，請參閱部分字詞、模式和特殊字元。

為 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 搜尋中的全文檢索搜尋，以了解查詢處理階段和文字分析的影響。

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

共用方式為