Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
重要
Azure Cosmos DB for Apache Gremlin 索引器目前處於公開預覽階段,並受 Microsoft Azure 預覽補充使用條款的約束。
有關此功能專屬的預覽條款,請參閱 預覽功能。
Azure Cosmos DB for Apache Gremlin 索引器(預覽版)會從 Azure Cosmos DB for Apache Gremlin 匯入內容,並使其可於 Foundry IQ 中搜尋。
本文補充建立索引子,並提供 Cosmos DB 專屬資訊。 它使用 REST API 展示所有索引器共有的三步驟工作流程:建立資料來源、建立索引、建立索引器。 資料擷取發生在你提交建立索引器請求時。
由於術語容易令人困惑,值得一提的是,Azure Cosmos DB 索引與 Foundry IQ 索引是不同的操作。 Foundry IQ 中的索引作業會在您的 Foundry IQ 服務中建立並載入搜尋索引。
先決條件
請填寫 索引預覽註冊表單。 報名會自動通過。
一個Azure Cosmos DB帳戶、資料庫、容器和物品。 同時使用相同區域來使用Foundry IQ和Azure Cosmos DB,以降低延遲並避免頻寬費用。
Azure Cosmos DB 集合上的 自動索引政策,設定為 Consistent。 此設定為預設配置。 不建議懶惰地編入索引,可能會導致資料遺失。
閱讀權限。 「完全存取」連接字串 包含可授與內容存取權的金鑰,但如果您使用 Azure 角色,請確保 Foundry IQ 服務受控識別具有 Cosmos DB 帳戶讀取者角色權限。
一個 REST 客戶端 用來建立資料來源、索引和索引器。
定義資料來源
資料來源定義指定了索引資料、憑證及識別資料變更的政策。 資料來源被定義為獨立的資源,以便多個索引器都能使用。
在此通話中,請指定預覽版 REST API 版本,以建立一個可透過 Azure Cosmos DB for Apache Gremlin 連接的資料來源。 你可以用 2021-04-01-preview ,也可以以後再用。 我們推薦 使用最新的預覽版 REST API。
建立或更新資料來源 以設定其定義:
POST https://[service name].search.windows.net/datasources?api-version=2026-11-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "[my-cosmosdb-gremlin-ds]", "type": "cosmosdb", "credentials": { "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin;" }, "container": { "name": "[cosmos-db-collection]", "query": "g.V()" }, "dataChangeDetectionPolicy": { "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName": "_ts" }, "dataDeletionDetectionPolicy": null, "encryptionKey": null, "identity": null }將「type」設為
"cosmosdb"(必需)。將「credentials」設為連線字串。 下一節將介紹所支援的格式。
將「container」添加到集合中。 「name」屬性是必填的,它指定了圖的 ID。
「查詢」屬性是可選的。 預設情況下,針對 Azure Cosmos DB for Apache Gremlin 的 Foundry IQ 索引器會將圖形中的每個頂點設為索引中的文件。 邊緣則被忽略。 查詢預設為
g.V()。 或者,您也可以將查詢設定為只為邊緣編製索引。 要為邊建立索引,請將查詢設定為g.E()。如果您的資料具有揮發性,且您希望索引器在後續執行時只擷取新項目和更新項目,請設定「dataChangeDetectionPolicy」。 依預設會啟用累加式進度,並使用
_ts作為最高水位標記資料行。若您想在來源項目被刪除時從搜尋索引中移除搜尋文件,請設定「dataDeletionDetectionPolicy」。
支援的憑證與連線字串
索引器可以透過以下連線連接到集合。 對於目標為 Azure Cosmos DB for Apache Gremlin 的連線,請務必在連線字串中加入「ApiKind」。
避免在端點網址中顯示埠號。 如果您包含連接埠號碼,連線將會失敗。
| 完整存取連接字串 |
|---|
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=Gremlin" } |
| 你可以在Azure入口網站的Azure Cosmos DB帳戶頁面左側面板中選擇Keys來獲取連接字串。 務必選擇完整的連線字串,而非僅選擇一個金鑰。 |
| 管理身份連接字串 |
|---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" } |
| 此 連接字串 不需要帳戶金鑰,但您必須先設定 Foundry IQ 服務使用受控識別進行連線,並建立角色指派,授與 Cosmos DB 帳戶讀取者角色 權限。 更多資訊請參見 使用受控身分識別設定索引器連接至 Azure Cosmos DB 資料庫。 |
在索引中新增搜尋欄位
在 搜尋索引中,新增欄位以接受原始 JSON 文件或自訂查詢投影的輸出。 確保搜尋索引結構與你的圖表相容。 對於Azure Cosmos DB內容,你的搜尋索引結構應該對應於資料來源中的Azure Cosmos DB項目。
建立或更新索引 以定義儲存資料的搜尋欄位:
POST https://[service name].search.windows.net/indexes?api-version=2026-11-01-preview Content-Type: application/json api-key: [Search service admin key] { "name": "mysearchindex", "fields": [ { "name": "rid", "type": "Edm.String", "facetable": false, "filterable": false, "key": true, "retrievable": true, "searchable": true, "sortable": false, "analyzer": "standard.lucene", "indexAnalyzer": null, "searchAnalyzer": null, "synonymMaps": [], "fields": [] }, { "name": "label", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "sortable": false, "facetable": false, "key": false, "indexAnalyzer": null, "searchAnalyzer": null, "analyzer": "standard.lucene", "synonymMaps": [] }] }建立文件鍵欄位(「鍵」:真)。 對於分割集合,預設的文件鍵為 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 |
| 弦 | 埃德姆·斯特林 |
| 原始型態陣列如 [“a”、“b”、“c”] | Collection(Edm.String) |
| 看起來像日期的字串 | Edm.DateTimeOffset, Edm.String |
| GeoJSON 物件如 { “type”: “Point”, “coordinates”: [long, lat] } | Edm.GeographyPoint |
| 其他 JSON 物件 | 無 |
配置並執行 Azure Cosmos DB 索引器
一旦索引和資料來源建立完成,你就可以開始建立索引器了。 索引器配置指定控制執行時行為的輸入、參數與屬性。
透過為索引器命名,並參考資料來源與目標索引,建立或更新索引器:
POST https://[service name].search.windows.net/indexers?api-version=2026-11-01-preview Content-Type: application/json api-key: [search service admin key] { "name" : "[my-cosmosdb-indexer]", "dataSourceName" : "[my-cosmosdb-gremlin-ds]", "targetIndexName" : "[my-search-index]", "disabled": null, "schedule": null, "parameters": { "batchSize": null, "maxFailedItems": 0, "maxFailedItemsPerBatch": 0, "base64EncodeKeys": false, "configuration": {} }, "fieldMappings": [], "encryptionKey": null }如果欄位名稱或類型有差異,或在搜尋索引中需要多個來源欄位版本,請指定欄位對應。
請參閱 建立索引器 以了解更多其他屬性的資訊。
索引器在建立時會自動執行。 你可以把「停用」設為 true,來避免這種情況。 要控制索引器的執行,請按 需求執行索引器 或 將其列入排程。
檢查索引器狀態
要監控索引器狀態與執行歷史,請發送 「取得索引器狀態 」請求:
GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-11-01-preview
Content-Type: application/json
api-key: [admin key]
回應內容包括狀態及已處理項目數量。 它應該看起來像以下範例:
{
"status":"running",
"lastResult": {
"status":"success",
"errorMessage":null,
"startTime":"2022-02-21T00:23:24.957Z",
"endTime":"2022-02-21T00:36:47.752Z",
"errors":[],
"itemsProcessed":1599501,
"itemsFailed":0,
"initialTrackingState":null,
"finalTrackingState":null
},
"executionHistory":
[
{
"status":"success",
"errorMessage":null,
"startTime":"2022-02-21T00:23:24.957Z",
"endTime":"2022-02-21T00:36:47.752Z",
"errors":[],
"itemsProcessed":1599501,
"itemsFailed":0,
"initialTrackingState":null,
"finalTrackingState":null
},
... earlier history items
]
}
執行歷史包含最多 50 次最近完成的執行,並依逆時間順序排序,使最新的執行先行。
索引新文件和已更改的文件
索引器完成搜尋索引後,你可能會希望後續的索引器執行時,只針對資料庫中新增或變更的文件進行增量索引。
要啟用增量索引,請在資料來源定義中設定「dataChangeDetectionPolicy」屬性。 此特性告訴索引器您的資料使用了哪種變更追蹤機制。
對於 Azure Cosmos DB 索引子,唯一支援的原則是 HighWaterMarkChangeDetectionPolicy,並使用 Azure Cosmos DB 提供的 _ts (時間戳記) 屬性。
以下範例展示了帶有變更偵測政策的資料 來源定義 :
"dataChangeDetectionPolicy": {
"@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"highWaterMarkColumnName": "_ts"
},
已刪除文件的索引
當圖表資料被刪除時,你可能也想從搜尋索引中刪除其對應的文件。 資料刪除偵測策略的目的是有效識別已刪除的資料項目,並從索引中刪除整份文件。 資料刪除偵測政策並非用來刪除部分文件資訊。 目前唯一支援的政策是 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"
}
以下範例建立一個具有軟刪除政策的資料來源:
POST https://[service name].search.windows.net/datasources?api-version=2026-11-01-preview
Content-Type: application/json
api-key: [Search service admin key]
{
"name": "[my-cosmosdb-gremlin-ds]",
"type": "cosmosdb",
"credentials": {
"connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
},
"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"
}
}
即使啟用刪除偵測政策,也不支援刪除索引中複雜的(Edm.ComplexType)欄位。 此政策要求 Gremlin 資料庫中的「active」欄位必須為整數、字串或布林型。
將圖表資料映射到搜尋索引中的欄位
Azure Cosmos DB for Apache Gremlin 索引器會自動映射幾個圖形資料:
索引器會映射
_rid到索引中的欄位rid(如果存在),而 Base64 會將其編碼。索引器會映射
_id到索引中的欄位id(如果存在)。當您使用 Azure Cosmos DB for Apache Gremlin 查詢 Azure Cosmos DB 資料庫時,可能會注意到每個屬性的 JSON 輸出中都有一個
id和一個value。 索引子會自動將該屬性的value對應到搜尋索引中一個欄位;如果存在的話,該欄位的名稱會與該屬性相同。 以下範例中,450 被映射到搜尋索引中的一個pages欄位。
{
"id": "Cookbook",
"label": "book",
"type": "vertex",
"properties": {
"pages": [
{
"id": "48cf6285-a145-42c8-a0aa-d39079277b71",
"value": "450"
}
]
}
}
你可能會發現需要使用 Output Field Mappings 來將查詢輸出映射到索引中的欄位。 你可能會想用輸出欄位映射(Output Field Mappings)代替 欄位映射 ,因為自訂查詢可能包含複雜的資料。
舉例來說,假設你的查詢產生了這樣的輸出:
[
{
"vertex": {
"id": "Cookbook",
"label": "book",
"type": "vertex",
"properties": {
"pages": [
{
"id": "48cf6085-a211-42d8-a8ea-d38642987a71",
"value": "450"
}
],
}
},
"written_by": [
{
"yearStarted": "2017"
}
]
}
]
如果你想將上述 JSON 中的 值 pages 映射到索引中的欄位 totalpages ,可以在索引器定義中加入以下 輸出欄位 映射:
... // rest of indexer definition
"outputFieldMappings": [
{
"sourceFieldName": "/document/vertex/pages",
"targetFieldName": "totalpages"
}
]
注意輸出欄位映射是以 /document 開始,並且不包含 JSON 中屬性鍵的參考。 這是因為索引器在匯入圖資料時會將每個文件放在節點下方/document,且索引器也自動允許你透過簡單引用pages來參考 的pages值,而不必參考陣列pages中的第一個物件。
下一步
想了解更多關於 Apache Gremlin 的Azure Cosmos DB,請參閱 Introduction to Azure Cosmos DB: Azure Cosmos DB for Apache Gremlin。
如需更多關於 Foundry IQ 情境與價格的資訊,請參閱 azure.microsoft.com 上的 Foundry IQ 服務頁面。
欲了解索引器的網路設定,請參閱索引器存取受Azure網路安全功能保護的內容。