翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Keyspaces へのデータの一括アップロードまたは移行に適したツールを選択する方法
このセクションでは、Amazon Keyspaces にデータを一括アップロードまたは移行するために使用できるさまざまなツールを確認し、ニーズに応じて適切なツールを選定する方法を学びます。さらに、このセクションでは、Amazon Keyspaces にデータをインポートする方法を示す、利用可能なstep-by-stepのチュートリアルの概要とユースケースについて説明します。
Apache Cassandra から Amazon Keyspaces にワークロードを移行するための戦略を確認するには、「[Apache Cassandra から Amazon Keyspaces への移行の計画を立てる](migrating-cassandra.md)」を参照してください。
+ **移行ツール**
+ Github で利用可能な [Amazon Keyspaces (Apache Cassandra 向け) の料金計算ツール](https://aws-samples.github.io/sample-pricing-calculator-for-keyspaces/#cassandra)を使用すると、既存の Apache Cassandra ワークロードに基づいて Amazon Keyspaces の月額コストを見積もることができます。Amazon Keyspaces の Cassandra nodetool ステータス出力と意図したサーバーレス設定からメトリクスを入力して、2 つのソリューション間の直接コストを比較します。この計算ツールは、既存の Cassandra デプロイと比較した Amazon Keyspaces の運用コストにのみ重点を置いていることに注意してください。インフラストラクチャのメンテナンス、運用オーバーヘッド、Cassandra のサポートコストなどの総所有コスト (TCO) 要因は含まれません。
+ **Amazon Keyspaces 移行用の ZDM デュアル書き込みプロキシ** – [Github](https://github.com/aws-samples/amazon-keyspaces-examples/blob/main/migration/online/zdm-proxy/README.md) で利用可能な ZDM デュアル書き込みプロキシは、Apache Cassandra から Amazon Keyspaces へのダウンタイムのない移行をサポートしています。
+ **CQLReplicator** – CQLReplicator はオープンソースのユーティリティで、[Github](https://github.com/aws-samples/cql-replicator) から入手できます。このユーティリティを利用して、Apache Cassandra から Amazon Keyspaces にほぼリアルタイムでデータを移行できます。
詳細については、「[CQLReplicator を使用してデータを移行する](migration-hybrid-cql-rep.md)」を参照してください。
+ Amazon Managed Streaming for Apache Kafka を使用して、デュアル書き込みによる[オンライン移行](migrating-online.md)プロセスを実装する方法の詳細については、「[Guidance for continuous data migration from Apache Cassandra to Amazon Keyspaces](https://aws.amazon.com/solutions/guidance/continuous-data-migration-from-apache-cassandra-to-amazon-keyspaces/)」を参照してください。
+ 大規模な移行については、抽出、変換、ロード (ETL) ツールの使用を検討してください。 AWS Glue を使用すると、データ変換移行を迅速かつ効果的に実行できます。詳細については、「[オフライン移行プロセス: Apache Cassandra から Amazon Keyspaces への移行](migrating-offline.md)」を参照してください。
+ Apache Cassandra Spark コネクタを使用して Amazon Keyspaces にデータを書き込む方法については、「[チュートリアル: Apache Spark と統合してデータをインポートまたはエクスポートする](spark-integrating.md)」を参照してください。
+ cqlsh `COPY FROM` コマンドを使用してデータを Amazon Keyspaces にロードすることから始めます。cqlsh は、Apache Cassandra に含まれており、小さなデータセットまたはテストデータのロードに最適です。手順については、「[チュートリアル: cqlsh を使用した Amazon Keyspaces へのデータのロード](bulk-upload.md)」を参照してください。
+ また、Apache Cassandra 用の DataStax Bulk Loader を使用すれば、`dsbulk` コマンドを使用して Amazon Keyspaces にデータをロードできます。DSBulk は、インポート機能が cqlsh よりも強力で、[GitHub リポジトリ](https://github.com/datastax/dsbulk)から入手できます。手順については、「[チュートリアル: DSBulk を使用した Amazon Keyspaces へのデータのロード](dsbulk-upload.md)」を参照してください。
Amazon Keyspaces へのデータアップロードに関する一般的な考慮事項
+ **データを小さな単位に分けてアップロードします。**
生データサイズの観点から、次の移行単位とその潜在的なフットプリントを考慮してください。1 つまたは複数のフェーズで少量ずつデータをアップロードすれば、移行を簡単に進めることができます。
+ **クラスター別** — すべての Cassandra データを一度に移行します。このアプローチはクラスターが小さければおそらく問題ありません。
+ **キースペース別またはテーブル別** - 移行をキースペースまたはテーブルのグループに分割します。このアプローチは、各ワークロードの要件に基づいてフェーズでデータを移行する場合に役立ちます。
+ **データ別** - データサイズを縮小するために、特定のユーザーまたは製品グループのデータを移行することを検討します。
+ **最初に優先的にアップロードするデータを処理のしやすさに基づいて決めます。**
特定の時間に変更されないデータ、夜間のバッチジョブのデータ、オフライン時間に使用されないデータ、内部アプリのデータなど、最初に簡単に移行できるデータがあるかどうかを検討します。
**Topics**
+ [チュートリアル: cqlsh を使用した Amazon Keyspaces へのデータのロード](bulk-upload.md)
+ [チュートリアル: DSBulk を使用した Amazon Keyspaces へのデータのロード](dsbulk-upload.md)
# チュートリアル: cqlsh を使用した Amazon Keyspaces へのデータのロード
このチュートリアルガイドでは、`cqlsh COPY FROM` コマンドを使用して Apache Cassandra から Amazon Keyspaces にデータを移行する手順を案内します。`cqlsh COPY FROM` コマンドは、学術的な目的やテスト用に小さなデータセットを Amazon Keyspaces に迅速かつ簡単にアップロードするのに便利です。本稼働ワークロードの移行方法の詳細については、「[オフライン移行プロセス: Apache Cassandra から Amazon Keyspaces への移行](migrating-offline.md)」を参照してください。このチュートリアルでは、次の手順を実行します。
前提条件 – 認証情報を使用して AWS アカウントを設定し、証明書の JKS トラストストアファイルを作成し、Amazon Keyspaces に接続する`cqlsh`ように を設定します。
1. **ソース CSV とターゲットテーブルの作成** – ソースデータとして CSV ファイルを準備し、Amazon Keyspaces でターゲットのキースペースとテーブルを作成します。
1. **データの準備** – CSV ファイル内のデータをランダム化して分析し、行サイズの平均値と最大値を求めます。
1. **スループットキャパシティの設定** – データサイズと必要なロード時間に基づいて必要な書き込みキャパシティユニット (WCU) を計算し、テーブルにプロビジョニングされるキャパシティを設定します。
1. **cqlsh パラメータの設定** – ワークロードを均等に分散させるために、`INGESTRATE`、`NUMPROCESSES`、`MAXBATCHSIZE`、`CHUNKSIZE` などの `cqlsh COPY FROM` パラメータの最適値を求めます。
1. **`cqlsh COPY FROM` コマンドの実行** – `cqlsh COPY FROM` コマンドを実行して、CSV ファイルから Amazon Keyspaces テーブルにデータをアップロードし、進行状況を監視します。
トラブルシューティング – 無効なリクエスト、パーサーエラー、キャパシティエラー、cqlsh エラーなど、データアップロードの処理中によく起きる問題を解決します。
**Topics**
+ [前提条件: `cqlsh COPY FROM` を使用してデータをアップロードする前に完了する手順](bulk-upload-prequs.md)
+ [ステップ 1: データアップロード用のソース CSV ファイルとターゲットテーブルを作成する](bulk-upload-source.md)
+ [ステップ 2: データを正常にアップロードできるようにソースデータを準備する](bulk-upload-prepare-data.md)
+ [ステップ 3: テーブルのスループットキャパシティを設定する](bulk-upload-capacity.md)
+ [ステップ 4: `cqlsh COPY FROM` を設定する](bulk-upload-config.md)
+ [ステップ 5: `cqlsh COPY FROM` コマンドを実行して CSV ファイルからターゲットテーブルにデータをアップロードする](bulk-upload-run.md)
+ [トラブルシューティング](bulk-upload-troubleshooting.md)
# 前提条件: `cqlsh COPY FROM` を使用してデータをアップロードする前に完了する手順
このチュートリアルを開始する前に、次のタスクを完了しておく必要があります。
1. まだサインアップしていない場合は、「」の手順に従って にサインアップ AWS アカウント します[セットアップ AWS Identity and Access Management](accessing.md#SettingUp.IAM)。
1. [Amazon Keyspaces にプログラムによってアクセスするためのサービス固有の認証情報を作成する](programmatic.credentials.ssc.md) のステップに従って、サービス固有の認証情報を作成します。
1. Cassandra クエリ言語シェル (cqlsh) 接続をセットアップし、[`cqlsh` を使用した Amazon Keyspaces への接続](programmatic.cqlsh.md) のステップに従って Amazon Keyspaces に接続できることを確認します。
# ステップ 1: データアップロード用のソース CSV ファイルとターゲットテーブルを作成する
このチュートリアルでは、`keyspaces_sample_table.csv` という名前のカンマ区切り値 (CSV) ファイルをデータ移行用のソースファイルとして使用します。提供されたサンプルファイルには、`book_awards` という名前のテーブルに関する数行のデータが含まれています。
1. ソースファイルを作成します。次のオプションのいずれかを選択します。
+ 次のアーカイブファイル [samplemigration.zip](samples/samplemigration.zip) に含まれているサンプル CSV ファイル (`keyspaces_sample_table.csv`) をダウンロードします。アーカイブを解凍し、`keyspaces_sample_table.csv` へのパスをメモしておきます。
+ Apache Cassandra データベースに保存されている独自のデータを CSV ファイルに入力するには、次の例に示すように、`cqlsh` `COPY TO` ステートメントを使用してソース CSV ファイルに入力します。
```
cqlsh localhost 9042 -u "username" -p "password" --execute "COPY mykeyspace.mytable TO 'keyspaces_sample_table.csv' WITH HEADER=true";
```
作成する CSV ファイルが以下の要件を満たしていることを確認してください。
+ 最初の行に列名が含まれています。
+ ソース CSV ファイルの列名がターゲットテーブルの列名と一致してます。
+ データがカンマで区切られてます。
+ すべてのデータ値が有効な Amazon Keyspaces データ型です。「[データ型](cql.elements.md#cql.data-types)」を参照してください。
1. Amazon Keyspaces でターゲットのキースペースとテーブルを作成します。
1. `cqlsh` を使用して Amazon Keyspaces に接続し、次の例のサービスエンドポイント、ユーザー名、およびパスワードをそれぞれ独自の値に置き換えます。
```
cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "111122223333" -p "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" --ssl
```
1. 次の例に示すように、`catalog` という名前の新しいキースペースを作成します。
```
CREATE KEYSPACE catalog WITH REPLICATION = {'class': 'SingleRegionStrategy'};
```
1. 新しいキースペースが利用可能になったら、次のコードを使用してターゲットテーブル `book_awards` を作成します。
```
CREATE TABLE "catalog.book_awards" (
year int,
award text,
rank int,
category text,
book_title text,
author text,
publisher text,
PRIMARY KEY ((year, award), category, rank)
);
```
Apache Cassandra が元のデータソースである場合、ヘッダーが一致している Amazon Keyspaces ターゲットテーブルを作成する簡単な方法は、次のステートメントに示すように、ソーステーブルから `CREATE TABLE` ステートメントを生成する方法です。
```
cqlsh localhost 9042 -u "username" -p "password" --execute "DESCRIBE TABLE mykeyspace.mytable;"
```
次に、Amazon Keyspaces で、列名とデータ型が Cassandra ソーステーブルの説明と一致しているターゲットテーブルを作成します。
# ステップ 2: データを正常にアップロードできるようにソースデータを準備する
効率的な転送のためのソースデータの準備には、2 つのステップがあります。まず、データをランダム化します。第 2 のステップでは、データが正常にアップロードされるように、データを分析して、適切な `cqlsh` パラメータ値と必要なテーブル設定を判断します。
**データをランダム化する**
`cqlsh COPY FROM` コマンドは、CSV ファイルに表示される順序と同じ順序でデータの読み取りと書き込みを行います。`cqlsh COPY TO` コマンドを使用してソースファイルを作成すると、データはキーソートされた順序で CSV に書き込まれます。内部的には、Amazon Keyspaces でパーティションキーを使用してデータが分割されます。Amazon Keyspaces には、同一のパーティションキーに対するロードバランスリクエストに役立つロジックが内蔵されていますが、順序をランダム化すると、データのロードが高速かつ効率的になります。これは、Amazon Keyspaces で異なるパーティションにデータが書き込まれたときに発生する組み込みのロードバランシングを利用できるためです。
パーティション間で書き込みを均等に分散させるには、ソースファイル内のデータをランダム化する必要があります。アプリケーションを書き込んでこれを実行することができます。また、[Shuf](https://en.wikipedia.org/wiki/Shuf) などのオープンソースツールを使用することもできます。Shuf は、Linux ディストリビューション、macOS (コアユーティリティを [homebrew](https://brew.sh) にインストールする)、Windows (Windows Subsystem for Linux (WSL) を使用する) で無料で使用できます。このステップで列名を含むヘッダー行がシャッフルされないようにするには、追加のステップが 1 つ必要です。
ヘッダーを維持した状態でソースファイルをランダム化するには、次のコードを入力します。
```
tail -n +2 keyspaces_sample_table.csv | shuf -o keyspace.table.csv && (head -1 keyspaces_sample_table.csv && cat keyspace.table.csv ) > keyspace.table.csv1 && mv keyspace.table.csv1 keyspace.table.csv
```
Shuf により、`keyspace.table.csv` という新しい CSV ファイルにデータが書き換えられます。これで、不要になった `keyspaces_sample_table.csv` ファイルを削除できます。
**データを分析する**
データを分析して、平均行サイズと最大行サイズを決定します。
この作業を行う理由は次のとおりです。
+ 転送されるデータの総量を見積もる場合に、平均行サイズが役立ちます。
+ データのアップロードに必要な書き込みキャパシティをプロビジョニングする際には、平均行サイズが必要になります。
+ 各行のサイズが 1 MB 未満 (Amazon Keyspaces の行サイズの上限) であることを確認できます。
**注記**
このクォータは、パーティションサイズではなく、行サイズを指します。Apache Cassandra のパーティションとは異なり、Amazon Keyspaces のパーティションのサイズは事実上無制限です。パーティションキーとクラスタリング列には、メタデータ用の追加のストレージが必要です。このストレージは行の raw サイズに追加する必要があります。詳細については、「[Amazon Keyspaces で行のサイズを推定する](calculating-row-size.md)」を参照してください。
次のコードは、[AWK](https://en.wikipedia.org/wiki/AWK) を使用して CSV ファイルを分析し、行の平均サイズと最大サイズを出力します。
```
awk -F, 'BEGIN {samp=10000;max=-1;}{if(NR>1){len=length($0);t+=len;avg=t/NR;max=(len>max ? len : max)}}NR==samp{exit}END{printf("{lines: %d, average: %d bytes, max: %d bytes}\n",NR,avg,max);}' keyspace.table.csv
```
このコードを実行すると、次の出力が表示されます。
```
using 10,000 samples:
{lines: 10000, avg: 123 bytes, max: 225 bytes}
```
このチュートリアルの次のステップの平均行サイズを使用して、テーブルの書き込みキャパシティをプロビジョニングします。
# ステップ 3: テーブルのスループットキャパシティを設定する
このチュートリアルでは、設定された時間範囲内でデータがロードされるように cqlsh を調整する方法を示します。事前に実行する読み取りと書き込みの数がわかっているので、プロビジョンドキャパシティモードを使用します。データ転送が完了したら、アプリケーションのトラフィックパターンに合わせてテーブルのキャパシティモードを設定する必要があります。キャパシティ管理の詳細については、「[Amazon Keyspaces (Apache Cassandra 向け) でのサーバーレスリソースの管理](serverless_resource_management.md)」を参照してください。
プロビジョンドキャパシティモードでは、事前にテーブルにプロビジョニングする読み取りキャパシティと書き込みキャパシティの量を指定します。書き込みキャパシティは時間ユニットで課金され、書き込みキャパシティユニット (WCU) で計測されます。各 WCU は、1 秒あたり 1 KB のデータの書き込みをサポートするのに十分な書き込みキャパシティです。データをロードする際に、書き込みレートが、ターゲットテーブルで設定した WCU の上限 (パラメータ: `write_capacity_units`) を超えないようにしてください。
デフォルトでは、1 つのテーブルに最大 40,000 の WCU を、アカウント内のすべてのテーブルに最大 80,000 の WCU をプロビジョニングすることができます。追加のキャパシティが必要な場合は、[Service Quotas](https://console.aws.amazon.com/servicequotas/home#!/services/cassandra/quotas) コンソールでクォータの増加をリクエストできます。クォータの詳細については、「[Amazon Keyspaces (Apache Cassandra 向け) のクォータ](quotas.md)」を参照してください。
**挿入に必要な WCU の平均数を計算する**
1 秒あたり 1 KB のデータを挿入するには、1 WCU が必要です。CSV ファイルに 360,000 の行があり、1 時間ですべてのデータをロードする場合は、1 秒あたり 100 行 (360,000 行 / 60 分 / 60 秒 = 100 行/秒) を書き込む必要があります。各行に最大 1 KB のデータがある場合、1 秒あたり 100 行を挿入するには、100 WCU をテーブルにプロビジョニングする必要があります。各行に 1.5 KB のデータがある場合、1 秒あたり 1 行を挿入するには 2 WCU が必要です。したがって、1 秒あたり 100 行を挿入するには、200 WCU をプロビジョニングする必要があります。
1 秒あたり 1 行の挿入が必要な WCU 数を調べるには、平均行サイズ (バイト) を 1024 で割り、端数を切り上げて最も近い整数にします。
例えば、平均行サイズが 3000 バイトの場合、1 秒あたり 1 行を挿入するには 3 WCU が必要です。
```
ROUNDUP(3000 / 1024) = ROUNDUP(2.93) = 3 WCUs
```
**データのロード時間とキャパシティを計算する**
これで、CSV ファイルの平均サイズと平均行数が分かったので、特定の時間内にデータをロードする場合に必要な WCU 数と、さまざまな WCU 設定を使用して CSV ファイルにすべてのデータをロードするのにかかるおおよその時間を計算できます。
例えば、ファイルの各行が 1 KB で、CSV ファイルに 1,000,000 行がある場合、1 時間でデータをロードするには、その時間に少なくとも 278 WCU をテーブルにプロビジョニングする必要があります。
```
1,000,000 rows * 1 KBs = 1,000,000 KBs
1,000,000 KBs / 3600 seconds =277.8 KBs / second = 278 WCUs
```
**プロビジョンドキャパシティを設定する**
テーブルの書き込みキャパシティは、そのテーブルの作成時、または `ALTER TABLE` CQL コマンドを使用して、設定することができます。以下は、`ALTER TABLE` CQL ステートメントを使用してテーブルのプロビジョンキャパシティ設定に変更を加えるための構文です。
```
ALTER TABLE mykeyspace.mytable WITH custom_properties={'capacity_mode':{'throughput_mode': 'PROVISIONED', 'read_capacity_units': 100, 'write_capacity_units': 278}} ;
```
完全な言語リファレンスについては、「[ALTER TABLE](cql.ddl.table.md#cql.ddl.table.alter)」を参照してください。
# ステップ 4: `cqlsh COPY FROM` を設定する
このセクションでは、`cqlsh COPY FROM` のパラメータ値を決定する方法について説明します。`cqlsh COPY FROM` コマンドは、前の手順で準備した CSV ファイルを読み取り、CQL を使用して Amazon Keyspaces にデータを挿入します。このコマンドにより、行の分割と一連のワーカー間での `INSERT` オペレーションの配分が行われます。各ワーカーは Amazon Keyspaces との接続を確立し、このチャンネルに沿って `INSERT` リクエストを送信します。
`cqlsh COPY` コマンドには、ワーカー間でワークを均等に分配するための内部ロジックがありません。ただし、ワークが均等に分配されるように手動で設定することはできます。まず、次の主要な cqlsh パラメータを確認します。
+ **DELIMITER** — カンマ以外の区切り文字を使用した場合はこのパラメータを設定できます。デフォルトはカンマです。
+ **INGESTRATE** — `cqlsh COPY FROM` により処理が試行される 1 秒あたりのターゲット行数。設定しない場合のデフォルト値は 100,000 です。
+ **NUMPROCESSES** — `COPY FROM` タスクに対して cqlsh により作成される子ワーカープロセスの数。この設定の最大値は 16 で、デフォルトは `num_cores - 1` です。`num_cores` は cqlsh が実行されているホストの処理コア数です。
+ **MAXBATCHSIZE** - バッチサイズにより、1 つのバッチで挿入先テーブルに挿入される最大行数が決まります。設定されていない場合、cqlsh により挿入行数が 20 行のバッチが使用されます。
+ **CHUNKSIZE** — 子ワーカーに渡すワーク単位のサイズ。デフォルトでは、5,000 に設定されます。
+ **MAXATTEMPTS** — 失敗したワーカーチャンクの再試行の最高回数。最高試行回数に達すると、失敗したレコードが新しい CSV ファイルに書き込まれ、後ほど、失敗を調査した上で再実行できます。
ターゲット送信先テーブルにプロビジョニングした WCU の数に基づいて `INGESTRATE` を設定します。`cqlsh COPY FROM` コマンドの `INGESTRATE` は制限ではなくターゲット平均です。これは、設定した数を大きく上回る可能性がある (多くの場合そうなる) ことを意味します。このような超過を許可し、データロードリクエストを処理できるだけの十分なキャパシティを確保するには、`INGESTRATE` をテーブルの書き込みキャパシティの 90% に設定します。
```
INGESTRATE = WCUs * .90
```
次に、`NUMPROCESSES` パラメータを、システムのコア数より 1 少ない値に設定します。システムのコア数を調べるには、次のコードを実行します。
```
python -c "import multiprocessing; print(multiprocessing.cpu_count())"
```
このチュートリアルでは、以下の値を使用します。
```
NUMPROCESSES = 4
```
各プロセスでワーカーが作成され、各ワーカーで Amazon Keyspaces への接続が確立されます。Amazon Keyspaces は、接続ごとに 1 秒あたり最大で 3,000 件の CQL リクエストに対応できます。つまり、各ワーカーの 1 秒あたりのリクエスト処理数が 3,000 件未満であるか確認する必要があるということです。
`INGESTRATE` と同様に、ワーカーは設定した数値を大幅に上回ることが多く、クロックの秒数に制限されません。したがって、大幅な超過を考慮しておくために、各ワーカーの 1 秒あたりの目標リクエスト処理数が 2,500 件になるように cqlsh パラメータを設定します。ワーカーに分配されるワーク量を計算するには、次のガイドラインを使用します。
+ `INGESTRATE` を `NUMPROCESSES` で割ります。
+ `INGESTRATE` / `NUMPROCESSES` > 2,500 になった場合は、この式が真になるように `INGESTRATE` を下げます。
```
INGESTRATE / NUMPROCESSES <= 2,500
```
サンプルデータのアップロードを最適化するための設定を行う前に、`cqlsh` のデフォルト設定を再確認し、その使用がデータのアップロードプロセスにどのように影響するのか見てみましょう。`cqlsh COPY FROM` では `CHUNKSIZE` を使用して膨大なワークが作成されて (`INSERT` ステートメント) ワーカーに分配されるので、ワークは自動的には均等に分配されません。`INGESTRATE` 設定によっては、アイドル状態になるワーカーもあります。
ワーカー間でワークを均等に分配し、各ワーカーに対して 1 秒あたりの最適なリクエスト数を 2,500 件で維持するには、入力パラメータを変更して `CHUNKSIZE`、`MAXBATCHSIZE`、`INGESTRATE` に設定する必要があります。データロード中のネットワークトラフィックの使用率を最適化するには、`MAXBATCHSIZE` の値として最大値の 30 に近い値を選択します。`CHUNKSIZE` を 100 に、`MAXBATCHSIZE` を 25 に変更すると、10,000 行が 4 つのワーカーに均等に分配されます (10,000 / 2500 = 4)、
次のコード例はこのことを示しています。
```
INGESTRATE = 10,000
NUMPROCESSES = 4
CHUNKSIZE = 100
MAXBATCHSIZE. = 25
Work Distribution:
Connection 1 / Worker 1 : 2,500 Requests per second
Connection 2 / Worker 2 : 2,500 Requests per second
Connection 3 / Worker 3 : 2,500 Requests per second
Connection 4 / Worker 4 : 2,500 Requests per second
```
要約するために、`cqlsh COPY FROM` パラメータの設定時に次の数式を使用します。
+ **INGESTRATE** = write\$1capacity\$1units \$1 .90
+ **NUMPROCESSES** = num\$1cores -1 (デフォルト)
+ **INGESTRATE / NUMPROCESSES** = 2,500 (これは true ステートメントでなければなりません。)
+ **MAXBATCHSIZE** = 30 (デフォルトは 20。Amazon Keyspaces では最大で 30 のバッチが受け入れられます。)
+ **CHUNKSIZE** = (INGESTRATE / NUMPROCESSES) / MAXBATCHSIZE
これで `NUMPROCESSES`、`INGESTRATE`、`CHUNKSIZE` の計算が完了し、データをロードする準備が整いました。
# ステップ 5: `cqlsh COPY FROM` コマンドを実行して CSV ファイルからターゲットテーブルにデータをアップロードする
`cqlsh COPY FROM` コマンドを使用して、以下のステップを実行します。
1. cqlsh を使用して Amazon Keyspaces に接続します。
1. 次のコードがあるキースペースを選択します。
```
USE catalog;
```
1. 書き込み整合性を `LOCAL_QUORUM` に設定します。データの耐久性を確保するため、Amazon Keyspaces では他の書き込み整合性設定は使用できません。以下のコードを参照してください。
```
CONSISTENCY LOCAL_QUORUM;
```
1. 次のコード例を使用して `cqlsh COPY FROM` 構文を作成します。
```
COPY book_awards FROM './keyspace.table.csv' WITH HEADER=true
AND INGESTRATE=calculated ingestrate
AND NUMPROCESSES=calculated numprocess
AND MAXBATCHSIZE=20
AND CHUNKSIZE=calculated chunksize;
```
1. 前のステップで準備したステートメントを実行します。cqlsh は、構成したすべての設定をエコーバックします。
1. 設定が入力と一致していることを確認します。次の例を参照してください。
```
Reading options from the command line: {'chunksize': '120', 'header': 'true', 'ingestrate': '36000', 'numprocesses': '15', 'maxbatchsize': '20'}
Using 15 child processes
```
1. 次の例に示すように、転送された行数と現在の平均レートを確認します。
```
Processed: 57834 rows; Rate: 6561 rows/s; Avg. rate: 31751 rows/s
```
1. cqlsh によるデータのアップロードが完了したら、次の例に示すように、データロード統計のサマリー (読み取られたファイルの数、ランタイム、スキップされた行数) を確認します。
```
15556824 rows imported from 1 files in 8 minutes and 8.321 seconds (0 skipped).
```
このチュートリアルの最後のステップでは、データを Amazon Keyspaces にアップロードしました。
**重要**
データを転送したので、アプリケーションの通常のトラフィックパターンに合わせてターゲットテーブルのキャパシティモード設定を調整します。プロビジョンドキャパシティは、変更するまでは、時間ユニットで課金されます。
# トラブルシューティング
データのアップロードが完了したら、行がスキップされたかどうかを確認します。これを行うには、ソース CSV ファイルのソースディレクトリに移動し、次の名前のファイルを検索します。
```
import_yourcsvfilename.err.timestamp.csv
```
cqlsh により、この名前のファイルに、スキップされたデータ行が書き込まれます。ファイルがソースディレクトリに存在し、その中にデータが含まれている場合、これらの行は Amazon Keyspaces にアップロードされませんでした。これらの行のアップロードを再試行するには、まずアップロード中に発生したエラーを確認し、それに応じてデータを調整します。これらの行のアップロードを再試行するために、プロセスを再実行します。
**一般的なエラー**
行がロードされない最も一般的な理由は、容量エラーとパーサーエラーです。
**Amazon Keyspaces にデータをアップロードする際の不正なリクエストエラー**
次の例では、ソーステーブルにカウンター列が含まれているため、`COPY` cqlshコマンドからのバッチ呼び出しがログに記録されます。Amazon Keyspaces では、ログに記録されたバッチコールはサポートされていません。
```
Failed to import 10 rows: InvalidRequest - Error from server: code=2200 [Invalid query] message=“Only UNLOGGED Batches are supported at this time.“, will retry later, attempt 22 of 25
```
このエラーを解決するには、DSBulk を使用してデータを移行します。詳細については、「[チュートリアル: DSBulk を使用した Amazon Keyspaces へのデータのロード](dsbulk-upload.md)」を参照してください。
**Amazon Keyspaces にデータをアップロードする際のパーサーエラー**
次の例では、`ParseError` が原因で行がスキップされます。
```
Failed to import 1 rows: ParseError - Invalid ... –
```
このエラーを解決するには、インポートするデータが Amazon Keyspaces のテーブルスキーマと一致していることを確認する必要があります。インポートファイルで解析エラーが発生していないか確認してください。`INSERT` ステートメントを使用してエラーを切り離すことで、1 行のデータの使用を試すことができます。
**Amazon Keyspaces にデータをアップロードする際の容量エラー**
```
Failed to import 1 rows: WriteTimeout - Error from server: code=1100 [Coordinator node timed out waiting for replica nodes' responses]
message="Operation timed out - received only 0 responses." info={'received_responses': 0, 'required_responses': 2, 'write_type': 'SIMPLE', 'consistency':
'LOCAL_QUORUM'}, will retry later, attempt 1 of 100
```
Amazon Keyspaces では、スループットキャパシティ不足により書き込みリクエストが失敗した場合に、`ReadTimeout` 例外と `WriteTimeout` 例外を使用してその失敗が示されます。キャパシティ不足の例外を診断するために、Amazon Keyspaces は Amazon CloudWatch で `WriteThrottleEvents` と `ReadThrottledEvents` のメトリクスを公開しています。詳細については、「[Amazon CloudWatch による Amazon Keyspaces のモニタリング](monitoring-cloudwatch.md)」を参照してください。
**Amazon Keyspaces にデータをアップロードする際の cqlsh エラー**
cqlsh エラーのトラブルシューティングに役立てるために、失敗したコマンドに `--debug` フラグを付けて再実行します。
互換性のないバージョンの cqlsh を使用すると、次のエラーが表示されます。
```
AttributeError: 'NoneType' object has no attribute 'is_up'
Failed to import 3 rows: AttributeError - 'NoneType' object has no attribute 'is_up', given up after 1 attempts
```
次のコマンドを実行して、正しいバージョンの cqlsh がインストールされていることを確認します。
```
cqlsh --version
```
出力に関して次のような内容が表示されます。
```
cqlsh 5.0.1
```
Windows を使用している場合は、`cqlsh` のすべてのインスタンスを `cqlsh.bat` に置き換えます。例えば、Windows で cqlsh のバージョンを確認するには、次のコマンドを実行します。
```
cqlsh.bat --version
```
サーバーから cqlsh クライアントに何らかの種類のエラーが 3 回連続で送信されると、Amazon Keyspaces への接続が失敗します。cqlsh クライアントで処理が失敗すると、次のメッセージが表示されます。
```
Failed to import 1 rows: NoHostAvailable - , will retry later, attempt 3 of 100
```
このエラーを解決するには、インポートするデータが Amazon Keyspaces のテーブルスキーマと一致していることを確認する必要があります。インポートファイルで解析エラーが発生していないか確認してください。INSERT ステートメントを使用してエラーを切り離すことで、1 行のデータの使用を試すことができます。
クライアントにより接続の再確立が自動的に試行されます。
# チュートリアル: DSBulk を使用した Amazon Keyspaces へのデータのロード
このステップバイステップのチュートリアルでは、[GitHub](https://github.com/datastax/dsbulk.git) で入手できる DataStax Bulk Loader (DSBulk) を使用して、Apache Cassandra から Amazon Keyspaces にデータを移行する手順が説明されています。DSBulk は、学術用途やテスト目的で Amazon Keyspaces にデータセットをアップロードする場合に便利です。本稼働ワークロードの移行方法の詳細については、「[オフライン移行プロセス: Apache Cassandra から Amazon Keyspaces への移行](migrating-offline.md)」を参照してください。このチュートリアルでは、次の手順を実行します。
前提条件 – 認証情報を使用して AWS アカウントを設定し、証明書の JKS トラストストアファイルを作成し、 を設定し`cqlsh`、DSBulk をダウンロードしてインストールし、 `application.conf` ファイルを設定します。
1. **ソース CSV とターゲットテーブルの作成** – ソースデータとして CSV ファイルを準備し、Amazon Keyspaces でターゲットのキースペースとテーブルを作成します。
1. **データの準備** – CSV ファイル内のデータをランダム化して分析し、行サイズの平均値と最大値を求めます。
1. **スループットキャパシティの設定** – データサイズと必要なロード時間に基づいて必要な書き込みキャパシティユニット (WCU) を計算し、テーブルにプロビジョニングされるキャパシティを設定します。
1. **DSBulk 設定の構成** – 認証、SSL/TLS、整合性レベル、接続プールサイズなどを設定した、DSBulk 設定ファイルを作成します。
1. **DSBulk ロードコマンドの実行** – DSBulk ロードコマンドを実行して、CSV ファイルから Amazon Keyspaces テーブルにデータをアップロードし、進行状況を監視します。
**Topics**
+ [前提条件: DSBulk でデータをアップロードする前に完了する手順](dsbulk-upload-prequs.md)
+ [ステップ 1: DSBulk を使用してデータアップロード用のソース CSV ファイルとターゲットテーブルを作成する](dsbulk-upload-source.md)
+ [ステップ 2: DSBulk を使用してアップロード対象のデータを準備する](dsbulk-upload-prepare-data.md)
+ [ステップ 3: ターゲットテーブルのスループットキャパシティを設定する](dsbulk-upload-capacity.md)
+ [ステップ 4: CSV ファイルからターゲットテーブルにデータをアップロードするように `DSBulk` を設定する](dsbulk-upload-config.md)
+ [ステップ 5: DSBulk `load` コマンドを実行して CSV ファイルからターゲットテーブルにデータをアップロードする](dsbulk-upload-run.md)
# 前提条件: DSBulk でデータをアップロードする前に完了する手順
このチュートリアルを開始する前に、次のタスクを完了しておく必要があります。
1. まだサインアップしていない場合は、「」の手順に従って AWS アカウントにサインアップします[セットアップ AWS Identity and Access Management](accessing.md#SettingUp.IAM)。
1. [Amazon Keyspaces の AWS 認証情報の作成と設定](access.credentials.md) のステップに従って認証情報を作成します。
1. JKS 信頼ストアファイルを作成します。
1. 次のデジタル証明書をダウンロードし、ローカルまたはホームディレクトリにファイルを保存します。
1. AmazonRootCA1
1. AmazonRootCA2
1. AmazonRootCA3
1. AmazonRootCA4
1. Starfield クラス 2 ルート (オプション – 下位互換性用)
証明書をダウンロードするには、次のコマンドを使用できます。
```
curl -O https://www.amazontrust.com/repository/AmazonRootCA1.pem
curl -O https://www.amazontrust.com/repository/AmazonRootCA2.pem
curl -O https://www.amazontrust.com/repository/AmazonRootCA3.pem
curl -O https://www.amazontrust.com/repository/AmazonRootCA4.pem
curl -O https://certs.secureserver.net/repository/sf-class2-root.crt
```
**注記**
Amazon Keyspaces は以前、Starfield Class 2 CA に固定された TLS 証明書を使用していました。 AWS は、Amazon Trust Services (Amazon ルート CAs で発行された証明書 AWS リージョン にすべて移行しています。この移行中に、Amazon ルート CAs 1～4 と Starfield ルートの両方を信頼するようにクライアントを設定し、すべてのリージョンで互換性を確保します。
1. デジタル証明書を trustStore ファイルに変換し、キーストアに追加します。
```
openssl x509 -outform der -in AmazonRootCA1.pem -out temp_file.der
keytool -import -alias amazon-root-ca-1 -keystore cassandra_truststore.jks -file temp_file.der
openssl x509 -outform der -in AmazonRootCA2.pem -out temp_file.der
keytool -import -alias amazon-root-ca-2 -keystore cassandra_truststore.jks -file temp_file.der
openssl x509 -outform der -in AmazonRootCA3.pem -out temp_file.der
keytool -import -alias amazon-root-ca-3 -keystore cassandra_truststore.jks -file temp_file.der
openssl x509 -outform der -in AmazonRootCA4.pem -out temp_file.der
keytool -import -alias amazon-root-ca-4 -keystore cassandra_truststore.jks -file temp_file.der
openssl x509 -outform der -in sf-class2-root.crt -out temp_file.der
keytool -import -alias cassandra -keystore cassandra_truststore.jks -file temp_file.der
```
最後のステップでは、キーストアのパスワードを作成し、各証明書を信頼する必要があります。対話型コマンドは次のようになります。
```
Enter keystore password:
Re-enter new password:
Owner: CN=Amazon Root CA 1, O=Amazon, C=US
Issuer: CN=Amazon Root CA 1, O=Amazon, C=US
Serial number: 66c9fcf99bf8c0a39e2f0788a43e696365bca
Valid from: Tue May 26 00:00:00 UTC 2015 until: Sun Jan 17 00:00:00 UTC 2038
Certificate fingerprints:
SHA1: 8D:A7:F9:65:EC:5E:FC:37:91:0F:1C:6E:59:FD:C1:CC:6A:6E:DE:16
SHA256: 8E:CD:E6:88:4F:3D:87:B1:12:5B:A3:1A:C3:FC:B1:3D:70:16:DE:7F:57:CC:90:4F:E1:CB:97:C6:AE:98:19:6E
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#2: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
DigitalSignature
Key_CertSign
Crl_Sign
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 84 18 CC 85 34 EC BC 0C 94 94 2E 08 59 9C C7 B2 ....4.......Y...
0010: 10 4E 0A 08 .N..
]
]
Trust this certificate? [no]: yes
Certificate was added to keystore
Enter keystore password:
Owner: CN=Amazon Root CA 2, O=Amazon, C=US
Issuer: CN=Amazon Root CA 2, O=Amazon, C=US
Serial number: 66c9fd29635869f0a0fe58678f85b26bb8a37
Valid from: Tue May 26 00:00:00 UTC 2015 until: Sat May 26 00:00:00 UTC 2040
Certificate fingerprints:
SHA1: 5A:8C:EF:45:D7:A6:98:59:76:7A:8C:8B:44:96:B5:78:CF:47:4B:1A
SHA256: 1B:A5:B2:AA:8C:65:40:1A:82:96:01:18:F8:0B:EC:4F:62:30:4D:83:CE:C4:71:3A:19:C3:9C:01:1E:A4:6D:B4
Signature algorithm name: SHA384withRSA
Subject Public Key Algorithm: 4096-bit RSA key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#2: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
DigitalSignature
Key_CertSign
Crl_Sign
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: B0 0C F0 4C 30 F4 05 58 02 48 FD 33 E5 52 AF 4B ...L0..X.H.3.R.K
0010: 84 E3 66 52 ..fR
]
]
Trust this certificate? [no]: yes
Certificate was added to keystore
Enter keystore password:
Owner: CN=Amazon Root CA 3, O=Amazon, C=US
Issuer: CN=Amazon Root CA 3, O=Amazon, C=US
Serial number: 66c9fd5749736663f3b0b9ad9e89e7603f24a
Valid from: Tue May 26 00:00:00 UTC 2015 until: Sat May 26 00:00:00 UTC 2040
Certificate fingerprints:
SHA1: 0D:44:DD:8C:3C:8C:1A:1A:58:75:64:81:E9:0F:2E:2A:FF:B3:D2:6E
SHA256: 18:CE:6C:FE:7B:F1:4E:60:B2:E3:47:B8:DF:E8:68:CB:31:D0:2E:BB:3A:DA:27:15:69:F5:03:43:B4:6D:B3:A4
Signature algorithm name: SHA256withECDSA
Subject Public Key Algorithm: 256-bit EC (secp256r1) key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#2: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
DigitalSignature
Key_CertSign
Crl_Sign
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: AB B6 DB D7 06 9E 37 AC 30 86 07 91 70 C7 9C C4 ......7.0...p...
0010: 19 B1 78 C0 ..x.
]
]
Trust this certificate? [no]: yes
Certificate was added to keystore
Enter keystore password:
Owner: CN=Amazon Root CA 4, O=Amazon, C=US
Issuer: CN=Amazon Root CA 4, O=Amazon, C=US
Serial number: 66c9fd7c1bb104c2943e5717b7b2cc81ac10e
Valid from: Tue May 26 00:00:00 UTC 2015 until: Sat May 26 00:00:00 UTC 2040
Certificate fingerprints:
SHA1: F6:10:84:07:D6:F8:BB:67:98:0C:C2:E2:44:C2:EB:AE:1C:EF:63:BE
SHA256: E3:5D:28:41:9E:D0:20:25:CF:A6:90:38:CD:62:39:62:45:8D:A5:C6:95:FB:DE:A3:C2:2B:0B:FB:25:89:70:92
Signature algorithm name: SHA384withECDSA
Subject Public Key Algorithm: 384-bit EC (secp384r1) key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#2: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
DigitalSignature
Key_CertSign
Crl_Sign
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: D3 EC C7 3A 65 6E CC E1 DA 76 9A 56 FB 9C F3 86 ...:en...v.V....
0010: 6D 57 E5 81 mW..
]
]
Trust this certificate? [no]: yes
Certificate was added to keystore
Enter keystore password:
Owner: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US
Issuer: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US
Serial number: 0
Valid from: Tue Jun 29 17:39:16 UTC 2004 until: Thu Jun 29 17:39:16 UTC 2034
Certificate fingerprints:
SHA1: AD:7E:1C:28:B0:64:EF:8F:60:03:40:20:14:C3:D0:E3:37:0E:B5:8A
SHA256: 14:65:FA:20:53:97:B8:76:FA:A6:F0:A9:95:8E:55:90:E4:0F:CC:7F:AA:4F:B7:C2:C8:67:75:21:FB:5F:B6:58
Signature algorithm name: SHA1withRSA (weak)
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: BF 5F B7 D1 CE DD 1F 86 F4 5B 55 AC DC D7 10 C2 ._.......[U.....
0010: 0E A9 88 E7 ....
]
[OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US]
SerialNumber: [ 00]
]
#2: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
CA:true
PathLen:2147483647
]
#3: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: BF 5F B7 D1 CE DD 1F 86 F4 5B 55 AC DC D7 10 C2 ._.......[U.....
0010: 0E A9 88 E7 ....
]
]
Warning:
The input uses the SHA1withRSA signature algorithm which is considered a security risk. This algorithm will be disabled in a future update.
Trust this certificate? [no]: yes
Certificate was added to keystore
```
1. Cassandra クエリ言語シェル (cqlsh) 接続をセットアップし、[`cqlsh` を使用した Amazon Keyspaces への接続](programmatic.cqlsh.md) のステップに従って Amazon Keyspaces に接続できることを確認します。
1. DSBulk をダウンロードしてインストールします。
**注記**
このチュートリアルで示されているバージョンは、利用可能な最新バージョンではない可能性があります。DSBulk をダウンロードする前に、[DataStax Bulk Loader のダウンロードページで](https://downloads.datastax.com/#bulk-loader)最新バージョンを確認し、それに応じて次のコマンドのバージョン番号を更新します。
1. DSBulk をダウンロードするには、次のコードを使用します。
```
curl -OL https://downloads.datastax.com/dsbulk/dsbulk-1.8.0.tar.gz
```
1. 次に、tar ファイルを解凍し、以下の例に示されているように、DSBulk を `PATH` に追加します。
```
tar -zxvf dsbulk-1.8.0.tar.gz
# add the DSBulk directory to the path
export PATH=$PATH:./dsbulk-1.8.0/bin
```
1. DSBulk により使用される設定を保存するための `application.conf` ファイルを作成します。次の例を `./dsbulk_keyspaces.conf` として保存できます。ローカルノード上にいない場合は、`localhost` を、ローカルの Cassandra クラスターのコンタクトポイント (DNS 名や IP アドレスなど) に置き換えます。ファイル名とパスは、後で `dsbulk load` コマンドで指定する必要があるためメモしておいてください。
```
datastax-java-driver {
basic.contact-points = [ "localhost"]
advanced.auth-provider {
class = software.aws.mcs.auth.SigV4AuthProvider
aws-region = us-east-1
}
}
```
1. SigV4 サポートを有効にするには、次の例に示すように、[GitHub](https://github.com/aws/aws-sigv4-auth-cassandra-java-driver-plugin/releases/) からシェード `jar` ファイルをダウンロードし、DSBulk `lib` フォルダに配置します。
```
curl -O -L https://github.com/aws/aws-sigv4-auth-cassandra-java-driver-plugin/releases/download/4.0.6-shaded-v2/aws-sigv4-auth-cassandra-java-driver-plugin-4.0.6-shaded.jar
```
# ステップ 1: DSBulk を使用してデータアップロード用のソース CSV ファイルとターゲットテーブルを作成する
このチュートリアルでは、`keyspaces_sample_table.csv` という名前のカンマ区切り値 (CSV) ファイルをデータ移行用のソースファイルとして使用します。提供されたサンプルファイルには、`book_awards` という名前のテーブルに関する数行のデータが含まれています。
1. ソースファイルを作成します。次のオプションのいずれかを選択します。
+ 次のアーカイブファイル [samplemigration.zip](samples/samplemigration.zip) に含まれているサンプル CSV ファイル (`keyspaces_sample_table.csv`) をダウンロードします。アーカイブを解凍し、`keyspaces_sample_table.csv` へのパスをメモしておきます。
+ Apache Cassandra データベースに保存されている独自のデータを CSV ファイルに入力するには、次の例に示すように、`dsbulk unload` を使用してソース CSV ファイルに入力します。
```
dsbulk unload -k mykeyspace -t mytable -f ./my_application.conf > keyspaces_sample_table.csv
```
作成する CSV ファイルが以下の要件を満たしていることを確認してください。
+ 最初の行に列名が含まれています。
+ ソース CSV ファイルの列名がターゲットテーブルの列名と一致してます。
+ データがカンマで区切られてます。
+ すべてのデータ値が有効な Amazon Keyspaces データ型です。「[データ型](cql.elements.md#cql.data-types)」を参照してください。
1. Amazon Keyspaces でターゲットのキースペースとテーブルを作成します。
1. `cqlsh` を使用して Amazon Keyspaces に接続し、次の例のサービスエンドポイント、ユーザー名、およびパスワードをそれぞれ独自の値に置き換えます。
```
cqlsh cassandra.us-east-1.amazonaws.com 9142 -u "111122223333" -p "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" --ssl
```
1. 次の例に示すように、`catalog` という名前の新しいキースペースを作成します。
```
CREATE KEYSPACE catalog WITH REPLICATION = {'class': 'SingleRegionStrategy'};
```
1. 新しいキースペースが利用可能な状態になったら、次のコードを使用してターゲットテーブル `book_awards` を作成します。非同期的なリソース作成と、リソースが利用可能かどうかを確認する方法については、「[Amazon Keyspaces でキースペースの作成ステータスを確認する](keyspaces-create.md)」を参照してください。
```
CREATE TABLE catalog.book_awards (
year int,
award text,
rank int,
category text,
book_title text,
author text,
publisher text,
PRIMARY KEY ((year, award), category, rank)
);
```
Apache Cassandra が元のデータソースである場合、ヘッダーが一致している Amazon Keyspaces ターゲットテーブルを作成する簡単な方法は、次のステートメントに示すように、ソーステーブルから `CREATE TABLE` ステートメントを生成する方法です。
```
cqlsh localhost 9042 -u "username" -p "password" --execute "DESCRIBE TABLE mykeyspace.mytable;"
```
次に、Amazon Keyspaces で、列名とデータ型が Cassandra ソーステーブルの説明と一致しているターゲットテーブルを作成します。
# ステップ 2: DSBulk を使用してアップロード対象のデータを準備する
効率的な転送のためのソースデータの準備には、2 つのステップがあります。まず、データをランダム化します。2 番目のステップでは、データを分析して、適切な `dsbulk` パラメータ値と必要なテーブル設定を明確にします。
**データをランダム化する**
`dsbulk` コマンドは、CSV ファイルに表示される順序と同じ順序でデータの読み取りと書き込みを行います。`dsbulk` コマンドを使用してソースファイルを作成すると、データはキーソートされた順序で CSV に書き込まれます。内部的には、Amazon Keyspaces でパーティションキーを使用してデータが分割されます。Amazon Keyspaces には、同一のパーティションキーに対するロードバランスリクエストに役立つロジックが内蔵されていますが、順序をランダム化すると、データのロードが高速かつ効率的になります。これは、Amazon Keyspaces で異なるパーティションにデータが書き込まれたときに発生する組み込みのロードバランシングを利用できるためです。
パーティション間で書き込みを均等に分散させるには、ソースファイル内のデータをランダム化する必要があります。アプリケーションを書き込んでこれを実行することができます。また、[Shuf](https://en.wikipedia.org/wiki/Shuf) などのオープンソースツールを使用することもできます。Shuf は、Linux ディストリビューション、macOS (コアユーティリティを [homebrew](https://brew.sh) にインストールする)、Windows (Windows Subsystem for Linux (WSL) を使用する) で無料で使用できます。このステップで列名を含むヘッダー行がシャッフルされないようにするには、追加のステップが 1 つ必要です。
ヘッダーを維持した状態でソースファイルをランダム化するには、次のコードを入力します。
```
tail -n +2 keyspaces_sample_table.csv | shuf -o keyspace.table.csv && (head -1 keyspaces_sample_table.csv && cat keyspace.table.csv ) > keyspace.table.csv1 && mv keyspace.table.csv1 keyspace.table.csv
```
Shuf により、`keyspace.table.csv` という新しい CSV ファイルにデータが書き換えられます。これで、不要になった `keyspaces_sample_table.csv` ファイルを削除できます。
**データを分析する**
データを分析して、平均行サイズと最大行サイズを決定します。
この作業を行う理由は次のとおりです。
+ 転送されるデータの総量を見積もる場合に、平均行サイズが役立ちます。
+ データのアップロードに必要な書き込みキャパシティをプロビジョニングする際には、平均行サイズが必要になります。
+ 各行のサイズが 1 MB 未満 (Amazon Keyspaces の行サイズの上限) であることを確認できます。
**注記**
このクォータは、パーティションサイズではなく、行サイズを指します。Apache Cassandra のパーティションとは異なり、Amazon Keyspaces のパーティションのサイズは事実上無制限です。パーティションキーとクラスタリング列には、メタデータ用の追加のストレージが必要です。このストレージは行の raw サイズに追加する必要があります。詳細については、「[Amazon Keyspaces で行のサイズを推定する](calculating-row-size.md)」を参照してください。
次のコードは、[AWK](https://en.wikipedia.org/wiki/AWK) を使用して CSV ファイルを分析し、行の平均サイズと最大サイズを出力します。
```
awk -F, 'BEGIN {samp=10000;max=-1;}{if(NR>1){len=length($0);t+=len;avg=t/NR;max=(len>max ? len : max)}}NR==samp{exit}END{printf("{lines: %d, average: %d bytes, max: %d bytes}\n",NR,avg,max);}' keyspace.table.csv
```
このコードを実行すると、次の出力が表示されます。
```
using 10,000 samples:
{lines: 10000, avg: 123 bytes, max: 225 bytes}
```
最大行サイズが 1 MB を超えないようにしてください。超えた場合は、行を分割するか、データを圧縮して、行サイズを 1 MB 未満にする必要があります。このチュートリアルの次のステップでは、平均行サイズを使用して、テーブルの書き込みキャパシティをプロビジョニングします。
# ステップ 3: ターゲットテーブルのスループットキャパシティを設定する
このチュートリアルでは、設定された時間範囲内でデータがロードされるように DSBulk を調整する方法を示します。事前に実行する読み取りと書き込みの数がわかっているので、プロビジョンドキャパシティモードを使用します。データ転送が完了したら、アプリケーションのトラフィックパターンに合わせてテーブルのキャパシティモードを設定する必要があります。キャパシティ管理の詳細については、「[Amazon Keyspaces (Apache Cassandra 向け) でのサーバーレスリソースの管理](serverless_resource_management.md)」を参照してください。
プロビジョンドキャパシティモードでは、事前にテーブルにプロビジョニングする読み取りキャパシティと書き込みキャパシティの量を指定します。書き込みキャパシティは時間ユニットで課金され、書き込みキャパシティユニット (WCU) で計測されます。各 WCU は、1 秒あたり 1 KB のデータの書き込みをサポートするのに十分な書き込みキャパシティです。データをロードする際に、書き込みレートが、ターゲットテーブルで設定した WCU の上限 (パラメータ: `write_capacity_units`) を超えないようにしてください。
デフォルトでは、1 つのテーブルに最大 40,000 の WCU を、アカウント内のすべてのテーブルに最大 80,000 の WCU をプロビジョニングすることができます。追加のキャパシティが必要な場合は、[Service Quotas](https://console.aws.amazon.com/servicequotas/home#!/services/cassandra/quotas) コンソールでクォータの増加をリクエストできます。クォータの詳細については、「[Amazon Keyspaces (Apache Cassandra 向け) のクォータ](quotas.md)」を参照してください。
**挿入に必要な WCU の平均数を計算する**
1 秒あたり 1 KB のデータを挿入するには、1 WCU が必要です。CSV ファイルに 360,000 の行があり、1 時間ですべてのデータをロードする場合は、1 秒あたり 100 行 (360,000 行 / 60 分 / 60 秒 = 100 行/秒) を書き込む必要があります。各行に最大 1 KB のデータがある場合、1 秒あたり 100 行を挿入するには、100 WCU をテーブルにプロビジョニングする必要があります。各行に 1.5 KB のデータがある場合、1 秒あたり 1 行を挿入するには 2 WCU が必要です。したがって、1 秒あたり 100 行を挿入するには、200 WCU をプロビジョニングする必要があります。
1 秒あたり 1 行の挿入が必要な WCU 数を調べるには、平均行サイズ (バイト) を 1024 で割り、端数を切り上げて最も近い整数にします。
例えば、平均行サイズが 3000 バイトの場合、1 秒あたり 1 行を挿入するには 3 WCU が必要です。
```
ROUNDUP(3000 / 1024) = ROUNDUP(2.93) = 3 WCUs
```
**データのロード時間とキャパシティを計算する**
これで、CSV ファイルの平均サイズと平均行数が分かったので、特定の時間内にデータをロードする場合に必要な WCU 数と、さまざまな WCU 設定を使用して CSV ファイルにすべてのデータをロードするのにかかるおおよその時間を計算できます。
例えば、ファイルの各行が 1 KB で、CSV ファイルに 1,000,000 行がある場合、1 時間でデータをロードするには、その時間に少なくとも 278 WCU をテーブルにプロビジョニングする必要があります。
```
1,000,000 rows * 1 KBs = 1,000,000 KBs
1,000,000 KBs / 3600 seconds =277.8 KBs / second = 278 WCUs
```
**プロビジョンドキャパシティを設定する**
テーブルの書き込みキャパシティは、そのテーブルの作成時、または `ALTER TABLE` コマンドを使用して、設定することができます。以下は、`ALTER TABLE` コマンドを使用してテーブルのプロビジョンドキャパシティ設定に変更を加えるための構文です。
```
ALTER TABLE catalog.book_awards WITH custom_properties={'capacity_mode':{'throughput_mode': 'PROVISIONED', 'read_capacity_units': 100, 'write_capacity_units': 278}} ;
```
完全な言語リファレンスについては、「[CREATE TABLE](cql.ddl.table.md#cql.ddl.table.create)」と「[ALTER TABLE](cql.ddl.table.md#cql.ddl.table.alter)」を参照してください。
# ステップ 4: CSV ファイルからターゲットテーブルにデータをアップロードするように `DSBulk` を設定する
このセクションでは、データが Amazon Keyspaces にアップロードされるように DSBulk を設定する場合に必要なステップについて説明します。DSBulk を設定するには、設定ファイルを使用します。設定ファイルは、コマンドラインから直接指定します。
1. Amazon Keyspaces への移行用の DSBulk 設定ファイルを作成します。この例では、ファイル名 `dsbulk_keyspaces.conf` を使用します。DSBulk 設定ファイルで以下の設定を指定します。
1. *`PlainTextAuthProvider`* — `PlainTextAuthProvider` クラスを使用して認証プロバイダーを作成します。`ServiceUserName` と `ServicePassword` は、[Amazon Keyspaces にプログラムによってアクセスするための認証情報を作成する](programmatic.credentials.md) の手順に従ってサービス固有の認証情報を生成したときに取得したユーザー名とパスワードと一致している必要があります。
1. *`local-datacenter`* – の値を接続 AWS リージョン 先の `local-datacenter`に設定します。例えば、アプリケーションを `cassandra.us-east-1.amazonaws.com` に接続する場合は、ローカルデータセンターを `us-east-1` に設定します。使用可能なすべての については AWS リージョン、「」を参照してください[Amazon Keyspaces のサービスエンドポイント](programmatic.endpoints.md)。レプリカを避けるには、`slow-replica-avoidance` を `false` に設定します。
1. *`SSLEngineFactory`* — SSL/TLS を設定するには、`class = DefaultSslEngineFactory` を使用してクラスを指定する設定ファイル (1 行が含まれている) に、セクションを追加して、`SSLEngineFactory` を初期化します。`cassandra_truststore.jks` へのパスと、作成しておいたパスワードを提供します。
1. *`consistency`* — 整合性レベルを `LOCAL QUORUM` に設定します。他の書き込み整合性レベルはサポートされません。詳細については「[Apache Cassandra でサポートされている読み取り/書き込み整合性レベルと関連コスト](consistency.md)」を参照してください。
1. プールごとの接続数は Java ドライバーで設定できます。この例では、`advanced.connection.pool.local.size` を 3 に設定します。
次に、完全なサンプル設定ファイルを示します。
```
datastax-java-driver {
basic.contact-points = [ "cassandra.us-east-1.amazonaws.com:9142"]
advanced.auth-provider {
class = PlainTextAuthProvider
username = "ServiceUserName"
password = "ServicePassword"
}
basic.load-balancing-policy {
local-datacenter = "us-east-1"
slow-replica-avoidance = false
}
basic.request {
consistency = LOCAL_QUORUM
default-idempotence = true
}
advanced.ssl-engine-factory {
class = DefaultSslEngineFactory
truststore-path = "./cassandra_truststore.jks"
truststore-password = "my_password"
hostname-validation = false
}
advanced.connection.pool.local.size = 3
}
```
1. DSBulk `load` コマンドのパラメータを確認します。
1. *`executor.maxPerSecond`* — ロードコマンドにより処理が試行される 1 秒あたりの最大行数。設定しない場合、この設定は -1 となり無効になります。
ターゲット送信先テーブルにプロビジョニングした WCU の数に基づいて `executor.maxPerSecond` を設定します。`load` コマンドの `executor.maxPerSecond` は制限ではなくターゲット平均です。これは、設定した数を大きく上回る可能性がある (多くの場合そうなる) ことを意味します。このような超過を許可し、データロードリクエストを処理できるだけの十分なキャパシティを確保するには、`executor.maxPerSecond` をテーブルの書き込みキャパシティの 90% に設定します。
```
executor.maxPerSecond = WCUs * .90
```
このチュートリアルでは、`executor.maxPerSecond` を 5 に設定します。
**注記**
DSBulk 1.6.0 以上を使用している場合は、代わりに `dsbulk.engine.maxConcurrentQueries` を使用できます。
1. DSBulk `load` コマンドのためにこれらの追加パラメータを設定します。
+ *`batch-mode`* — このパラメータは、パーティションキー別にオペレーションをグループ化するようにシステムに指示を出します。バッチモードは無効にすることを推奨します。バッチモードは、ホットキーシナリオを引き起こし、`WriteThrottleEvents` の原因となる可能性があるためです。
+ *`driver.advanced.retry-policy-max-retries`* — これにより、失敗したクエリが再試行される回数が決まります。設定しない場合のデフォルトは 10 になります。この値は必要に応じて調整できます。
+ *`driver.basic.request.timeout`* — クエリが返されるまでのシステムの待機時間 (分)。設定しない場合のデフォルトは「5 分」です。この値は必要に応じて調整できます。
# ステップ 5: DSBulk `load` コマンドを実行して CSV ファイルからターゲットテーブルにデータをアップロードする
このチュートリアルの最後のステップでは、データを Amazon Keyspaces にアップロードします。
DSBulk `load` コマンドを使用して、以下のステップを実行します。
1. 次のコードを実行して、CSV ファイルから Amazon Keyspaces テーブルにデータをアップロードします。前の手順で作成したアプリケーション設定ファイルへのパスを必ず更新してください。
```
dsbulk load -f ./dsbulk_keyspaces.conf --connector.csv.url keyspace.table.csv -header true --batch.mode DISABLED --executor.maxPerSecond 5 --driver.basic.request.timeout "5 minutes" --driver.advanced.retry-policy.max-retries 10 -k catalog -t book_awards
```
1. 出力には、成功したオペレーションと失敗したオペレーションの詳細が記されているログファイルの場所が含まれます。このファイルは次のディレクトリに保存されています。
```
Operation directory: /home/user_name/logs/UNLOAD_20210308-202317-801911
```
1. ログファイルのエントリには、次の例のように、メトリックが含まれます。行数が csv ファイルの行数と一致しているか確認します。
```
total | failed | rows/s | p50ms | p99ms | p999ms
200 | 0 | 200 | 21.63 | 21.89 | 21.89
```
**重要**
データを転送したので、アプリケーションの通常のトラフィックパターンに合わせてターゲットテーブルのキャパシティモード設定を調整します。プロビジョンドキャパシティは、変更するまでは、時間ユニットで課金されます。詳細については、「[Amazon Keyspaces で読み取り/書き込みのキャパシティモードを設定する](ReadWriteCapacityMode.md)」を参照してください。