从云存储导入 CSV 文件到平凯云 Starter 或 Essential

本文档介绍如何将 CSV 文件从阿里云对象存储服务（OSS）导入到平凯云 Starter 或平凯云 Essential。腾讯云对象存储 COS 支持情况请以平凯数据库云服务控制台为准。

限制

为保证数据一致性，平凯数据库云服务仅允许将 CSV 文件导入到空表中。如果你需要将数据导入到已存在且包含数据的表中，可以按照本文档的方式先将数据导入到一个临时空表，然后使用 INSERT SELECT 语句将数据复制到目标已存在的表中。

第 1 步：准备 CSV 文件

如果单个 CSV 文件大于 256 MiB，建议将其切分为多个小文件，每个文件大小约为 256 MiB。

平凯数据库云服务支持导入非常大的 CSV 文件，但当输入文件为多个且每个文件大小约为 256 MiB 时，性能最佳。这是因为平凯数据库云服务可以并行处理多个文件，从而大幅提升导入速度。
按如下方式命名 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。数字后缀可以不连续，但必须为正序。你还需要在数字前补零，以保证所有后缀长度一致。
- 平凯数据库云服务支持导入以下格式的压缩文件：.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。
i
注意
- 为获得更好的性能，建议每个压缩文件大小不超过 100 MiB。
- Snappy 压缩文件必须为官方 Snappy 格式。不支持其他变体的 Snappy 压缩格式。
- 对于未压缩的文件，如果你在某些场景下无法按照上述规则修改 CSV 文件名（例如，CSV 文件链接也被你的其他程序使用），可以保持文件名不变，并在第 4 步的 Mapping Settings 中，将源数据导入到单一目标表。

第 2 步：创建目标表结构

由于 CSV 文件不包含表结构信息，在将 CSV 文件中的数据导入平凯数据库云服务之前，你需要通过以下任一方法创建表结构：

方法 1：在平凯数据库云服务中，为你的源数据创建目标数据库和表。
方法 2：在存放 CSV 文件的阿里云对象存储服务目录下，为你的源数据创建目标表结构文件：
1. 为你的源数据创建数据库结构文件。
  
  如果你的 CSV 文件遵循第 1 步的命名规则，则数据库结构文件为可选项。否则，数据库结构文件为必需项。
  
  每个数据库结构文件必须采用 ${db_name}-schema-create.sql 格式，并包含一个 CREATE DATABASE DDL 语句。通过该文件，平凯数据库云服务会在导入数据时创建 ${db_name} 数据库以存储你的数据。
  
  例如，如果你创建了一个包含如下语句的 mydb-schema-create.sql 文件，平凯数据库云服务会在导入数据时创建 mydb 数据库。
```
CREATE DATABASE mydb;
```
2. 为你的源数据创建表结构文件。
  
  如果你没有在存放 CSV 文件的阿里云对象存储服务目录下包含表结构文件，平凯数据库云服务在导入数据时不会为你创建相应的表。
  
  每个表结构文件必须采用 ${db_name}.${table_name}-schema.sql 格式，并包含一个 CREATE TABLE DDL 语句。通过该文件，平凯数据库云服务会在导入数据时，在 ${db_name} 数据库中创建 ${db_table} 表。
  
  例如，如果你创建了一个包含如下语句的 mydb.mytable-schema.sql 文件，平凯数据库云服务会在导入数据时，在 mydb 数据库中创建 mytable 表。
```
CREATE TABLE mytable (
ID INT,
REGION VARCHAR(20),
COUNT INT );
```
  注意
  
  每个 ${db_name}.${table_name}-schema.sql 文件只能包含一个 DDL 语句。如果文件中包含多个 DDL 语句，只有第一个会生效。

第 3 步：配置跨账户访问

为了让平凯数据库云服务能够访问阿里云对象存储服务桶中的 CSV 文件，请为你的平凯云 Starter 或 Essential 实例配置阿里云对象存储服务（OSS）访问。

第 4 步：导入 CSV 文件

要将 CSV 文件导入到平凯云 Starter 或平凯云 Essential，请按照以下步骤操作：

打开目标平凯云 Starter 或 Essential 实例的 Import 页面。
1. 登录平凯数据库云服务控制台，进入集群列表页面。
  
  提示：
  
  如果你属于多个组织，请先使用左上角的下拉框切换到目标组织。
2. 点击目标平凯云 Starter 或 Essential 实例名称进入概览页面，然后在左侧导航栏点击 Data > Import。
点击 Import data from Cloud Storage。
在 Import Data from Cloud Storage 页面，填写以下信息：
- Storage Provider：选择 阿里云 OSS。
- Source Files URI：
  - 导入单个文件时，输入源文件 URI，格式为 oss://[bucket_name]/[data_source_folder]/[file_name].csv。例如，oss://sampledata/ingest/TableName.01.csv。
  - 导入多个文件时，输入源文件夹 URI，格式为 oss://[bucket_name]/[data_source_folder]/。例如，oss://sampledata/ingest/。
- Credential：你可以使用 AccessKey 对访问你的桶。详情参见配置阿里云对象存储服务（OSS）访问。
点击 Next。
在 Destination Mapping 部分，指定源文件与目标表的映射方式。

当 Source Files URI 指定为目录时，Use File naming conventions for automatic mapping 选项默认被选中。

注意

当 Source Files URI 指定为单个文件时，不显示 Use File naming conventions for automatic mapping 选项，平凯数据库云服务会自动将 Source 字段填充为文件名。此时，你只需选择目标数据库和表进行数据导入。
- 若希望平凯数据库云服务自动将所有遵循文件命名规范的源文件映射到对应表，请保持该选项选中，并选择 CSV 作为数据格式。
- 若需手动配置映射规则，将你的源 CSV 文件与目标数据库和表关联，请取消选中该选项，并填写以下字段：
  - Source：输入文件名模式，格式为 [file_name].csv。例如：TableName.01.csv。你也可以使用通配符匹配多个文件，仅支持 * 和 ? 通配符。
    - my-data?.csv：匹配所有以 my-data 开头，后跟单个字符的 CSV 文件，如 my-data1.csv 和 my-data2.csv。
    - my-data*.csv：匹配所有以 my-data 开头的 CSV 文件，如 my-data-2023.csv 和 my-data-final.csv。
  - Target Database 和 Target Table：选择要导入数据的目标数据库和表。
点击 Next。平凯数据库云服务会相应扫描源文件。
查看扫描结果，检查找到的数据文件及其对应的目标表，然后点击 Start Import。
当导入进度显示 Completed 时，检查已导入的表。

当你运行导入任务时，如果检测到任何不支持或无效的转换，平凯数据库云服务会自动终止导入作业并报告导入错误。

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

删除部分已导入的表。
检查表结构文件，如有错误请修正。
检查 CSV 文件中的数据类型。
重新尝试导入任务。

故障排查

解决数据导入过程中的警告

点击 Start Import 后，如果你看到类似 can't find the corresponding source files 的警告信息，请通过提供正确的源文件、按照数据导入命名规范重命名现有文件，或使用 Advanced Settings 进行调整来解决。

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

导入表中行数为零

当导入进度显示 Completed 后，检查已导入的表。如果行数为零，说明没有数据文件匹配你输入的 Bucket URI。此时，请通过提供正确的源文件、按照数据导入命名规范重命名现有文件，或使用 Advanced Settings 进行调整来解决。之后，重新导入这些表。