本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 如何选择合适的工具将数据批量上传或迁移到 Amazon Keyspaces
<a name="migrating-tools"></a>

在本节中，您可以查看可用于将数据批量上传或迁移到 Amazon Keyspaces 的各种工具，并了解如何根据需要选择合适的工具。此外，本节还概述了演示如何将数据导入 Amazon Keyspaces 的可用 step-by-step教程和使用案例。

要查看将工作负载从 Apache Cassandra 迁移到 Amazon Keyspaces 的可用策略，请参阅[创建从 Apache Cassandra 迁移到 Amazon Keyspaces 的迁移计划](migrating-cassandra.md)。
+ **迁移工具**
  + 借助 Github 上提供的[亚马逊密钥空间（适用于 Apache Cassandra）的定价计算器](https://aws-samples.github.io/sample-pricing-calculator-for-keyspaces/#cassandra)，您可以根据现有的 Apache Cassandra 工作负载估算亚马逊密钥空间的每月费用。输入您的 Cassandra 节点工具状态输出和 Amazon Keyspaces 的预期无服务器配置中的指标，以比较两种解决方案之间的直接成本。请注意，此计算器仅关注与您的现有 Cassandra 部署相比 Amazon Keyspaces 的运营成本。它不包括总拥有成本 (TCO) 因素，例如基础架构维护、运营开销或Cassandra的支持成本。
  + **用于亚马逊密钥空间迁移的 ZDM 双写代理** — Github [上](https://github.com/aws-samples/amazon-keyspaces-examples/blob/main/migration/online/zdm-proxy/README.md)提供的 ZDM 双写代理支持从 Apache Cassandra 到亚马逊密钥空间的零停机迁移。
  + **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 中，最适用于加载小型数据集或测试数据。有关 step-by-step说明，请参阅[教程：使用 cqlsh 将数据加载到 Amazon Keyspaces](bulk-upload.md)。
  + 您也可以使用适用于 Apache Cassandra 的 DataStax 批量加载器使用命令将数据加载到 Amazon Keyspaces 中。`dsbulk` DSBulk[提供了比 cqlsh 更强大的导入功能，并且可从存储库中获取。GitHub ](https://github.com/datastax/dsbulk)有关 step-by-step说明，请参阅[教程：使用将数据加载到 Amazon Keyspaces DSBulk](dsbulk-upload.md)。

将数据上传到 Amazon Keyspaces 的一般注意事项
+ **将数据上传分解为较小的组成部分。**

  考虑以下迁移单位及其在原始数据大小方面的潜在占用空间。在一个或多个阶段上传少量数据可能有助于简化迁移。
  + **按集群**：一次性迁移所有 Cassandra 数据。这种方法可能适用于较小的集群。
  + **按键空间或表**：将迁移分解为键空间或表组。此方法可以帮助您根据每个工作负载的要求分阶段迁移数据。
  + **按数据**：考虑迁移特定用户组或产品的数据，进一步减少数据大小。
+ **根据简便性，首选确定要上传的数据的优先顺序。**

  考虑一下您是否有可以首先且更轻松地迁移的数据，例如，在特定时间段内不会更改的数据、来自夜间批处理作业的数据、离线期间未使用的数据或来自内部应用程序的数据。

**Topics**
+ [教程：使用 cqlsh 将数据加载到 Amazon Keyspaces](bulk-upload.md)
+ [教程：使用将数据加载到 Amazon Keyspaces DSBulk](dsbulk-upload.md)

# 教程：使用 cqlsh 将数据加载到 Amazon Keyspaces
<a name="bulk-upload"></a>

本教程将指导您完成使用 `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 参数** - 确定诸如 `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` 上传数据之前需要完成的步骤
<a name="bulk-upload-prequs"></a>

在开始本教程之前，您必须完成以下任务：

1. 如果您还没有这样做，请 AWS 账户 按照中的步骤进行注册[设置 AWS Identity and Access Management](accessing.md#SettingUp.IAM)。

1. 按照[创建用于通过编程方式访问 Amazon Keyspaces 的服务特定凭证。](programmatic.credentials.ssc.md)中的步骤创建特定于服务的凭证。

1. 设置 Cassandra 查询语言 Shell (cqlsh) 连接，并按照[使用 `cqlsh` 连接 Amazon Keyspaces](programmatic.cqlsh.md) 中的步骤确认您可以连接到 Amazon Keyspaces。

# 第 1 步：为数据上传创建源 CSV 文件和目标表
<a name="bulk-upload-source"></a>

在本教程中，我们使用名为 `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 步：为成功上传数据做好源数据准备
<a name="bulk-upload-prepare-data"></a>

为高效传输准备源数据的过程包含两个步骤。第一步，随机化数据。第二步，分析数据以确定相应的 `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 [通过使用 Windows Subsystem for Linux (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 将数据重写到名为 `keyspace.table.csv` 的新 CSV 文件中。现在，您可以删除 `keyspaces_sample_table.csv` 文件，您不再需要此文件了。

**分析数据**  
通过分析数据来确定平均行大小和最大行大小。

执行此操作出于以下原因：
+ 平均行大小有助于估算要传输的数据总量。
+ 您需要平均行大小来预置上传数据所需的写入容量。
+ 您可以确保每行的大小小于 1MB，这是 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：为表设置吞吐容量
<a name="bulk-upload-capacity"></a>

本教程向您展示了如何调整 cqlsh 以在设定的时间范围内加载数据。由于您提前知道自己要执行多少读取和写入操作，因此可以使用预置容量模式。完成数据传输后，应该将表的容量模式设置为与应用程序的流量模式相匹配。要了解有关容量管理的更多信息，请参阅 [在 Amazon Keyspaces（Apache Cassandra 兼容）中管理无服务器资源](serverless_resource_management.md)。

使用预置容量模式，您可以提前指定要为表预置多少读取和写入容量。写入容量按小时计费，并以写入容量单位 () WCUs 计量。每个 WCU 的写入容量足以支持每秒写入 1KB 数据。加载数据时，写入速率必须低于目标表上设置的最大值 WCUs（参数:`write_capacity_units`）。

默认情况下，您最多可以为一个表预配置 40,000， WCUs 为账户中的 WCUs 所有表配置最多 80,000。如果您需要更多容量，可以在[服务限额](https://console.aws.amazon.com/servicequotas/home#!/services/cassandra/quotas)控制台中请求提高限额。有关限额的更多信息，请参阅[Amazon Keyspaces（Apache Cassandra 兼容）限额](quotas.md)。

**计算刀片 WCUs 所需的平均数量**  
每秒插入 1KB 数据需要 1 个 WCU。如果您的 CSV 文件有 360000 行，并且您想在 1 小时内加载所有数据，则必须每秒写入 100 行（360000 行/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` 设置
<a name="bulk-upload-config"></a>

本部分概述如何确定 `cqlsh COPY FROM` 的参数值。`cqlsh COPY FROM` 命令读取您之前准备的 CSV 文件，并使用 CQL 将数据插入到 Amazon Keyspaces 中。该命令将行分开，并将 `INSERT` 操作分配给一组 Worker。每个 Worker 与 Amazon Keyspaces 建立连接并通过该通道发送 `INSERT` 请求。

`cqlsh COPY` 命令没有在 Worker 之间均匀分配工作的内部逻辑。但是，您可以手动对其进行配置，以确保均匀分配工作。首先查看以下关键的 cqlsh 参数：
+ **DELIMITER**：如果您使用逗号以外的分隔符，则可以设置此参数，此参数默认为逗号。
+ **INGESTRATE**：`cqlsh COPY FROM` 每秒尝试处理的目标行数。如果未设置，则默认为 100000。
+ **NUMPROCESSES**：cqlsh 为 `COPY FROM` 任务创建的子 Worker 进程的数量。此设置的最大值为 16，默认值为 `num_cores - 1`，其中 `num_cores` 是运行 cqlsh 的主机上的处理内核数。
+ **MAXBATCHSIZE**：批次大小决定了在单个批次中插入到目标表中的最大行数。如果未设置，cqlsh 将使用插入 20 行的批次。
+ **CHUNKSIZE**：传递给子 Worker 的工作单元的大小。默认情况下，它设置为 5000。
+ **MAXATTEMPTS**：重试失败 Worker 块的最大次数。达到最大尝试次数后，失败记录将写入一个新的 CSV 文件中，您可以在调查失败后再次运行该文件。

`INGESTRATE`根据您配置到目标目标表 WCUs 的数量进行设置。`cqlsh COPY FROM` 命令的 `INGESTRATE` 不是限制，而是目标平均值。这意味着它可以（并且经常）突破您设定的数字。要允许暴增并确保有足够的容量来处理数据加载请求，请将 `INGESTRATE` 设置为表写入容量的 90%。

```
INGESTRATE = WCUs * .90
```

接下来，将 `NUMPROCESSES` 参数设置为比系统上的内核数少一个。要弄清楚系统的内核数，您可以运行以下代码。

```
python -c "import multiprocessing; print(multiprocessing.cpu_count())"
```

在本教程中，我们使用以下值。

```
NUMPROCESSES = 4
```

每个进程都会创建一个 Worker，并且每个 Worker 都会与 Amazon Keyspaces 建立连接。Amazon Keyspaces 在每个连接上每秒可支持最多 3000 个 CQL 请求。这意味着您必须确保每个 Worker 每秒处理的请求少于 3000 个。

与 `INGESTRATE` 一样，Worker 经常会突破您设置的数字，并且不受时钟秒数的限制。因此，考虑到暴增，请将 cqlsh 参数设置为每个 Worker 每秒处理 2500 个请求。要计算分配给 Worker 的工作量，请使用以下准则。
+ `INGESTRATE` 除以 `NUMPROCESSES`。
+ 如果 `INGESTRATE`/`NUMPROCESSES` > 2500，请降低 `INGESTRATE` 以使此公式成立。

```
INGESTRATE / NUMPROCESSES <= 2,500
```

在配置设置以优化示例数据的上传之前，让我们回顾一下 `cqlsh` 默认设置，看看使用它们会如何影响数据上传过程。由于 `cqlsh COPY FROM` 使用 `CHUNKSIZE` 创建工作块（`INSERT` 语句）以分配给 Worker，因此工作不会自动均匀分配。根据 `INGESTRATE` 设置，有些 Worker 可能会处于闲置状态。

要在 Worker 之间均匀分配工作并使每个 Worker 保持每秒 2500 个请求的最佳速率，必须通过更改输入参数来设置 `CHUNKSIZE`、`MAXBATCHSIZE`、和 `INGESTRATE`。要优化数据加载期间的网络流量利用率，请为 `MAXBATCHSIZE` 选择一个接近最大值 30 的值。通过将 `CHUNKSIZE` 更改为 100，将 `MAXBATCHSIZE` 更改为 25，10000 行将均匀分配给四个 Worker（10000/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** = 写入容量单位 \$1 0.90
+ **NUMPROCESSES** = 内核数 - 1（默认设置）
+ **INGESTRATE/NUMPROCESSES** = 2500（这必须是一个真语句。）
+ **MAXBATCHSIZE** = 30（默认为 20。Amazon Keyspaces 最多可接受 30 个批次。）
+ **CHUNKSIZE** = (INGESTRATE/NUMPROCESSES)/MAXBATCHSIZE

现在您已经计算了 `NUMPROCESSES`、`INGESTRATE` 和 `CHUNKSIZE`，接下来可以加载数据。

# 第 5 步：运行 `cqlsh COPY FROM` 命令将 CSV 文件中的数据上传到目标表
<a name="bulk-upload-run"></a>

要运行 `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。

**重要**  
现在您已经传输了数据，接下来调整目标表的容量模式设置，使其与应用程序的常规流量模式相匹配。在更改之前，您的预置容量按小时费率收费。

# 问题排查
<a name="bulk-upload-troubleshooting"></a>

数据上传完成后，检查是否跳过了行。为此，请导航到源 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 请使用迁移数据。有关更多信息，请参阅 [教程：使用将数据加载到 Amazon Keyspaces DSBulk](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 在亚马逊上发布了`WriteThrottleEvents``ReadThrottledEvents`指标。 CloudWatch有关更多信息，请参阅 [使用亚马逊监控亚马逊密钥空间 CloudWatch](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 语句来使用单行数据，从而隔离错误。

客户端会自动尝试重新建立连接。

# 教程：使用将数据加载到 Amazon Keyspaces DSBulk
<a name="dsbulk-upload"></a>

本 step-by-step教程将指导您使用上提供的 DataStax 批量加载器 () DSBulk 将数据从 Apache Cassandra 迁移到 Amazon Keyspaces。[GitHub](https://github.com/datastax/dsbulk.git)用于 DSBulk 将数据集上传到 Amazon Keyspaces 用于学术或考试目的非常有用。有关如何迁移生产工作负载的更多信息，请参阅[离线迁移过程：Apache Cassandra 到 Amazon Keyspaces](migrating-offline.md)。在本教程中，您将完成以下步骤。

先决条件-使用凭据设置 AWS 帐户，为证书创建 JKS 信任存储文件，配置`cqlsh`、下载和安装 DSBulk以及配置`application.conf`文件。

1. **创建源 CSV 和目标表** - 准备一个 CSV 文件作为源数据，然后在 Amazon Keyspaces 中创建目标键空间和表。

1. **准备数据** - 随机采样 CSV 文件中的数据，并对其进行分析，以确定平均行大小和最大行大小。

1. **设置吞吐容量**-根据数据大小和所需的加载时间计算所需的写入容量单位 (WCUs)，并配置表的预配置容量。

1. **配置 DSBulk 设置**-使用身份验证、SSL/TLS、一致性级别和连接池大小等设置创建 DSBulk 配置文件。

1. **运行 DSBulk 加载命令 — 运行加载命令**将数据从 CSV 文件上传到 Amazon Keyspaces 表，并监控进度。 DSBulk 

**Topics**
+ [先决条件：在上传数据之前必须完成的步骤 DSBulk](dsbulk-upload-prequs.md)
+ [步骤 1：使用创建源 CSV 文件和用于上传数据的目标表 DSBulk](dsbulk-upload-source.md)
+ [第 2 步：使用准备要上传的数据 DSBulk](dsbulk-upload-prepare-data.md)
+ [第 3 步：为目标表设置吞吐能力](dsbulk-upload-capacity.md)
+ [第 4 步：配置 `DSBulk` 设置，以将 CSV 文件中的数据上传到目标表](dsbulk-upload-config.md)
+ [第 5 步：运行 DSBulk `load` 命令将 CSV 文件中的数据上传到目标表](dsbulk-upload-run.md)

# 先决条件：在上传数据之前必须完成的步骤 DSBulk
<a name="dsbulk-upload-prequs"></a>

在开始本教程之前，您必须完成以下任务：

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 Class 2 Root（可选 — 为了向后兼容）

      要下载证书，您可以使用以下命令。

      ```
      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 正在将所有证书全部迁移 AWS 区域 到根据亚马逊信任服务（Amazon Root CAs 1—4）颁发的证书。在此过渡期间，将客户端配置为同时信任 Amazon Root 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 查询语言 Shell (cqlsh) 连接，并按照[使用 `cqlsh` 连接 Amazon Keyspaces](programmatic.cqlsh.md) 中的步骤确认您可以连接到 Amazon Keyspaces。

1. 下载并安装 DSBulk。
**注意**  
本教程中显示的版本可能不是可用的最新版本。下载之前 DSBulk，请查看 B [DataStax ulk 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. 创建一个`application.conf`文件来存储要使用的设置 DSBulk。您可以将以下示例保存为 `./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 支持，请从下载阴影`jar`文件[GitHub](https://github.com/aws/aws-sigv4-auth-cassandra-java-driver-plugin/releases/)并将其放在 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：使用创建源 CSV 文件和用于上传数据的目标表 DSBulk
<a name="dsbulk-upload-source"></a>

在本教程中，我们使用名为 `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
<a name="dsbulk-upload-prepare-data"></a>

为高效传输准备源数据的过程包含两个步骤。第一步，随机化数据。第二步，分析数据以确定相应的 `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) 中安装 coreutils）和 Windows [通过使用 Windows Subsystem for Linux (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 将数据重写到名为 `keyspace.table.csv` 的新 CSV 文件中。现在，您可以删除 `keyspaces_sample_table.csv` 文件，您不再需要此文件了。

**分析数据**  
通过分析数据来确定平均行大小和最大行大小。

执行此操作出于以下原因：
+ 平均行大小有助于估算要传输的数据总量。
+ 您需要平均行大小来预置上传数据所需的写入容量。
+ 您可以确保每行的大小小于 1MB，这是 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}
```

确保最大行大小不超过 1MB。否则，必须拆分行或压缩数据，使行大小小于 1MB。在本教程的下一步中，您将使用平均行大小来预置表的写入容量。

# 第 3 步：为目标表设置吞吐能力
<a name="dsbulk-upload-capacity"></a>

本教程向您展示如何调整 DSBulk 以在设定的时间范围内加载数据。由于您提前知道自己要执行多少读取和写入操作，因此可以使用预置容量模式。完成数据传输后，应该将表的容量模式设置为与应用程序的流量模式相匹配。要了解有关容量管理的更多信息，请参阅 [在 Amazon Keyspaces（Apache Cassandra 兼容）中管理无服务器资源](serverless_resource_management.md)。

使用预置容量模式，您可以提前指定要为表预置多少读取和写入容量。写入容量按小时计费，并以写入容量单位 () WCUs 计量。每个 WCU 的写入容量足以支持每秒写入 1KB 数据。加载数据时，写入速率必须低于目标表上设置的最大值 WCUs（参数:`write_capacity_units`）。

默认情况下，您最多可以为一个表预配置 40,000， WCUs 为账户中的 WCUs 所有表配置最多 80,000。如果您需要更多容量，可以在[服务限额](https://console.aws.amazon.com/servicequotas/home#!/services/cassandra/quotas)控制台中请求提高限额。有关限额的更多信息，请参阅[Amazon Keyspaces（Apache Cassandra 兼容）限额](quotas.md)。

**计算刀片 WCUs 所需的平均数量**  
每秒插入 1KB 数据需要 1 个 WCU。如果您的 CSV 文件有 360000 行，并且您想在 1 小时内加载所有数据，则必须每秒写入 100 行（360000 行/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` 命令来设置表的写入容量设置。以下是使用 `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 步：配置 `DSBulk` 设置，以将 CSV 文件中的数据上传到目标表
<a name="dsbulk-upload-config"></a>

本节概述了配置 DSBulk 将数据上传到 Amazon Keyspaces 所需的步骤。您可以使用配置文件 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，初始化 `SSLEngineFactory`，方法是在配置文件中添加一个部分，其中只有一行，用于指定类 `class = DefaultSslEngineFactory`。提供指向 `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`*：load 命令尝试每秒同时处理的最大行数。如果未设置，则使用 -1 禁用此设置。

      `executor.maxPerSecond`根据您配置到目标目标表 WCUs 的数量进行设置。`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 文件中的数据上传到目标表
<a name="dsbulk-upload-run"></a>

在本教程的最后一步中，您要将数据上传到 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 中配置 read/write 容量模式](ReadWriteCapacityMode.md)。