Azure AI 検索でクエリを実行するために Azure Cosmos DB for Apache Gremlin からデータのインデックスを付ける

[アーティクル]
09/03/2024

重要

Azure Cosmos DB for Apache Gremlin インデクサーは、現在、追加の使用条件の下でパブリックプレビュー段階にあります。現時点では、SDK のサポートはありません。

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

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

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

前提条件

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

データソースを定義する

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

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

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

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

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

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

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

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

フルアクセス接続文字列
`{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }`
Azure portal の 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 の項目に対応している必要があります。

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

 POST https://[service name].search.windows.net/indexes?api-version=2024-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 Search によって rid に自動的に変更されます。また、Azure Cosmos DB の _rid 値には、Azure AI Search キーでは無効な文字が含まれています。そのため、_rid 値は Base64 でエンコードされます。
コンテンツをより検索しやすくするために、追加のフィールドを作成します。詳細については、インデックスの作成に関するページを参照してください。

マッピングデータ型

JSON データ型	Azure AI Search のフィールドの型
Bool	Edm.Boolean、Edm.String
整数などの数値	Edm.Int32、Edm.Int64、Edm.String
浮動小数点などの数値	Edm.Double、Edm.String
String	Edm.String
["a", "b", "c"] などのプリミティブ型の配列	Collection(Edm.String)
日付などの文字列	Edm.DateTimeOffset、Edm.String
{ "type": "Point", "coordinates": [long, lat] } などの GeoJSON オブジェクト	Edm.GeographyPoint
その他の JSON オブジェクト	該当なし

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

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

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

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

フィールドの名前または種類に違いがある、または検索インデックスで複数のソースフィールドのバージョンが必要な場合、フィールドマッピングを定義します。
その他のプロパティについては、「インデクサーの作成方法」を参照してください。

インデクサーは、作成されると自動的に実行されます。これを防ぐには、"disabled" を true に設定します。インデクサーの実行を制御するには、インデクサーをオンデマンドで実行するか、スケジュールを設定します。

インデクサーの状態を確認する

インデクサーの状態と実行履歴を監視するには、インデクサーの状態の取得要求を送信します。

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-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 によって指定される _ts (timestamp) プロパティを使用する HighWaterMarkChangeDetectionPolicy です。

次の例は、変更検出ポリシーを含むデータソース定義を示しています。

"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=2024-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」列が整数、文字列、またはブール型である必要があります。

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

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"
            }
          ]
        }
    }

クエリ出力をインデックス内のフィールドにマップするために、出力フィールドのマッピングを使用することが必要な場合があります。カスタムクエリでは複雑なデータを使用する場合が多いため、フィールドマッピングではなく、出力フィールドマッピングを使用することが望ましい場合があります。

たとえば、クエリによって次の出力が生成されるとします。

    [
      {
        "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 の配列内の最初のオブジェクトを参照する必要はありません。

次のステップ

Azure Cosmos DB for Apache Gremlin について詳しくは、「Azure Cosmos DB の概要: Azure Cosmos DB for Apache Gremlin」をご覧ください。
Azure AI Search のシナリオと価格の詳細については、azure.microsoft.com の検索サービスに関するページを参照してください。
インデクサーのネットワーク構成については、「Azure ネットワークセキュリティ機能によって保護されているコンテンツへのインデクサーアクセス」に関するページを参照してください。

次の方法で共有

Azure AI 検索でクエリを実行するために Azure Cosmos DB for Apache Gremlin からデータのインデックスを付ける

前提条件

データソースを定義する

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

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

マッピングデータ型

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

インデクサーの状態を確認する

新規および変更されたドキュメントのインデックス作成

削除されたドキュメントのインデックス作成

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure AI 検索でクエリを実行するために Azure Cosmos DB for Apache Gremlin からデータのインデックスを付ける

前提条件

データ ソースを定義する

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

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

マッピング データ型

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

インデクサーの状態を確認する

新規および変更されたドキュメントのインデックス作成

削除されたドキュメントのインデックス作成

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

次のステップ

フィードバック

その他のリソース

データソースを定義する

マッピングデータ型

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