次の方法で共有


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

重要

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 ロールを使用している場合は、検索サービスのマネージド IDCosmos DB アカウントの閲覧者ロールのアクセス許可があることを確認してください。

  • データ ソース、インデックス、インデクサーを作成するための REST クライアント

データ ソースを定義する

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

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

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

     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
     }
     }
    
  2. "type" を "cosmosdb" に指定します (必須)。

  3. "credentials" を接続文字列に設定します。 続く部分は、サポートされている形式を記述します。

  4. "container" をコレクションに設定します。 "name" プロパティは必須であり、グラフの ID を指定します。

    "query" プロパティは省略可能です。 既定では、Azure Cosmos DB for Apache Gremlin 用の Azure AI Search インデクサーによって、グラフ内のすべての頂点がインデックス内のドキュメントとして作成されます。 エッジは無視されます。 クエリの既定値は g.V() です。 また、エッジのインデックスのみ作成するようにクエリを設定することもできます。 エッジのインデックスを作成するには、クエリを g.E() に設定します。

  5. データが変化しやすいので、以降の実行で新規および更新された項目だけをインデクサーで取得する場合は、"dataChangeDetectionPolicy" を設定します。 高基準列として _ts を使用すると、増分の進行状況が既定で有効になります。

  6. ソース項目が削除されたら場合に検索インデックスから検索ドキュメントを削除する場合は、"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 の接続文字列
{ "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 の項目に対応している必要があります。

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

     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": []
        }]
      }
    
  2. ドキュメント キー フィールド ("key": true) を作成します。 パーティション分割されたコレクションの場合、既定のドキュメント キーは Azure Cosmos DB の _rid プロパティですが、フィールド名の先頭にはアンダースコア文字を使用できないため、これは Azure AI Search によって rid に自動的に変更されます。 また、Azure Cosmos DB の _rid 値には、Azure AI Search キーでは無効な文字が含まれています。 そのため、_rid 値は Base64 でエンコードされます。

  3. コンテンツをより検索しやすくするために、追加のフィールドを作成します。 詳細については、インデックスの作成に関するページを参照してください。

マッピング データ型

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 インデクサーを構成して実行する

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

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

    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
    }
    
  2. フィールドの名前または種類に違いがある、または検索インデックスで複数のソース フィールドのバージョンが必要な場合、フィールド マッピングを定義します。

  3. その他のプロパティについては、「インデクサーの作成方法」を参照してください。

インデクサーは、作成されると自動的に実行されます。 これを防ぐには、"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 インデクサーによって、一部のグラフ データが自動的にマップされます。

  1. _rid が存在する場合、インデクサーによってインデックス内の rid フィールドにマップされて、Base64 エンコーディングされます。

  2. _id が存在する場合、インデクサーによってインデックス内の id フィールドにマップされます。

  3. Azure Cosmos DB for Apache Gremlin を使用して Azure Cosmos DB データベースに対してクエリを実行すると、各プロパティの JSON 出力には idvalue が含まれている場合があります。 プロパティの 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 の配列内の最初のオブジェクトを参照する必要はありません。

次のステップ