Azure DocumentDB 全文搜尋是一個以 BM25 評分為基礎、由分析器驅動的搜尋引擎,透過與 MongoDB 相容的原始操作提供。 它依相關性排序結果,容忍使用者的錯字,並結合文本匹配與結構化條件,無需獨立搜尋叢集。 自訂分析器支援前綴匹配、階層識別碼及語言專屬分析。
啟用全文搜尋
在建立搜尋索引或執行$search查詢之前,請先在您的 Azure DocumentDB 叢集上啟用全文搜尋功能。 請選擇下列其中一個方法。
Azure 入口網站
- 登入 Azure 入口網站並開啟您的 Azure DocumentDB 叢集。
- 在 「設定」下,選擇 「功能」。
- 選擇 全文搜尋,初始狀態為 關閉。
- 在右側開啟的窗格中,檢視功能資訊,然後選擇「 啟用」。
Azure CLI
在安裝 Azure CLI 的 Bash 中執行以下指令。 將資源 ID 佔位符替換為您叢集中的實際值。 PATCH 指令會保留從叢集讀取的預覽特性,且恰好包含一次 FullTextSearch。
set -euo pipefail
az login
RESOURCE_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>"
URL="https://management.azure.com${RESOURCE_ID}?api-version=2024-07-01"
# Review the current provisioning state and preview features.
az rest --method get --url "$URL" \
--query '{state:properties.provisioningState,features:properties.previewFeatures}' \
--output json
# Preserve other preview features and add FullTextSearch exactly once.
BODY=$(az rest --method get --url "$URL" \
--query '{properties: {previewFeatures: [properties.previewFeatures[?@ != `"FullTextSearch"`] || `[]`, [`"FullTextSearch"`]][]}}' \
--output json)
az rest --method patch --url "$URL" --body "$BODY"
# Check the updated configuration.
az rest --method get --url "$URL" \
--query '{state:properties.provisioningState,features:properties.previewFeatures}' \
--output json
Terraform
對於現有叢集,請使用 AzAPI 提供者更新 properties.previewFeatures,而不重新建立叢集。 以下範例使用 AzAPI 2.x,並在新增 FullTextSearch前讀取目前的清單。
terraform {
required_providers {
azapi = {
source = "Azure/azapi"
version = "~> 2.0"
}
}
}
provider "azapi" {}
variable "cluster_resource_id" {
type = string
description = "The resource ID of the existing Azure DocumentDB cluster."
}
data "azapi_resource" "cluster" {
type = "Microsoft.DocumentDB/mongoClusters@2024-07-01"
resource_id = var.cluster_resource_id
response_export_values = {
preview_features = "properties.previewFeatures || `[]`"
}
}
resource "azapi_update_resource" "full_text_search" {
type = "Microsoft.DocumentDB/mongoClusters@2024-07-01"
resource_id = var.cluster_resource_id
body = {
properties = {
previewFeatures = distinct(concat(
data.azapi_resource.cluster.output.preview_features,
["FullTextSearch"]
))
}
}
}
設定 cluster_resource_id 為您的叢集資源 ID。 執行 terraform init、檢視 terraform plan、然後執行 terraform apply。
如果有其他 Terraform 資源管理叢集,請確保它沒有同時管理此屬性。 對於資源 azurerm_mongo_cluster,當 AzAPI 擁有該屬性時,將 preview_features 新增至其 lifecycle.ignore_changes 清單。 檢視計畫,如果計畫建議更換叢集,就不要繼續。
Bicep
更新管理叢集的範本。 新增一個陣列參數,包含您想保留的所有其他預覽功能:
param otherPreviewFeatures array = []
在您現有properties資源的Microsoft.DocumentDB/mongoClusters物件中,設定:
previewFeatures: union(otherPreviewFeatures, [
'FullTextSearch'
])
保持叢集的其他資源屬性不變。 這是一個屬性片段,而非獨立範本。 Bicep 會以所提供的功能清單取代預覽功能清單;它不會自動讀取並合併現有功能。
請使用 az deployment group what-if 檢視部署,然後使用 az deployment group create 部署更新後的範本。
Important
使用任一方法啟用全文搜尋後,請等待 10 分鐘後再建立搜尋索引或執行查詢。 在資源設定中看到 FullTextSearch 並不代表啟用已經完成。
目前可用的內容
| Capability | 運算子或原語 |
|---|---|
| BM25 關鍵字搜尋 | $search + text |
| 模糊(可容忍錯字)搜尋 |
$search
+
text 與 fuzzy.maxEdits |
| 片語搜尋與鄰近匹配 | $search + phrase + slop |
| 前綴搜尋 | 具 edgeGram 斷詞器或詞元篩選器的自訂分析器 |
| 階層式識別碼搜尋 | 帶有 pathHierarchy 分詞器的自訂分析器 |
| 自訂文字分析 | 用於正規化、詞幹提取、停用詞及模式處理的有序分詞器與 token 過濾管線 |
| 語言專屬分析 | 中文、日文、韓文及泰文分析器與分詞器 |
| 多欄位識別碼搜尋 | 一個具有多個 mappings.fields 項目與明確查詢路徑的索引 |
| 對同一欄位進行的替代分析 | 命名 multi 映射 |
| 結構化與文字搜尋 |
具有 equals、boolean、date、number 和 compound 的 token、in、exists 以及 range 對應 |
| 內嵌排序與 top-N 檢索 |
$search.sort 在映射標量場與下游 $limit 推下 |
| 混合關鍵字 + 向量檢索 | 以 RRF 結合分開的關鍵字與 cosmosSearch 查詢 |
目前限制
以下功能目前不支援:
- 動態映射、動態型別集合、字元篩選器、同義詞定義,以及
storedSource。 -
compound.minimumShouldMatch以及自訂評分提升。 - 即
autocomplete、queryString、 及near運算子。 -
wildcard裡面的regex和$search運算子不被支援。 -
$searchMeta階段、$$SEARCH_META變數、計數、分面和醒目提示。 -
objectId、uuid、embeddedDocument、autocomplete及geo對應類型。
在 混合搜尋 中使用用戶端或彙總管線的 RRF 範例,將關鍵字與向量結果融合在一起。 目前 $rankFusion 階段尚未支援。
關於服務範圍的參考資料,包括搜尋索引生命週期限制,請參閱 全文搜尋限制。
Azure DocumentDB 全文搜尋的運作方式
Azure DocumentDB 中的搜尋索引是與文件索引分開的物件。 你用 createSearchIndexes 資料庫命令建立它,不是用 db.<coll>.createIndex({ field: "text" }),也不是用 createIndexes 和 "textSearch" 鍵類型。 索引定義宣告哪些欄位可搜尋、其類型,以及在索引時與查詢時所使用的分析管線。
查詢作為聚合管線的第一階段,使用 operator 執行 $search 。 預設情況下,引擎會回傳依相關性排序的文件,您可以在下游 { $meta: "searchScore" } 階段透過 $project 查看其相關性。 改用內嵌 sort 來依索引標量欄位排序結果。 本節範例使用 mongosh 風格的 MongoDB Shell 語法,但相同操作適用於任何相容 MongoDB 的驅動程式。
每一個 Azure DocumentDB 全文搜尋查詢都適用四項規則:
-
依名稱指定索引,在
$search內使用index: "<name>"。 若省略,查詢會鎖定名為default的索引;不會選擇任意索引。 所有查詢路徑必須存在於所選索引中。 -
$search總是 聚合管線的第一階段,因此搜尋索引會在其他運算子執行前先縮小候選集合範圍。 - 在
limit內沒有$search或count欄位。 使用下游{ $limit: N }階段限制結果。 - 將文字與結構化條件與
compound結合。 在映射標量場上使用equals、range、exists和in。 對於需要下游$match的條件,請在最後的$limit之前套用它,讓限制套用於符合條件的結果。
設定 dynamic: false 或省略 dynamic 會使用靜態映射。 每個可搜尋欄位都必須明確宣告於 mappings.fields。 設定dynamic: true會導致索引建立失敗,並顯示 mappings.dynamic is not supported in search indexes yet.。如果缺少 mappings.fields 或其為空,索引建立也會失敗。
單一搜尋索引可涵蓋多個文字、識別碼、數字、日期、布林值及巢狀文件欄位。
何時使用 Azure DocumentDB 全文搜尋功能
| Mode | 最適合用於 | 需要搜尋索引 | 依 BM25 排名 |
|---|---|---|---|
$regex |
與欄位值進行模式比對,且不需相關性排序。 效能取決於模式和可用的索引。 | No | No |
$search + text |
標準關鍵字搜尋,包括文字、描述、標題。 | Yes | Yes |
$search + text + fuzzy |
輸入即搜尋、面向使用者的目錄或日誌搜尋,適用於常有錯字的情況。 | Yes | Yes |
$search + phrase |
多字產品名稱、引用的使用者輸入、詞序很重要的錯誤訊息字串。 | Yes | Yes |
客製化分析器+ text |
前綴查找、階層式識別碼、正規化文字,以及語言專屬分析。 | Yes | Yes |
$search + compound |
在同一查詢中取得精確類別、可用性、數字或日期條件的文字檢索。 | Yes | 文字子句有助於提升相關性 |
| 混合型(BM25 + 向量) | 將自然語言查詢與精確識別碼混合的目錄或知識庫搜尋;RAG 擷取。 | 是(BM25 + 向量) | 融合分數 |
全文搜尋與文字索引
$text運算子與{ field: "text" }索引已正式推出。 全文搜尋使用獨立的搜尋索引與 $search 查詢,且仍為預覽版。 啟用預覽不會變更現有的文字索引或 $text 查詢。
若要評估預覽全文搜尋,請建立獨立的搜尋索引並使用 $search 查詢。 您不需要將現有的 $text 工作負載遷移,即可評估此預覽版。