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

發行項
01/19/2024

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

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

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

雖然簡單剖析器是以 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=2020-06-30
{
  "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，搜尋用戶端會在串行化搜尋文字時逸出引號。您的搜尋片語可以傳送為「羅奇汽車旅館」。

根據預設，傳入 search 參數的所有字串都會經歷語彙分析。請確定您已瞭解所使用分析器的令牌化行為。通常，當查詢結果非預期時，可以追蹤到詞彙在查詢時間如何標記化的原因。您可以在特定字串上測試令牌化，以確認輸出。

任何含有一或多個字詞的文字輸入都會被視為查詢執行的有效起點。 Azure AI 搜尋會比對包含任何或所有字詞的檔，包括分析文字期間發現的任何變化。

如同這個聲音一樣簡單，Azure AI 搜尋 服務中有一個查詢執行層面可能會 產生非預期的結果，因為將更多詞彙和運算符新增至輸入字串，而不會減少搜尋結果。此擴充是否實際發生取決於NOT 運算子的包含，結合searchMode參數設定，決定NOT 在或 OR 行為方面AND如何解譯。如需詳細資訊，請參閱 NOT 布爾運算元底下的運算符。

布林運算子

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

字元範例使用方式

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

| pool | ocean 找到 OR 任一字詞時，作業會尋找相符專案。在此範例中，查詢引擎會在包含或 ocean 兩者pool的檔上傳回相符專案。因為 OR 是預設的結合運算子，所以您也可以將其排除在外，因此 pool ocean 相當於 pool | ocean。

字元	範例	使用方式
`+`	`pool + ocean`	`AND`作業。例如， `pool + ocean` 規定文件必須包含這兩個詞彙。
`\|`	`pool \| ocean`	找到 `OR` 任一字詞時，作業會尋找相符專案。在此範例中，查詢引擎會在包含或 `ocean` 兩者`pool`的檔上傳回相符專案。因為 `OR` 是預設的結合運算子，所以您也可以將其排除在外，因此 `pool ocean` 相當於 `pool \| ocean`。
`-`	`pool – ocean`	`NOT`作業會傳回排除字詞之檔的相符專案。 `searchMode`查詢要求上的參數會控制具有 `NOT` 運算符`AND`的字詞是使用ed或`OR`ed搭配查詢中的其他詞彙（假設其他詞彙上沒有布爾運算元）。有效值包括 `any` 或 `all`。 `searchMode=any` 藉由包含更多結果來增加查詢的召回率，且預設 `-` 會解譯為 “OR NOT”。例如， `pool - ocean` 會比對包含字詞 `pool` 的檔，或不包含字詞 `ocean`的檔。 `searchMode=all` 藉由包含較少的結果來增加查詢的精確度，且預設 `-` 會解譯為 “AND NOT”。例如，使用 `searchMode=any`，查詢 `pool - ocean` 會比對包含「pool」一詞的檔，以及不包含「ocean」一詞的所有檔。這可以說是 `-` 運算子更直覺的行為。因此，如果您想要優化搜尋精確度而非召回率，而且您的使用者經常在`-`搜尋中使用運算子，您應該考慮使用 `searchMode=allsearchMode=any` 而不是。在 `searchMode` 決定設定時，請考慮各種應用程式中查詢的用戶互動模式。搜尋資訊的使用者更有可能在查詢中包含操作員，而不是具有更多內建導覽結構的電子商務網站。

-

pool – ocean

NOT作業會傳回排除字詞之檔的相符專案。

searchMode查詢要求上的參數會控制具有 NOT 運算符AND的字詞是使用ed或ORed搭配查詢中的其他詞彙（假設其他詞彙上沒有布爾運算元）。有效值包括 any 或 all。

searchMode=any 藉由包含更多結果來增加查詢的召回率，且預設 - 會解譯為 “OR NOT”。例如， pool - ocean 會比對包含字詞 pool 的檔，或不包含字詞 ocean的檔。

searchMode=all 藉由包含較少的結果來增加查詢的精確度，且預設 - 會解譯為 “AND NOT”。例如，使用 searchMode=any，查詢 pool - ocean 會比對包含「pool」一詞的檔，以及不包含「ocean」一詞的所有檔。這可以說是 - 運算子更直覺的行為。因此，如果您想要優化搜尋精確度而非召回率，而且您的使用者經常在-搜尋中使用運算子，您應該考慮使用 searchMode=allsearchMode=any 而不是。

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

前置詞查詢

針對「開頭」查詢，新增後綴運算元（*）作為字詞其餘部分的佔位元。前置詞查詢必須以至少一個英數位元開頭，才能新增後綴運算符。

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

類似於篩選條件，前置詞查詢會尋找完全相符的專案。因此，沒有相關性評分（所有結果都會收到 1.0 的搜尋分數）。請注意，前置詞查詢可能會變慢，特別是索引很大且前置詞包含少量字元時。邊緣 n-gram Tokenization 之類的替代方法可能會執行得更快。使用前置詞搜尋的字詞不能超過 1000 個字元。

簡單語法僅支援前置詞比對。針對與字詞結尾或中間的後綴或虛字元比對，請使用完整的 Lucene 語法進行通配符搜尋。

逸出搜尋運算符

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

如果這些字元是索引中標記的一部分，請在查詢中以單一反斜杠（\）作為前置詞，以逸出它。例如，假設您已使用自定義分析器進行整個詞彙標記化，且您的索引包含字串 “Luxury+Hotel”。若要取得此令牌的完全相符專案，請插入逸出字元： search=luxury\+hotel。

為了簡化較典型的案例，此規則有兩個例外狀況，其中不需要逸出：

只有當 NOT 運算符 - 是空格符之後的第一個字元時，才需要逸出。 -如果出現在中間（例如，在中3352CDD0-EF30-4A2E-A512-3B30AF40F3FD），您可以略過逸出。
後綴運算子 * 只有在空格符前的最後一個字元才需要逸出。 *如果出現在中間（例如，在中4*4=16），則不需要逸出。

注意

根據預設，標準分析器會在語彙分析期間刪除和中斷連字元、空格符、連字元和其他字元上的單字。如果您需要特殊字元保留在查詢字串中，您可能需要在索引中保留這些字元的分析器。某些選擇包括 Microsoft 自然語言分析器，可保留連字元字組，或自定義分析器以取得更複雜的模式。如需詳細資訊，請參閱部分字詞、模式和特殊字元。

在 URL 中編碼不安全和保留字元

確定所有不安全和保留的字元都會在URL中編碼。例如，'#' 是不安全的字元，因為它是URL中的片段/錨點標識符。如果在網址中使用，字元必須編碼為 %23 。 '&' 和 '=' 是保留字元的範例，因為它們會分隔參數，並在 Azure AI 搜尋服務中指定值。如需詳細資訊，請參閱 RFC1738：統一資源定位器（URL）。

不安全的字元為 " ` < > # % { } | \ ^ ~ [ ]。保留字元為 ; / ? : @ = + &。

特殊字元

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

如果您需要特殊字元表示法，您可以指派保留它們的分析器：

空格分析器會將空格符分隔的任何字元序列視為標記（因此'❤' emoji 會被視為令牌）。
語言分析器，例如 Microsoft English 分析器（en.microsoft），會採用『$』或 '€' 字串作為令牌。

如需確認，您可以測試分析器，以查看為指定的字串產生哪些令牌。如您所預期，您可能不會從單一分析器取得完整令牌化。因應措施是建立多個包含相同內容的欄位，但使用不同的分析器指派（例如、description_endescription_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 搜尋中的全文搜索，以瞭解查詢處理階段和文字分析的影響。

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