Azure DocumentDB 中的全文搜尋

Azure DocumentDB 全文搜尋是一個以 BM25 評分為基礎、由分析器驅動的搜尋引擎,透過與 MongoDB 相容的原始操作提供。 它依相關性排序結果,容忍使用者的錯字,並結合文本匹配與結構化條件,無需獨立搜尋叢集。 自訂分析器支援前綴匹配、階層識別碼及語言專屬分析。

在建立搜尋索引或執行$search查詢之前,請先在您的 Azure DocumentDB 叢集上啟用全文搜尋功能。 請選擇下列其中一個方法。

Azure 入口網站

  1. 登入 Azure 入口網站並開啟您的 Azure DocumentDB 叢集。
  2. 在 「設定」下,選擇 「功能」。
  3. 選擇 全文搜尋,初始狀態為 關閉。
  4. 在右側開啟的窗格中,檢視功能資訊,然後選擇「 啟用」。

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 或其為空,索引建立也會失敗。

單一搜尋索引可涵蓋多個文字、識別碼、數字、日期、布林值及巢狀文件欄位。

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 工作負載遷移,即可評估此預覽版。