備註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
Azure Cosmos DB for NoSQL 索引器會從 Azure Cosmos DB for NoSQL 匯入內容,並使其可於 Foundry IQ(Azure AI 搜尋服務)中搜尋。
本文提供 Cosmos DB 的特定資訊,用於補充建立索引子。 它會使用 Azure 入口網站 和 REST API 來示範所有索引器通用的三部分工作流程:建立數據源、建立索引、建立索引器。 提交建立索引子要求時會擷取資料。
由於術語容易令人困惑,值得一提的是,Azure Cosmos DB 索引與 Foundry IQ 索引是不同的操作。 在 Foundry IQ 中進行索引,會在您的 Foundry IQ 服務上建立並載入搜尋索引。
先決條件
Azure Cosmos DB 帳戶、資料庫、容器和項目。 同時使用相同區域來使用Foundry IQ和Azure Cosmos DB,以降低延遲並避免頻寬費用。
Azure Cosmos DB 集合上的自動索引編製原則,已設定為一致。 這是預設組態。 不建議延遲索引編製,其可能會導致資料遺失。
讀取權限。 「完整存取」連接字串 包含一個金鑰,可授予內容存取權,但如果您使用身份(Microsoft Entra ID),請確保 Foundry IQ 服務管理身份同時被指派為 Cosmos DB 帳戶讀取角色與 Cosmos DB 內建資料讀取者角色。
若要完成本文中的範例,您需要 Azure 入口網站 或 REST 用戶端。 如果您是使用 Azure 入口網站,請確定已啟用所有公用網路的存取權。 建立 Cosmos DB 索引子的其他方法包括 Azure SDK。
嘗試使用範例數據
使用這些指示,在 Cosmos DB 中建立容器和資料庫以供測試之用。
從 GitHub 下載 HotelsData_toCosmosDB.json,在 Cosmos DB 中建立一個容器,其中包含範例飯店資料集的子集。
登入 Azure 入口網站,並在 Cosmos DB 上建立帳戶、資料庫和容器。
在 Cosmos DB 中,選擇 Data Explorer,並為新容器提供以下數值。
房產 價值觀 資料庫 新建 資料庫識別碼 hotelsdb 跨容器共用輸送量 不要選取 容器識別碼 旅館 資料分割索引鍵 /HotelId 容器輸送量 (自動調整) Autoscale 容器最大 RU/秒 1000 在 [數據總管] 中,展開 hotelsdb 和 hotels,然後選取 [專案]。
選取 [上傳項目],然後選取您從 GitHub 下載的 HotelsData_toCosmosDB.json 檔案。
以滑鼠右鍵按一下 [項目],然後選取 [新增 SQL 查詢]。 預設查詢為
SELECT * FROM c。選取 [執行查詢] 以執行查詢並檢視結果。 您應該有 50 份旅館文件。
既然有了容器,您就可以使用 Azure 入口網站、REST 用戶端或 Azure SDK 來編製資料索引。
[描述] 欄位提供最詳細的內容。 你應該將此欄位鎖定為全文搜尋及可選的向量查詢。
使用 Azure 入口網站
你可以使用 匯入資料 精靈,自動從 SQL 資料庫的表格或檢視進行索引。
啟動精靈。
在 [連線至您的資料] 上,選取或確認資料來源為 [Azure Cosmos DB] 或 [NoSQL 帳戶]。
資料來源名稱指的是 Foundry IQ 中的資料來源連線物件。 你的資料來源名稱是透過精靈工作流程結尾指定的自訂前綴自動產生的。
指定資料庫名稱和集合。 查詢是選擇性的。 如果您有階層式資料,而且想要匯入特定配量,這會很有用。
指定驗證方法,可以是受控識別或內建 API 金鑰。 如果您未指定受控識別連線,Azure 入口網站會使用金鑰。
如果您設定 Foundry IQ 使用管理身份,並在 Cosmos DB 上建立角色指派,授予 Cosmos DB Account Reader 及 Cosmos DB 內建資料閱讀器對該身份的權限,您的索引器即可使用 Microsoft Entra ID 與角色連接至 Cosmos DB。
你可以指定變更與刪除追蹤的選項。
變更偵測 預設透過
_ts欄位(時間戳記)支援。 如果您利用使用範例資料進行嘗試中所述的方法上傳內容,則會使用_ts欄位建立集合。刪除偵測需要您在集合中預先存在一個頂層欄位,該欄位可用作軟刪除標誌。 其應為布林值欄位 (您可以將其命名為 IsDeleted)。 指定
true做為虛刪除值。 在搜尋索引中,新增名為 IsDeleted 的對應搜尋欄位,設定為可擷取和可篩選。繼續進行其餘步驟以完成精靈:
使用 REST API
本節示範建立數據源、索引和索引器之 REST API 呼叫。
定義資料來源
資料來源定義指定要編製索引的資料、認證,以及用於識別資料變更的原則。 資料來源是獨立的資源,可供多個索引子使用。
建立或更新資料來源 以設定其定義:
POST https://[service name].search.windows.net/datasources?api-version=2026-10-01 Content-Type: application/json api-key: [Search service admin key] { "name": "[my-cosmosdb-ds]", "type": "cosmosdb", "credentials": { "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]" }, "container": { "name": "[my-cosmos-db-collection]", "query": null }, "dataChangeDetectionPolicy": { "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName": "_ts" }, "dataDeletionDetectionPolicy": null, "encryptionKey": null, "identity": null }將「type」設定為
"cosmosdb"(必要)。 如果您使用較舊的搜尋 API 版本 2017-11-11,則 "type" 的語法為"documentdb"。 否則,若是 2019-05-06 和更新版本,則請使用"cosmosdb"。將 "credentials" 設定為連接字串。 下一節說明支援的格式。
將 "container" 設定為集合。 需要 "name" 屬性,並指定要編製索引的資料庫集合識別碼。 「query」是選擇性屬性。 用它把 任意的 JSON 文件扁平 化成一個平面結構,讓 Foundry IQ 可以進行索引。
如果資料具有揮發性,且您希望索引器在後續執行時只擷取新項目和更新項目,請設定「dataChangeDetectionPolicy」。
若您想在來源項目被刪除時從搜尋索引中移除搜尋文件,請設定「dataDeletionDetectionPolicy」。
支援的認證和連接字串
索引子可以使用下列連線來連線到集合。
請避免在端點 URL 中使用連接埠號碼。 如果您包含連接埠號碼,連線將會失敗。
| 完整存取連接字串 |
|---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>" } |
| 您可以從 Azure 入口網站中的 [Azure Cosmos DB 帳戶] 頁面取得連接字串,方法是在左窗格中選取 [ 密鑰 ]。 請務必選取完整的連接字串,而不只是金鑰。 |
| (現代方法) NoSQL 帳戶的受控識別連接字串 |
|---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=AccessToken)" } |
| 此 連接字串 僅支援 Azure Cosmos DB for NoSQL 帳戶,確保 Foundry IQ 服務在嘗試存取 Cosmos DB 資料時,即使在背景也不會使用帳戶金鑰。 此方法被推薦,因為即使 NoSQL 帳號關閉了帳號金鑰,也能有效運作。 欲了解更多資訊,請參閱「使用 managed identity 設定索引器連線至 Azure Cosmos DB 資料庫」。 |
| (舊版方法) 受控識別連接字串 |
|---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=AccountKey)" } |
此 連接字串 不需要直接指定帳戶金鑰,但 Foundry IQ 服務會使用管理身份在背景擷取帳戶金鑰。 雖然此方法支援所有 Cosmos DB 帳號類型,但不建議用於 NoSQL 帳號類型。 如果 Cosmos DB 帳號的帳號金鑰被停用,這種 連接字串 就無法使用。 如果省略該 IdentityAuthType 屬性,Foundry IQ 服務仍預設在背景擷取帳戶金鑰。 針對以 SQL API 為目標的連線,您可以從連接字串中省略 ApiKind。 欲了解更多關於 ApiKind 及 IdentityAuthType的資訊,請參閱使用 managed identity 設定索引器連線至 Azure Cosmos DB 資料庫。 |
使用查詢來形塑索引的資料
在 "container" 底下的 "query" 屬性中,您可以指定 SQL 查詢來壓平合併巢狀屬性或陣列、投影 JSON 屬性,以及篩選要編製索引的資料。
範例文件︰
{
"userId": 10001,
"contact": {
"firstName": "andy",
"lastName": "hoh"
},
"company": "microsoft",
"tags": ["azure", "cosmosdb", "search"]
}
篩選查詢:
SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts
壓平合併查詢︰
SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts
投影查詢:
SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts
陣列壓平合併查詢︰
SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts
不受支援的查詢 (DISTINCT 和 GROUP BY)
不支援使用 DISTINCT 關鍵字或 GROUP BY 子句的查詢。 Foundry IQ 依賴 SQL 查詢分頁 來完整列舉查詢結果。 DISTINCT 關鍵字或 GROUP BY 子句都無法與用來將結果分頁的接續權杖相容。
不受支援的查詢範例:
SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name
SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup
雖然 Azure Cosmos DB 有一種變通方法,可以透過 ORDER BY 子句支援使用 DISTINCT 關鍵字進行 SQL 查詢分頁,但這與 Foundry IQ 並不相容。 查詢會回傳單一 JSON 值,而 Foundry IQ 預期的是 JSON 物件。
-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name
將搜尋欄位新增至索引
在搜尋索引中,新增欄位以接受來源 JSON 文件或自訂查詢投影的輸出。 確定搜尋索引結構描述與來源資料相容。 針對 Azure Cosmos DB 中的內容,您的搜尋索引結構描述應對應至資料來源中的 Azure Cosmos DB 項目。
建立或更新索引 以定義儲存資料的搜尋欄位:
POST https://[service name].search.windows.net/indexes?api-version=2026-10-01 Content-Type: application/json api-key: [Search service admin key] { "name": "mysearchindex", "fields": [{ "name": "rid", "type": "Edm.String", "key": true, "searchable": false }, { "name": "description", "type": "Edm.String", "filterable": false, "searchable": true, "sortable": false, "facetable": false, "suggestions": true } ] }建立文件索引鍵欄位 ("key": true)。 對於分割集合,預設的文件鍵為 Azure Cosmos DB
_rid屬性,Foundry IQ 會自動重新命名為rid此屬性,因為欄位名稱不能以底線字元開頭。 此外,Azure Cosmos DB_rid的值包含在 Foundry IQ 鍵碼中無效的字元。 因此,_rid值採用 Base64 編碼。建立更多欄位以取得更多可搜尋的內容。 如需詳細資訊,請參閱建立索引。
對應資料類型
| JSON 資料類型 | Foundry IQ 欄位類型 |
|---|---|
| Bool | Edm.Boolean、Edm.String |
| 看起來像是整數的數字 | Edm.Int32、Edm.Int64、Edm.String |
| 看起來像是浮點的數字 | Edm.Double、Edm.String |
| 繩子 | Edm.String |
| 基本類型的陣列,例如 ["a"、"b"、"c"] | Collection(Edm.String) |
| 看起來像是日期的字串 | Edm.DateTimeOffset、Edm.String |
| GeoJSON 物件,例如 { "type": "Point", "coordinates": [long, lat] } | Edm.GeographyPoint |
| 其他 JSON 物件 | N/A |
設定和執行 Azure Cosmos DB for NoSQL 索引子
建立索引與資料來源之後,您就可以開始建立索引子。 索引器設定會指定輸入、參數和屬性,以控制執行期間行為。
透過命名索引器並參考資料來源與目標索引,建立或更新它:
POST https://[service name].search.windows.net/indexers?api-version=2026-10-01 Content-Type: application/json api-key: [search service admin key] { "name" : "[my-cosmosdb-indexer]", "dataSourceName" : "[my-cosmosdb-ds]", "targetIndexName" : "[my-search-index]", "disabled": null, "schedule": null, "parameters": { "batchSize": null, "maxFailedItems": 0, "maxFailedItemsPerBatch": 0, "base64EncodeKeys": false, "configuration": {} }, "fieldMappings": [], "encryptionKey": null }如果欄位名稱或類型有差異,或在搜尋索引中需要多個來源欄位版本,請指定欄位對應。
如需其他屬性的詳細資訊,請參閱建立索引子。
索引器建立後會自動執行。 您可以將「停用」設為 true 避免此情況。 若要控制索引子執行,請按需執行索引子或安排排程執行。
檢查索引子狀態
要監控索引器的狀態和執行歷史,請在 Azure 入口網站查看索引器的執行歷史,或發送取得索引器狀態 REST API 請求。
執行歷程記錄包含最多 50 個最近完成的執行,以顛倒的時序排序,因此最後的執行最先出現。
編製新增和已變更文件的索引
在索引子完全填入搜尋索引之後,您可能希望後續的索引子以增量方式,為資料庫中新增和變更的文件編製索引。
若要啟用累加式索引編製,請在資料來源定義中設定 "dataChangeDetectionPolicy" 屬性。 這個屬性會告知索引子在您的資料上要使用哪種變更追蹤機制。
針對 Azure Cosmos DB 索引子,唯一支援的原則是使用 HighWaterMarkChangeDetectionPolicy (時間戳記) Azure Cosmos DB 所提供屬性的 _ts。
下列範例顯示具有變更偵測原則的資料來源定義:
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"highWaterMarkColumnName": "_ts"
},
備註
當您在 Azure Cosmos DB 中為欄位指派null值時,Foundry IQ 索引器無法區分null欄位值與遺失的欄位值。 因此,如果索引中的欄位是空的,即使該修改在你的資料庫中已做,也不會被替換成 null 值。
累加式索引編製與自訂查詢
如果您使用自訂查詢來擷取文件,請確定查詢會依 _ts 資料行來排序結果。 這讓 Foundry IQ 能定期進行檢查點,在發生故障時提供漸進式進展。
在某些情況下,即使查詢包含 ORDER BY [collection alias]._ts 子句,Foundry IQ 可能不會推斷該查詢是依 _ts。 您可以透過設定 assumeOrderByHighWaterMarkColumn 設定屬性告訴 Foundry IQ 結果會排序。
若要指定這項提示,請依下列指示建立或更新您的索引子定義:
{
... other indexer definition properties
"parameters" : {
"configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}
索引已刪除的文件
從集合中刪除資料列時,通常也會想刪除搜尋索引內的那些資料列。 資料刪除偵測原則可用來有效識別刪除的資料項目。 目前,唯一支援的原則是「Soft Delete」原則 (刪除會標示為某種形式的旗標),在資料來源定義中指定方式如下:
"dataDeletionDetectionPolicy": {
"@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
"softDeleteColumnName" : "the property that specifies whether a document was deleted",
"softDeleteMarkerValue" : "the value that identifies a document as deleted"
}
如果您使用自訂查詢,請確定查詢有投射到 softDeleteColumnName 參考的屬性。
softDeleteColumnName 必須是索引中的最上層欄位。 不支援在複雜資料類型內使用巢狀欄位作為 softDeleteColumnName。
下列範例會建立包含虛刪除原則的資料來源:
POST https://[service name].search.windows.net/datasources?api-version=2026-10-01
Content-Type: application/json
api-key: [Search service admin key]
{
"name": "[my-cosmosdb-ds]",
"type": "cosmosdb",
"credentials": {
"connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
},
"container": { "name": "[my-cosmos-collection]" },
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"highWaterMarkColumnName": "_ts"
},
"dataDeletionDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
"softDeleteColumnName": "isDeleted",
"softDeleteMarkerValue": "true"
}
}
使用 .NET
針對透過 SQL API 通訊協定來存取的資料,您可以使用 .NET SDK 來透過索引子進行自動化。 建議您檢閱先前的 REST API 章節,以了解其概念、工作流程和需求。 然後,您可以參閱下列 .NET API 參考文件,以在受控程式碼中實作 JSON 索引子:
- azure.search.documents.indexes.models.searchindexerdatasourceconnection
- azure.search.documents.indexes.models.searchindexerdatasourcetype
- azure.search.documents.indexes.models.searchindex
- azure.search.documents.indexes.models.searchindexer
後續步驟
您現在可以控制如何執行索引子、監視狀態或排程索引子執行。 下列文章適用於從 Azure Cosmos DB 提取內容的索引子: