从云存储将 CSV 文件导入到 TiDB Cloud Premium

本文档介绍如何将 Amazon Simple Storage Service (Amazon S3) 或 Alibaba Cloud Object Storage Service (OSS) 中的 CSV 文件导入到 TiDB Cloud Premium 实例。

提示：

• 对于 TiDB Cloud Starter 或 Essential，请参见 从云存储将 CSV 文件导入到 TiDB Cloud Starter 或 Essential。
• 对于 TiDB Cloud Dedicated，请参见 从云存储将 CSV 文件导入到 TiDB Cloud Dedicated。

限制

为确保数据一致性，TiDB Cloud Premium 仅允许将 CSV 文件导入到空表中。若要将数据导入到已包含数据的现有表中，你可以按照本文档先将数据导入到一个临时空表中，然后使用 INSERT SELECT 语句将数据复制到目标现有表。

步骤 1. 准备 CSV 文件

1. 如果某个 CSV 文件大于 256 MiB，建议将其拆分为多个较小的文件，每个文件大小约为 256 MiB。

   TiDB Cloud Premium 支持导入非常大的 CSV 文件，但在使用多个大小约为 256 MiB 的输入文件时性能最佳。这是因为 TiDB Cloud Premium 可以并行处理多个文件，从而显著提升导入速度。

2. 按如下方式命名 CSV 文件：

   • 如果一个 CSV 文件包含整张表的全部数据，请将文件命名为 ${db_name}.${table_name}.csv 格式。导入数据时，该文件会映射到 ${db_name}.${table_name} 表。
   • 如果一张表的数据被拆分到多个 CSV 文件中，请为这些 CSV 文件追加数字后缀。例如，${db_name}.${table_name}.000001.csv 和 ${db_name}.${table_name}.000002.csv。数字后缀可以不连续，但必须按升序排列。你还需要在数字前补零，以确保所有后缀长度一致。
   • TiDB Cloud Premium 支持导入以下格式的压缩文件：.gzip、.gz、.zstd、.zst 和 .snappy。如果你想导入压缩的 CSV 文件，请将文件命名为 ${db_name}.${table_name}.${suffix}.csv.${compress} 格式，其中 ${suffix} 是可选的，可以是任意整数，例如 '000001'。例如，如果你想将 trips.000001.csv.gz 文件导入到 bikeshare.trips 表中，则需要将该文件重命名为 bikeshare.trips.000001.csv.gz。
   注意

   • 为获得更好的性能，建议将每个压缩文件的大小限制在 100 MiB 以内。
   • Snappy 压缩文件必须采用官方 Snappy 格式。不支持其他变体的 Snappy 压缩格式。
   • 对于未压缩文件，如果在某些情况下你无法按照上述规则更新 CSV 文件名（例如，这些 CSV 文件链接也被你的其他程序使用），你可以保持文件名不变，并在步骤 4 中使用 Mapping Settings 将源数据导入到单个目标表。

步骤 2. 创建目标表结构

由于 CSV 文件不包含 schema 信息，因此在将 CSV 文件中的数据导入到 TiDB Cloud Premium 之前，你需要使用以下任一方法创建表结构：

• 方法 1：在 TiDB Cloud Premium 中，为你的源数据创建目标数据库和表。

• 方法 2：在存放 CSV 文件的 Amazon S3 或 Alibaba Cloud Object Storage Service (OSS) 目录中，按如下方式为你的源数据创建目标表结构文件：

  1. 为你的源数据创建数据库结构文件。

     如果你的 CSV 文件遵循步骤 1中的命名规则，则数据库结构文件对于数据导入是可选的。否则，数据库结构文件是必需的。

     每个数据库结构文件必须采用 ${db_name}-schema-create.sql 格式，并包含一条 CREATE DATABASE DDL 语句。导入数据时，借助此文件，TiDB Cloud Premium 将创建 ${db_name} 数据库来存储你的数据。

     例如，如果你创建一个 mydb-schema-create.sql 文件，并包含以下语句，则在导入数据时，TiDB Cloud Premium 将创建 mydb 数据库。

     CREATE DATABASE mydb;
     

  2. 为你的源数据创建表结构文件。

     如果你没有在存放 CSV 文件的 Amazon S3 或 Alibaba Cloud Object Storage Service 目录中包含表结构文件，TiDB Cloud Premium 在导入数据时将不会为你创建相应的表。

     每个表结构文件必须采用 ${db_name}.${table_name}-schema.sql 格式，并包含一条 CREATE TABLE DDL 语句。导入数据时，借助此文件，TiDB Cloud Premium 将在 ${db_name} 数据库中创建 ${table_name} 表。

     例如，如果你创建一个 mydb.mytable-schema.sql 文件，并包含以下语句，则在导入数据时，TiDB Cloud Premium 将在 mydb 数据库中创建 mytable 表。

     CREATE TABLE mytable (
     ID INT,
     REGION VARCHAR(20),
     COUNT INT );
     

     注意

     每个 ${db_name}.${table_name}-schema.sql 文件应只包含一条 DDL 语句。如果文件包含多条 DDL 语句，则只有第一条会生效。

步骤 3. 配置跨账号访问

要允许 TiDB Cloud Premium 访问 Amazon S3 或 Alibaba Cloud Object Storage Service (OSS) 中的 CSV 文件，请执行以下任一操作：

• 如果你的 CSV 文件位于 Amazon S3，请为你的 TiDB Cloud Premium 实例配置 Amazon S3 访问。

  你可以使用 AWS access key 或 Role ARN 来访问你的 bucket。完成后，请记下 access key（包括 access key ID 和 secret access key）或 Role ARN 的值，因为你将在步骤 4中用到它。

• 如果你的 CSV 文件位于 Alibaba Cloud Object Storage Service (OSS)，请为你的 TiDB Cloud Premium 实例配置 Alibaba Cloud Object Storage Service (OSS) 访问。

第 4 步：导入 CSV 文件

要将 CSV 文件导入到 TiDB Cloud Premium，请执行以下步骤：

运行导入任务时，如果检测到任何不受支持或无效的转换，TiDB Cloud Premium 会自动终止导入作业并报告导入错误。

如果你遇到导入错误，请执行以下操作：

1. 删除部分已导入的表。
2. 检查表 schema 文件。如果存在任何错误，请更正该表 schema 文件。
3. 检查 CSV 文件中的数据类型。
4. 再次尝试导入任务。

故障排查

解决数据导入期间的警告

点击 Start Import 后，如果你看到类似 can't find the corresponding source files 的警告信息，请通过提供正确的源文件、按照 Naming Conventions for Data Import 重命名现有文件，或使用 Advanced Settings 进行修改来解决此问题。

解决这些问题后，你需要重新导入数据。

导入后的表中行数为零

当导入进度显示为 Completed 后，请检查已导入的表。如果行数为零，表示没有数据文件与您输入的 Bucket URI 匹配。在这种情况下，请通过提供正确的源文件、按照 Naming Conventions for Data Import 重命名现有文件，或使用 Advanced Settings 进行修改来解决此问题。之后，重新导入这些表。