Azure AI 検索のクエリ用の Apache Gremlin のAzure Cosmos DBからのデータのインデックス作成 (プレビュー)

Note

Azure AI 検索は、Azure ポータル、REST API、およびAzure SDKから使用できます。また、Foundry IQ は、エンタープライズコンテンツを、Microsoft Foundry ポータルのエージェントの再利用可能なアクセス許可に対応したナレッジベースに変換するマネージドナレッジレイヤーです。

Note

この機能は現在プレビュー段階です。このプレビュー版はサービスレベルアグリーメントなしで提供されています。運用環境のワークロードに使用することはお勧めできません。特定の機能がサポートされていないか、機能が制限されている可能性があります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

重要

これらの機能は、他のMicrosoft サービスおよびサードパーティのサービスへの接続をサポートします。これらのサービスの利用は各サービスの利用規約に従うものとし、データが Azure コンプライアンス境界の外部で処理または保存されたり、Azure コンプライアンス境界内に流入したりする場合があります。

データが組織のコンプライアンスと地理的境界の外部に流れるかどうか、および関連する影響、および適切なアクセス許可、境界、承認がプロビジョニングされるかどうかを管理するのは、お客様の責任です。

特定のユースケースのコンテキストで構築したアプリケーションを慎重に確認およびテストし、すべての適切な決定とカスタマイズを行う責任があります。これには、メタプロンプト、コンテンツフィルター、その他の安全システムなどの独自の責任ある AI 軽減策の実装や、アプリケーションが適切な品質、信頼性、セキュリティ、信頼性の標準を満たしていることを確認する機能が含まれます。詳細については、「Azure AI 検索透過性に関するメモを参照してください。

この記事では、インデクサーを構成して、Azure Cosmos DB for Apache Gremlinからコンテンツをインポートし、それをAzure AI 検索で検索可能にする方法について説明します。

この記事では、Cosmos DB に固有の情報を使用して インデクサーを作成 する方法について説明します。 REST API を使用して、すべてのインデクサーに共通する 3 部構成のワークフローを示します。データソースの作成、インデックスの作成、インデクサーの作成です。データ抽出は、インデクサーの作成要求を送信するときに発生します。

用語は混乱を招く可能性があるため、Azure Cosmos DBインデックス作成とAzure AI 検索インデックス作成は異なる操作です。 Azure AI 検索でインデックスを作成し、検索サービスに検索インデックスを読み込みます。

前提条件

プレビューに登録して、シナリオに関するフィードバックを提供します。フォームの送信後、この機能に自動的にアクセスできます。
Azure Cosmos DB アカウント、データベース、コンテナー、および項目。待機時間を短縮し、帯域幅の課金を回避するには、Azure AI 検索とAzure Cosmos DBの両方に同じリージョンを使用します。
Azure Cosmos DB コレクションの自動インデックス作成ポリシー。Consistent に設定されます。この設定は既定の構成です。遅延インデックス作成は推奨されず、データが不足する可能性があります。
読み取りアクセス許可。 "フルアクセス" コネクションストリングにはコンテンツへのアクセスを許可するキーが含まれていますが、Azure ロールを使用している場合は、search サービスのマネージド IDに Cosmos DB アカウントリーダーロール アクセス許可があることを確認してください。
データソース、インデックス、インデクサーを作成する REST クライアント。

データソースを定義する

データソース定義では、データの変更を識別するためのインデックス、資格情報、およびポリシーのデータを指定します。データソースは、複数のインデクサーで使用できるように、独立したリソースとして定義されます。

この呼び出しでは、プレビュー REST API バージョンを指定して、Apache Gremlin のAzure Cosmos DB経由で接続するデータソースを作成します。 2021-04-01-preview以降を使用できます。最新のプレビュー REST API をお勧めします。

データソースを作成または更新して、その定義を設定します。

 POST https://[service name].search.windows.net/datasources?api-version=2026-05-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" (必須) に設定します。
"資格情報" を接続文字列に設定します。次のセクションでは、サポートされている形式について説明します。
"container" をコレクションに設定します。 "name" プロパティは必須であり、グラフの ID を指定します。

"query" プロパティは省略可能です。既定では、Azure Cosmos DB for Apache Gremlin の Azure AI 検索インデクサーは、グラフ内のすべての頂点をインデックス内のドキュメントにします。エッジは無視されます。クエリの既定値は g.V() です。または、エッジのインデックスのみを作成するようにクエリを設定することもできます。エッジのインデックスを作成するには、クエリを g.E() に設定します。
データが揮発性であり、インデクサーが後続の実行時に新しい項目と更新された項目のみを取得する場合は、"dataChangeDetectionPolicy" を設定します。高基準値列として _ts を使用すると、増分の進行状況が既定で有効になります。
ソースアイテムが削除されたときに検索インデックスから検索ドキュメントを削除する場合は、"dataDeletionDetectionPolicy" を設定します。

サポートされている資格情報と接続文字列

インデクサーは、次の接続を使用してコレクションに接続できます。 Apache Gremlin のAzure Cosmos DBを対象とする接続の場合は、必ず接続文字列に "ApiKind" を含めるようにしてください。

エンドポイント URL のポート番号は使用しないでください。ポート番号を含めると、接続は失敗します。

完全アクセスの接続文字列
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }`
左側のウィンドウで Keys を選択すると、Azure ポータルのAzure Cosmos DB アカウントページから接続文字列を取得できます。キーだけでなく、完全な接続文字列を選択してください。

マネージド ID接続文字列

マネージド ID接続文字列
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)" }`
事前に検索サービスをマネージド IDを使用するように構成し、Cosmos DB アカウント閲覧者ロールのアクセス許可を付与するロールの割り当てを作成しておく必要があります。この接続文字列にはアカウントキーは必要ありません。詳細については、「マネージド ID を使用して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];)" }

事前に検索サービスをマネージド IDを使用するように構成し、Cosmos DB アカウント閲覧者ロールのアクセス許可を付与するロールの割り当てを作成しておく必要があります。この接続文字列にはアカウントキーは必要ありません。詳細については、「マネージド ID を使用してAzure Cosmos DB データベースへのインデクサー接続を設定するを参照してください。

インデックスに検索フィールドを追加する

検索インデックスで、ソース JSON ドキュメントまたはカスタムクエリプロジェクションの出力を受け入れるフィールドを追加します。検索インデックススキーマがグラフと互換性があることを確認します。 Azure Cosmos DB内のコンテンツの場合、検索インデックススキーマは、データソースの Azure Cosmos DB items に対応している必要があります。

インデックスを作成または更新して、データを格納する検索フィールドを定義します。

 POST https://[service name].search.windows.net/indexes?api-version=2026-05-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": []
    }]
  }

ドキュメントキーフィールド ("key": true) を作成します。パーティション分割コレクションの場合、既定のドキュメントキーは Azure Cosmos DB _rid プロパティです。フィールド名はアンダースコア文字で始めることができないため、Azure AI 検索自動的に rid に名前が変更されます。また、Azure Cosmos DB _rid 値には、Azure AI 検索キーで無効な文字が含まれています。このため、 _rid 値は Base64 でエンコードされます。
検索可能なコンテンツ用の追加フィールドを作成します。詳細については、インデックスの作成を参照してください。

データ型のマッピング

JSON データ型	Azure AI 検索フィールドの種類
ブール	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
{ "type": "Point", "coordinates": [long, lat] } などの GeoJSON オブジェクト	Edm.GeographyPoint
その他の JSON オブジェクト	N/a

Azure Cosmos DB インデクサーを構成して実行する

インデックスとデータソースが作成されたら、インデクサーを作成する準備ができました。インデクサーの構成では、実行時の動作を制御する入力、パラメーター、およびプロパティを指定します。

インデクサーを作成または更新するには、インデクサーに名前を付け、データソースとターゲットインデックスを参照します。

POST https://[service name].search.windows.net/indexers?api-version=2026-05-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-05-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インデクサーの場合、サポートされている唯一のポリシーは、Azure Cosmos DBによって提供される HighWaterMarkChangeDetectionPolicy (timestamp) プロパティを使用する _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-05-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' 列が整数、文字列、またはブール型である必要があります。

グラフデータを検索インデックス内のフィールドにマッピングする

Apache Gremlin インデクサーのAzure Cosmos DBでは、いくつかのグラフデータが自動的にマップされます。

インデクサーは、 _rid が存在する場合はインデックス内の rid フィールドにマップし、Base64 でエンコードします。
インデクサーは、 _id が存在する場合、インデックス内の id フィールドにマップします。
Apache Gremlin のAzure Cosmos DBを使用して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"
            }
          ]
        }
    }

クエリの出力をインデックス内のフィールドにマップするには、出力フィールドマッピングを使用する必要がある場合があります。カスタムクエリには複雑なデータが含まれている可能性があるため、フィールドマッピングの代わりに出力フィールドマッピングを使用する必要があります。

たとえば、クエリで次の出力が生成されたとします。

    [
      {
        "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の詳細については、「Azure Cosmos DBへの導入: Apache Gremlin のAzure Cosmos DBを参照してください。
Azure AI 検索シナリオと価格の詳細については、azure.microsoft.com の Search サービスのページを参照してください。
インデクサーのネットワーク構成については、Azureネットワークセキュリティ機能によって保護されたコンテンツへの Indexer アクセスを参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-21