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

你可以将未压缩和 Snappy 压缩的 Apache Parquet 格式数据文件导入到平凯云 Starter 或平凯云 Essential。本文档介绍如何将 Parquet 文件从阿里云对象存储服务（OSS）导入到平凯云 Starter 或平凯云 Essential。腾讯云对象存储 COS 支持情况请以平凯数据库云服务控制台为准。

i

注意

• 平凯数据库云服务仅支持将 Parquet 文件导入到空表中。若需将数据导入到已存在且包含数据的表中，你可以按照本文档将数据导入到一个临时空表，然后使用 INSERT SELECT 语句将数据复制到目标已存在的表中。
• Snappy 压缩文件必须采用 官方 Snappy 格式。不支持其他变体的 Snappy 压缩格式。

第 1 步：准备 Parquet 文件

i

注意

当前，平凯数据库云服务不支持导入包含以下任意数据类型的 Parquet 文件。如果待导入的 Parquet 文件包含这些数据类型，你需要先使用 支持的数据类型（例如 STRING）重新生成 Parquet 文件。或者，你也可以使用其他数据处理服务转换数据类型。

• LIST
• NEST STRUCT
• BOOL
• ARRAY
• MAP

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

   平凯数据库云服务支持导入非常大的 Parquet 文件，但在多个约 256 MB 的输入文件时性能最佳。这是因为平凯数据库云服务可以并行处理多个文件，从而大幅提升导入速度。

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

   • 如果一个 Parquet 文件包含整个表的所有数据，文件名应采用 ${db_name}.${table_name}.parquet 格式，导入数据时会映射到 ${db_name}.${table_name} 表。
   • 如果一个表的数据被拆分到多个 Parquet 文件中，应为这些 Parquet 文件添加数字后缀。例如，${db_name}.${table_name}.000001.parquet 和 ${db_name}.${table_name}.000002.parquet。数字后缀可以不连续，但必须为正序。你还需要在数字前补零，以保证所有后缀长度一致。

   i

   注意

   如果在某些情况下你无法按照上述规则修改 Parquet 文件名（例如，这些 Parquet 文件链接也被你的其他程序使用），你可以保持文件名不变，并在 第 4 步 的 Mapping Settings 中将源数据导入到单一目标表。

第 2 步：创建目标表结构

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

• 方法 1：在平凯数据库云服务中为你的源数据创建目标数据库和表。

• 方法 2：在存放 Parquet 文件的阿里云对象存储服务目录下，为你的源数据创建目标表结构文件，具体如下：

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

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

     每个数据库结构文件必须采用 ${db_name}-schema-create.sql 格式，并包含一个 CREATE DATABASE DDL 语句。通过该文件，平凯数据库云服务会在导入数据时创建 ${db_name} 数据库以存储你的数据。

     例如，如果你创建了一个包含如下语句的 mydb-schema-create.sql 文件，平凯数据库云服务会在导入数据时创建 mydb 数据库。

     CREATE DATABASE mydb;

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

     如果你没有在存放 Parquet 文件的阿里云对象存储服务目录下包含表结构文件，平凯数据库云服务在导入数据时不会为你创建相应的表。

     每个表结构文件必须采用 ${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 );

     i

     注意

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

第 3 步：配置跨账户访问

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

第 4 步：导入 Parquet 文件

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

1. 打开目标 平凯云 Starter 或 Essential 实例的 Import 页面。

   1. 登录 平凯数据库云服务控制台，并进入集群列表页面。

      i

      提示：

      如果你属于多个组织，请使用左上角的下拉框先切换到目标组织。

   2. 点击目标 平凯云 Starter 或 Essential 实例名称进入其概览页面，然后在左侧导航栏点击 Data > Import。

2. 点击 Import data from Cloud Storage。

3. 在 Import Data from Cloud Storage 页面，填写以下信息：

   • Storage Provider：选择 阿里云 OSS。
   • Source Files URI：
     • 导入单个文件时，输入源文件 URI，格式为 oss://[bucket_name]/[data_source_folder]/[file_name].parquet。例如：oss://sampledata/ingest/TableName.01.parquet。
     • 导入多个文件时，输入源文件夹 URI，格式为 oss://[bucket_name]/[data_source_folder]/。例如：oss://sampledata/ingest/。
   • Credential：你可以使用 AccessKey 对访问你的 bucket。详情参见 配置阿里云对象存储服务（OSS）访问。

4. 点击 Next。

5. 在 Destination Mapping 部分，指定源文件与目标表的映射方式。

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

   i

   注意

   当 Source Files URI 指定为单个文件时，不显示 Use File naming conventions for automatic mapping 选项，平凯数据库云服务会自动将 Source 字段填充为文件名。此时你只需选择目标数据库和表进行数据导入。

   • 若希望平凯数据库云服务自动将所有遵循 文件命名规范 的源文件映射到对应表，请保持该选项选中，并选择 Parquet 作为数据格式。

   • 若需手动配置映射规则，将你的源 Parquet 文件与目标数据库和表关联，请取消选中该选项，然后填写以下字段：

     • Source：输入文件名模式，格式为 [file_name].parquet。例如：TableName.01.parquet。你也可以使用通配符匹配多个文件，仅支持 * 和 ? 通配符。

       • my-data?.parquet：匹配所有以 my-data 开头，后跟单个字符的 Parquet 文件，如 my-data1.parquet 和 my-data2.parquet。
       • my-data*.parquet：匹配所有以 my-data 开头的 Parquet 文件，如 my-data-2023.parquet 和 my-data-final.parquet。

     • Target Database 和 Target Table：选择要导入数据的目标数据库和表。

6. 点击 Next。平凯数据库云服务会相应扫描源文件。

7. 查看扫描结果，检查找到的数据文件及其对应的目标表，然后点击 Start Import。

8. 当导入进度显示 Completed 时，检查已导入的表。

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

如果你遇到导入错误，请按以下步骤操作：

1. 删除部分导入的表。

2. 检查表结构文件。如果有错误，请修正表结构文件。

3. 检查 Parquet 文件中的数据类型。

   如果 Parquet 文件包含任何不支持的数据类型（如 NEST STRUCT、ARRAY 或 MAP），你需要使用 支持的数据类型（如 STRING）重新生成 Parquet 文件。

4. 重新尝试导入任务。

支持的数据类型

下表列出了可导入到平凯云 Starter 和平凯云 Essential 的 Parquet 支持数据类型。

故障排查

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

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

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

导入表中行数为零

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