チュートリアル: Cassandra アカウントの API にデータを移行する

2025-06-13

適用対象: カサンドラ

開発者は、所有しているオンプレミスまたはクラウドで実行される既存の Cassandra のワークロードを Azure に移行したいと考えることがあります。このようなワークロードは、Azure Cosmos DB の Cassandra 用 API アカウントに移行できます。このチュートリアルでは、Apache Cassandra のデータを Azure Cosmos DB の Cassandra 用 API アカウントに移行するために利用できる複数のオプションについて、その手順を説明します。

このチュートリアルに含まれるタスクは次のとおりです。

移行の計画
移行の前提条件
cqlshCOPY コマンドを使用してデータを移行する
Spark を使用してデータを移行する

Azure サブスクリプションがない場合は、開始する前に無料アカウントを作成してください。

移行の前提条件

スループットのニーズを見積もります。 Azure Cosmos DB の API for Cassandra アカウントにデータを移行する前に、ワークロードのスループットニーズを見積もります。一般に、CRUD 操作に必要な平均スループットから始めます。次に、抽出、変換、読み込み、またはスパイク時の操作に必要な追加のスループットを含めます。移行を計画するには次の詳細情報が必要です。
- 既存のデータサイズまたは推定データサイズ: データベースの最小サイズとスループットの要件を定義します。新しいアプリケーションのデータサイズを見積もる場合は、データが行間で均等に分散されていると想定し、データサイズを乗算して値を推定できます。
- 必要なスループット: 読み取り (クエリ、取得) および書き込み (更新、削除、挿入) 操作の概算スループットレート。この値は、必要な要求ユニット数と安定した状態のデータサイズを計算するために必要です。
- スキーマ:cqlsh を使用して既存の Cassandra クラスターに接続し、Cassandra からスキーマをエクスポートします。
```
cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql
```
  既存のワークロードの要件を明らかにした後は、収集したスループットの要件に従って Azure Cosmos DB アカウント、データベース、およびコンテナーを作成します。
- 操作の RU 料金の決定: Cassandra 用 API によってサポートされている任意の SDK を使用して、RU を決定できます。この例では、.NET バージョンでの RU 負担取得方法を示します。
```
var tableInsertStatement = table.Insert(sampleEntity);
var insertResult = await tableInsertStatement.ExecuteAsync();

foreach (string key in insertResult.Info.IncomingPayload)
  {
     byte[] valueInBytes = customPayload[key];
     double value = Encoding.UTF8.GetString(valueInBytes);
     Console.WriteLine($"CustomPayload:  {key}: {value}");
  }
```
必要なスループットの割り当て: Azure Cosmos DB は、要件の増大に従って、ストレージとスループットを自動的にスケーリングできます。 Azure Cosmos DB の要求ユニット計算ツールを使って、スループットのニーズを推定することができます。
Cassandra 用 API アカウントでテーブルを作成します 。データの移行を開始する前に、Azure portal または cqlsh からすべてのテーブルを事前に作成します。データベースレベルのスループットがある Azure Cosmos DB アカウントに移行しようとしている場合は、コンテナーの作成時に必ずパーティションキーを指定するようにしてください。
スループットを向上させる: データの移行にかかる時間は、Azure Cosmos DB のテーブルに対してプロビジョニングしたスループットの量に依存します。移行中のスループットを増やします。スループットが高くなるほど、レート制限を回避し、移行に要する時間を短縮できます。移行が完了したら、スループットを下げ、コストを節約します。また、Azure Cosmos DB アカウントをソースデータベースと同じリージョンに作成することもお勧めします。
TLS を有効にする: Azure Cosmos DB には、厳密なセキュリティ要件と基準があります。アカウントを操作するときは、TLS が有効になっていることを確認してください。 SSH で CQL を使用する場合は、TLS 情報を指定できます。

データを移行するためのオプション

cqlshCOPY コマンドまたは Spark を使用して、既存の Cassandra ワークロードから Azure Cosmos DB にデータを移動できます。

cqlsh COPY コマンドを使用してデータを移行する

警告

CQL COPY は、小さなデータセットを移行するためにのみ使用します。大きなデータセットを移動するには、Spark を使用してデータを移行します。

csv ファイルに正しいファイル構造が含まれていることを確認するには、 COPY TO コマンドを使用して、ソース Cassandra テーブルから csv ファイルにデータを直接エクスポートします。適切な資格情報を使用して、cqlsh がソーステーブルに接続されていることを確認します。
```
COPY exampleks.tablename TO 'data.csv' WITH HEADER = TRUE;   
```
次に、Cassandra 用 API アカウントの接続文字列情報を取得します。
- Azure portal にサインインし、Azure Cosmos DB アカウントに移動します。
- [接続文字列] ウィンドウを開きます。ここには、cqlsh から Cassandra 用 API アカウントに接続するために必要なすべての情報が表示されます。
Azure portal の接続情報を使用して、 cqlsh にサインインします。
data.csvをコピーするには、CQLCOPY FROM コマンドを使用します。このファイルは、 cqlsh がインストールされているユーザールートディレクトリに引き続き存在します。
```
COPY exampleks.tablename FROM 'data.csv' WITH HEADER = TRUE;
```

注意

Cassandra 用 API では、Cassandra 3.11 に付属するプロトコルバージョン 4 がサポートされます。 API で新しいプロトコルバージョンを使用する場合、問題が発生する可能性があります。新しいプロトコルバージョンでは、COPY FROM がループに入り、重複する行を返す可能性があります。

cqlsh コマンドに protocol-version を追加してください。

cqlsh <USERNAME>.cassandra.cosmos.azure.com 10350 -u <USERNAME> -p <PASSWORD> --ssl --protocol-version=4

CQL Copy コマンドに throughput-limiting オプションを追加する

cqlsh の COPY コマンドでは、Azure Cosmos DB へのドキュメントの取り込み速度を制御するさまざまなパラメーターがサポートされています。

COPY コマンドの既定の構成では、非常に高速なペースでデータを取り込もうとします。 Cosmos DB のレート制限動作は考慮されません。コレクションで構成されているスループットに応じて、CHUNKSIZE または INGESTRATE を削減する必要があります。

ドキュメントまたはレコードのサイズが 1 KB の場合は、20,000 RU のコレクションに対して次の構成 (少なくとも) をお勧めします。

CHUNKSIZE = 100
INGESTRATE = 500
MAXATTEMPTS = 10

コマンドの例

Cassandra 用 API からローカル csv ファイルにデータをコピーする

COPY standard1 (key, "C0", "C1", "C2", "C3", "C4") TO 'backup.csv' WITH PAGESIZE=100 AND MAXREQUESTS=1 ;

ローカル csv ファイルから Cassandra 用 API にデータをコピーする

COPY standard2 (key, "C0", "C1", "C2", "C3", "C4") FROM 'backup.csv' WITH CHUNKSIZE=100 AND INGESTRATE=100 AND MAXATTEMPTS=10;

重要

オープンソースバージョンの Apache Cassandra の CQLSH COPY のみがサポートされています。 Datastax Enterprise (DSE) バージョンの CQLSH でエラーが発生する可能性があります。

Spark を使用してデータを移行する

Spark を使用して Cassandra 用 API アカウントにデータを移行するには、次の手順を使用します。

Azure Databricks クラスターまたは Azure HDInsight クラスターをプロビジョニングします。
コピー先の Cassandra 用 API エンドポイントにデータを移動します。詳細については、「 Cassandra から Azure Cosmos DB for Apache Cassandra アカウントへのデータの移行」を参照してください。

Azure 仮想マシンまたは他のクラウド上の既存のクラスターにデータが存在する場合は、Spark ジョブを使用したデータの移行が推奨されるオプションです。 1 回限りまたは定期的なインジェストの仲介役として Spark を設定します。オンプレミス環境と Azure の間で Azure ExpressRoute 接続を使用することで、この移行を加速できます。

ライブマイグレーション

ネイティブ Apache Cassandra クラスターからのダウンタイムなしの移行が必要な場合は、デュアル書き込みと、履歴データを移行するための個別の一括データ読み込みを構成することをお勧めします。このパターンの実装は、アプリケーションコードの変更を最小限に抑えるために、オープンソースのデュアルライトプロキシを使用する方が簡単です。詳細については、「 Apache Cassandra から Azure Cosmos DB for Apache Cassandra へのデータのライブ移行」を参照してください。

リソースをクリーンアップする

必要がなくなったら、リソースグループ、Azure Cosmos DB アカウント、およびすべての関連リソースを削除できます。これを行うには、仮想マシン用のリソースグループを選択し、 [削除] を選択した後、削除するリソースグループの名前を確認します。

次のステップ

このチュートリアルでは、Azure Cosmos DB の Cassandra 用 API アカウントにデータを移行する方法について説明しました。次に、Azure Cosmos DB のその他の概念を学習します。

Azure Cosmos DB の調整可能なデータの一貫性レベル