Azure Cosmos DB for Gremlin でバルク エグゼキューター ライブラリを使用して一括でデータを取り込む

  • [アーティクル]

適用対象: Gremlin

グラフ データベースで、グラフ全体を更新したり、その一部を更新したりするために、データを一括で取り込むことが必要な場合がよくあります。 Azure Cosmos DB は、Azure Cosmos DB for Gremlin の分散データベースおよびバックボーンですが、負荷が十分に分散されている場合にパフォーマンスが最高になるように設計されています。 Azure Cosmos DB のバルク エグゼキューター ライブラリは、Azure Cosmos DB のこの固有機能を利用して、最適なパフォーマンスを提供するように設計されています。 詳細については、.NET SDK での一括サポートの導入に関するページを参照してください。

このチュートリアルでは、Azure Cosmos DB のバルク エグゼキューター ライブラリを使用して、Azure Cosmos DB for Gremlin コンテナーに graph オブジェクトをインポートし、更新する方法について説明します。 このプロセスの間、ライブラリを使用してプログラムから vertex オブジェクトと edge オブジェクトを作成し、1 回のネットワーク要求で複数のオブジェクトを挿入します。

Gremlin クエリをデータベースに送信する (この場合は、コマンドは 1 つずつ評価されてから実行されます) 代わりに、バルク エグゼキューター ライブラリを使用してオブジェクトをローカルで作成し、検証することができます。 ライブラリによって初期化された graph オブジェクトは、データベース サービスに順番に送信できます。

この手法を使用すると、データ インジェストを最大 100 倍高速化できるため、これは、初期データ移行や定期的なデータ移動操作を実行するための理想的な方法です。

以下の種類のバルク エグゼキューター ライブラリが提供されるようになりました。

.NET

前提条件

開始する前に、次の条件を満たしていることを確認します。

複製

このサンプルを使用するには、次のコマンドを実行します。

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

サンプルを入手するには、.\azure-cosmos-graph-bulk-executor\dotnet\src\ に関するページに移動してください。

サンプル


IGraphBulkExecutor graphBulkExecutor = new GraphBulkExecutor("MyConnectionString", "myDatabase", "myContainer");

List<IGremlinElement> gremlinElements = new List<IGremlinElement>();
gremlinElements.AddRange(Program.GenerateVertices(Program.documentsToInsert));
gremlinElements.AddRange(Program.GenerateEdges(Program.documentsToInsert));
BulkOperationResponse bulkOperationResponse = await graphBulkExecutor.BulkImportAsync(
    gremlinElements: gremlinElements,
    enableUpsert: true);

実行

次の表で説明するようにパラメーターを変更します。

パラメーター 説明
ConnectionString Azure Cosmos DB for Gremlin アカウントの [キー] セクションで見つけることができるサービス接続文字列。 これは AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>; のような形式です。
DatabaseName、ContainerName ターゲット データベースとコンテナーの名前。
DocumentsToInsert 生成されるドキュメントの数 (合成データのみに関連)。
PartitionKey データ インジェスト中に各ドキュメントでパーティション キーが指定されることを保証します。
NumberOfRUs コンテナーがまだ存在せず、実行中に作成する必要がある場合にのみ関連します。

.NET の完全なサンプル アプリケーションをダウンロードします。

Java

使用例

次のサンプル アプリケーションは、GraphBulkExecutor パッケージの使用方法を示します。 このサンプルでは、domain オブジェクト注釈または POJO (Plain Old Java Object) オブジェクトを直接使用します。 両方のアプローチを試して、実装とパフォーマンスの要求がより適切に満たされるのはどちらかを判断することをお勧めします。

複製

サンプルを使用するには、次のコマンドを実行します。

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

サンプルを入手するには、.\azure-cosmos-graph-bulk-executor\java\ に関するページに移動してください。

前提条件

このサンプルを実行するには、次のソフトウェアが必要です。

  • OpenJDK 11
  • Maven
  • Gremlin API を使用するように構成された Azure Cosmos DB アカウント

サンプル

private static void executeWithPOJO(Stream<GremlinVertex> vertices,
                                        Stream<GremlinEdge> edges,
                                        boolean createDocs) {
        results.transitionState("Configure Database");
        UploadWithBulkLoader loader = new UploadWithBulkLoader();
        results.transitionState("Write Documents");
        loader.uploadDocuments(vertices, edges, createDocs);
    }

構成

サンプルを実行するには、次の構成を参照し、必要に応じて変更します。

/resources/application.properties ファイルでは、Azure Cosmos DB を構成するために必要なデータを定義します。 必要な値については、次の表で説明しています。

プロパティ 説明
sample.sql.host Azure Cosmos DB によって提供される値。 .NET SDK URI を使用していることを確認します。これは、Azure Cosmos DB アカウントの [概要] セクションで確認できます。
sample.sql.key Azure Cosmos DB アカウントの [キー] セクションからはプライマリまたはセカンダリ キーを取得できます。
sample.sql.database.name サンプルを実行する Azure Cosmos DB アカウント内のデータベースの名前。 データベースが見つからない場合、サンプル コードによって作成されます。
sample.sql.container.name サンプルを実行するデータベース内のコンテナーの名前。 コンテナーが見つからない場合、サンプル コードによって作成されます。
sample.sql.partition.path コンテナーを作成する必要がある場合は、この値を使用して partitionKey パスを定義します。
sample.sql.allow.throughput ここで定義されているスループット値を使用するようにコンテナーが更新されます。 パフォーマンスの要求を満たすためにさまざまなスループット オプションを試している場合、調査が完了したら必ず、コンテナーのスループットをリセットしてください。 より高いスループットでプロビジョニングされたコンテナーを残す場合は、それに関連するコストが発生します。

実行

環境に応じて構成を変更したら、次のコマンドを実行します。

mvn clean package

安全性を高めるために、統合テストを実行することもできます。それには、pom.xml の skipIntegrationTests 値を false に変更します。

単体テストを正常に実行したら、サンプル コードを実行できます。

java -jar target/azure-cosmos-graph-bulk-executor-1.0-jar-with-dependencies.jar -v 1000 -e 10 -d

上記のコマンドを実行すると、小さなバッチ (1,000 頂点と約 5,000 エッジ) でサンプルが実行されます。 実行するボリュームや実行するサンプル バージョンを調整するには、以降のセクションのコマンド ライン引数を使用します。

コマンド ライン引数

次の表で説明しているように、このサンプルの実行中、いくつかのコマンド ライン引数を使用できます。

引数 説明
--vertexCount (-v) 生成する人物頂点の数をアプリケーションに通知します。
--edgeMax (-e) 各頂点に対して生成するエッジの最大数をアプリケーションに通知します。 ジェネレーターは、1 から指定した値までの数値をランダムに選択します。
--domainSample (-d) GraphBulkExecutors、GremlinVertex、GremlinEdge の各 POJO ではなく、人物と関係のドメイン構造を使用してサンプルを実行するようにアプリケーションに指示します。
--createDocuments (-c) create 操作を使用するようにアプリケーションに指示します。 引数が存在しない場合、アプリケーションは既定で upsert 操作を使用します。

詳細なサンプル情報

人物頂点

person クラスは、次の表で説明するように、GremlinVertex クラスへの変換に役立ついくつかの注釈で装飾された単純なドメイン オブジェクトです。

クラス注釈 説明
GremlinVertex このクラスを使用して作成するすべての頂点を定義するには、省略可能な label パラメーターを使用します。
GremlinId ID 値として使用するフィールドを定義するために使用されます。 人物クラスのフィールド名は ID ですが、必須ではありません。
GremlinProperty データベースに格納するときのプロパティの名前を変更するために email フィールドで使用されます。
GremlinPartitionKey クラスのどのフィールドにパーティション キーが含まれているかを定義するために使用されます。 指定するフィールド名は、コンテナーのパーティション パスによって定義された値と一致する必要があります。
GremlinIgnore データベースに書き込まれるプロパティから isSpecial フィールドを除外するために使用されます。

RelationshipEdge クラス

RelationshipEdge クラスは汎用性の高いドメイン オブジェクトです。 フィールド レベルのラベル注釈を使用すると、次の表に示すように、エッジ タイプの動的なコレクションを作成できます。

クラス注釈 説明
GremlinEdge クラス上の GremlinEdge 装飾では、指定されたパーティション キーのフィールドの名前を定義します。 エッジ ドキュメントを作成するとき、割り当てられる値はソース頂点情報に由来します。
GremlinEdgeVertex エッジのそれぞれの側 (ソースとデスティネーション) に 1 つずつ、GremlinEdgeVertex の 2 つのインスタンスが定義されます。 このサンプルには、GremlinEdgeVertexInfo というフィールドのデータ型が含まれています。 GremlinEdgeVertex クラスによって提供される情報は、エッジをデータベースに正しく作成するために必要です。 もう 1 つのオプションは、頂点のデータ型を GremlinVertex 注釈で装飾したクラスにすることです。
GremlinLabel サンプル エッジでは、フィールドを使用して label 値を定義します。 同じ基本ドメイン クラスを使用するため、これによってさまざまなラベルを定義できます。

出力の説明

コンソールは、サンプルの実行時間を記述する JSON 文字列でその実行を終了します。 この JSON 文字列には、次の情報が含まれています。

JSON 文字列 Description
startTime プロセスが開始された時刻の System.nanoTime()。
endTime プロセスが終了した時点の System.nanoTime()。
durationInNanoSeconds endTime の値と startTime の値の差。
durationInMinutes durationInNanoSeconds の値を分に変換したもの。 durationInMinutes の値は時刻値ではなく浮動小数点数で表されます。 たとえば、値 2.5 は 2 分 30 秒を表します。
vertexCount 生成される頂点のボリューム。これは、コマンド ラインの実行に渡される値と一致する必要があります。
edgeCount 生成されるエッジの量。これは静的ではなく、ランダム性の要素を使用して構築されます。
exception 実行を試みたときに例外がスローされた場合にのみ設定されます。

States 配列

states 配列には、実行内の各ステップにかかる時間の分析情報が示されます。 ステップについては、次の表で説明します。

実行ステップ 説明
サンプル頂点を構築する 人物オブジェクトの要求されたボリュームを作成するのにかかる時間の長さ。
サンプル エッジを構築する 関係オブジェクトを作成するのにかかる時間の長さ。
データベースを構成する データベースを構成するのにかかる時間。application.properties で指定された値に基づきます。
ドキュメントを書き込む ドキュメントをデータベースに書き込むのにかかる時間の長さ。

各状態には次の値が含まれます。

状態の値 説明
stateName 報告される状態の名前。
startTime 状態が開始したときの System.nanoTime() の値。
endTime 状態が終了したときの System.nanoTime() の値。
durationInNanoSeconds endTime の値と startTime の値の差。
durationInMinutes durationInNanoSeconds の値を分に変換したもの。 durationInMinutes の値は時刻値ではなく浮動小数点数で表されます。 たとえば、値 2.5 は 2 分 30 秒を表します。

次のステップ