本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 教學課程：使用 cqlsh 將資料載入 Amazon Keyspaces
本教學課程將引導您使用 `cqlsh COPY FROM`命令，將資料從 Apache Cassandra 遷移至 Amazon Keyspaces。`cqlsh COPY FROM` 命令有助於快速且輕鬆地將小型資料集上傳至 Amazon Keyspaces，以供學術或測試之用。如需如何遷移生產工作負載的詳細資訊，請參閱 [離線遷移程序：Apache Cassandra 到 Amazon Keyspaces](migrating-offline.md)。在本教學課程中，您將完成下列步驟：
先決條件 – 設定具有登入資料的 AWS 帳戶、建立憑證的 JKS 信任存放區檔案，以及設定 `cqlsh` 以連線至 Amazon Keyspaces。
1. **建立來源 CSV 和目標資料表** – 準備 CSV 檔案做為來源資料，並在 Amazon Keyspaces 中建立目標金鑰空間和資料表。
1. **準備資料** – 隨機化 CSV 檔案中的資料並加以分析，以判斷平均和最大資料列大小。
1. **設定輸送量容量** – 根據資料大小和所需的載入時間計算所需的寫入容量單位 (WCUs)，並設定資料表的佈建容量。
1. **設定 cqlsh 參數** – 決定`cqlsh COPY FROM`參數的最佳值`NUMPROCESSES`，例如 `INGESTRATE`、`MAXBATCHSIZE`、 和 `CHUNKSIZE`，以平均分配工作負載。
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 Query Language Shell (cqlsh) 連線，並依照 中的步驟確認您可以連線至 Amazon Keyspaces[使用 `cqlsh` 連線至 Amazon Keyspaces](programmatic.cqlsh.md)。
# 步驟 1：建立來源 CSV 檔案和目標資料表以進行資料上傳
在本教學課程中，我們使用逗號分隔值 (CSV) 檔案，其名稱`keyspaces_sample_table.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. 使用 連線至 Amazon Keyspaces`cqlsh`，將下列範例中的服務端點、使用者名稱和密碼取代為您自己的值。
```
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;"
```
然後，使用與 Cassandra 來源資料表描述相符的資料欄名稱和資料類型，在 Amazon Keyspaces 中建立目標資料表。
# 步驟 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) 中安裝 coreutils) 和 Windows （透過使用適用於 Linux 的 Windows 子系統 (WSL)) 上免費使用。需要額外的步驟，以防止具有資料欄名稱的標頭列在此步驟中隨機播放。
若要在保留 標頭時隨機化來源檔案，請輸入下列程式碼。
```
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 會將資料重寫至名為 的新 CSV 檔案`keyspace.table.csv`。您現在可以刪除`keyspaces_sample_table.csv`檔案 - 您不再需要它。
**分析資料**
透過分析資料來判斷平均和最大資料列大小。
您這樣做的原因如下：
+ 平均資料列大小有助於預估要傳輸的資料總量。
+ 您需要平均資料列大小來佈建資料上傳所需的寫入容量。
+ 您可以確保每個資料列的大小小於 1 MB，這是 Amazon Keyspaces 中的資料列大小上限。
**注意**
此配額是指資料列大小，而非分割區大小。與 Apache Cassandra 分割區不同，Amazon Keyspaces 分割區的大小幾乎沒有限制。分割區索引鍵和叢集資料欄需要額外的中繼資料儲存空間，您必須將其新增至資料列的原始大小。如需詳細資訊，請參閱[估計 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)。
使用佈建容量模式時，您可以指定要預先佈建至資料表的讀取和寫入容量。寫入容量會以每小時計費，並以寫入容量單位 (WCUs計量。每個 WCU 都有足夠的寫入容量，可支援每秒寫入 1 KB 的資料。當您載入資料時，寫入速率必須低於目標資料表上設定的最大 WCUs（參數：`write_capacity_units`)。
根據預設，您最多可以將 40，000 WCUs 佈建到 資料表，並在您帳戶中所有資料表中佈建 80，000 WCUs。如果您需要額外的容量，您可以在 [ Service Quotas](https://console.aws.amazon.com/servicequotas/home#!/services/cassandra/quotas) 主控台中請求增加配額。如需配額的詳細資訊，請參閱 [Amazon Keyspaces 配額 （適用於 Apache Cassandra)](quotas.md)。
**計算插入所需的 WCUs平均數量**
每秒插入 1 KB 的資料需要 1 個 WCU。如果您的 CSV 檔案有 360，000 個資料列，而且您想要在 1 小時內載入所有資料，則必須每秒寫入 100 個資料列 (360，000 個資料列/60 分鐘/60 秒 = 每秒 100 個資料列）。如果每一列最多有 1 KB 的資料，若要每秒插入 100 列，您必須將 100 WCUs 佈建到您的資料表。如果每個資料列有 1.5 KB 的資料，您需要兩個 WCUs才能每秒插入一個資料列。因此，若要每秒插入 100 個資料列，您必須佈建 200 WCUs。
若要判斷每秒需要插入一列的 WCUs 數量，請將平均資料列大小以位元組為單位除以 1024，然後四捨五入至最接近的整數。
例如，如果平均資料列大小為 3000 位元組，您需要三個 WCUs才能每秒插入一個資料列。
```
ROUNDUP(3000 / 1024) = ROUNDUP(2.93) = 3 WCUs
```
**計算資料載入時間和容量**
現在您已知道 CSV 檔案中的平均大小和資料列數，您可以計算在指定時間內載入資料所需的 WCUs 數量，以及使用不同的 WCU 設定載入 CSV 檔案中所有資料所需的大約時間。
例如，如果檔案中的每一列都是 1 KB，而 CSV 檔案中有 1，000，000 列，若要在 1 小時內載入資料，您需要在該小時內佈建至少 278 個 WCUs 到您的資料表。
```
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** – 如果您使用逗號以外的分隔符號，您可以設定此參數，預設為逗號。
+ **輸入** – `cqlsh COPY FROM`每秒嘗試處理的列數目標。如果取消設定，則預設為 100，000。
+ **NUMPROCESSES** – cqlsh 為`COPY FROM`任務建立的子工作者程序數目。此設定的最大值為 16，預設值為 `num_cores - 1`，其中 `num_cores`是執行 cqlsh 之主機上的處理核心數目。
+ **MAXBATCHSIZE** – 批次大小決定單一批次中插入目的地資料表的資料列數目上限。如果取消設定，cqlsh 會使用 20 個插入資料列的批次。
+ **CHUNKSIZE** – 傳遞給子工作者的工作單位大小。根據預設，它會設定為 5，000。
+ **MAXATTEMPTS** – 重試失敗工作者區塊的次數上限。達到嘗試次數上限後，失敗的記錄會寫入新的 CSV 檔案，您可以在調查失敗之後再次執行。
`INGESTRATE` 根據您佈建至目標目的地資料表的 WCUs 數目來設定 。`cqlsh COPY FROM` 命令`INGESTRATE`的 不是限制，而是目標平均值。這表示它可以 （且通常可以） 爆量超過您設定的數字。若要允許爆量，並確保有足夠的容量來處理資料載入請求，請將 `INGESTRATE` 設為資料表寫入容量的 90%。
```
INGESTRATE = WCUs * .90
```
接著，將 `NUMPROCESSES` 參數設定為比系統上的核心數目少一個。若要了解系統的核心數量，您可以執行下列程式碼。
```
python -c "import multiprocessing; print(multiprocessing.cpu_count())"
```
在本教學課程中，我們使用下列值。
```
NUMPROCESSES = 4
```
每個程序都會建立工作者，而且每個工作者都會建立與 Amazon Keyspaces 的連線。Amazon Keyspaces 在每個連線上每秒最多可支援 3，000 個 CQL 請求。這表示您必須確保每個工作者每秒處理少於 3，000 個請求。
如同 `INGESTRATE`，工作者通常會爆量超過您設定的數字，不受時鐘秒的限制。因此，若要考慮爆量，請將 cqlsh 參數設定為以每個工作者為目標，每秒處理 2，500 個請求。若要計算分配給工作者的工作量，請使用下列準則。
+ `INGESTRATE` 除以 `NUMPROCESSES`。
+ 如果 `INGESTRATE` / `NUMPROCESSES` > 2，500，請降低 `INGESTRATE`使此公式成為 true。
```
INGESTRATE / NUMPROCESSES <= 2,500
```
在您設定設定以最佳化上傳我們的範例資料之前，讓我們檢閱`cqlsh`預設設定，並了解使用它們如何影響資料上傳程序。由於 `cqlsh COPY FROM`使用 `CHUNKSIZE`來建立工作區塊 (`INSERT` 陳述式） 以分發給工作者，因此工作不會自動平均分發。有些工作者可能會閒置，視 `INGESTRATE` 設定而定。
若要在工作者之間平均分配工作，並將每個工作者保持在最佳每秒 2，500 個請求速率，您必須變更輸入參數`INGESTRATE`來設定 `MAXBATCHSIZE`、 `CHUNKSIZE`和 。若要在資料載入期間最佳化網路流量使用率，請選擇`MAXBATCHSIZE`接近最大值 30 的值。透過將 `CHUNKSIZE`變更為 100 和 `MAXBATCHSIZE` 25，10，000 個資料列平均分散在四個工作者之間 (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 （預設）
+ **擷取/NUMPROCESSES** = 2，500 （這必須是 true 陳述式。)
+ **MAXBATCHSIZE** = 30 （預設為 20。 Amazon Keyspaces 接受最多 30 個批次。)
+ **區塊大小** = （擷取 / 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 時發生無效的請求錯誤**
在下列範例中，來源資料表包含計數器資料欄，從 cqlsh `COPY`命令產生記錄的批次呼叫。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`陳述式嘗試使用單一資料列來隔離錯誤。
**將資料上傳至 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 用戶端從伺服器收到任何類型的連續三次錯誤後，與 Amazon Keyspaces 的連線會失敗。cqlsh 用戶端失敗，並顯示下列訊息。
```
Failed to import 1 rows: NoHostAvailable - , will retry later, attempt 3 of 100
```
若要解決此錯誤，您需要確定要匯入的資料符合 Amazon Keyspaces 中的資料表結構描述。檢閱匯入檔案是否有剖析錯誤。您可以使用 INSERT 陳述式來隔離錯誤，嘗試使用單一資料列。
用戶端會自動嘗試重新建立連線。