从云存储导入 Apache Parquet 文件到 TiDB Cloud Starter 或 Essential
你可以将未压缩或 Snappy 压缩的 Apache Parquet 格式数据文件导入到 TiDB Cloud Starter 或 TiDB Cloud Essential。本文档介绍如何将 Parquet 文件从 Amazon Simple Storage Service(Amazon S3)、Google Cloud Storage(GCS)、Azure Blob Storage 或阿里云对象存储服务(OSS)导入到 TiDB Cloud Starter 或 TiDB Cloud Essential。
第 1 步:准备 Parquet 文件
如果单个 Parquet 文件大于 256 MB,建议将其拆分为多个小文件,每个文件大小约为 256 MB。
TiDB Cloud 支持导入非常大的 Parquet 文件,但在多个约 256 MB 的输入文件时性能最佳。这是因为 TiDB Cloud 可以并行处理多个文件,从而大幅提升导入速度。
按如下方式命名 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
。数字后缀可以不连续,但必须递增,并且需要在数字前补零以保证所有后缀长度一致。
- 如果一个 Parquet 文件包含整个表的所有数据,文件名应采用
第 2 步:创建目标表结构
由于 Parquet 文件不包含表结构信息,在将 Parquet 文件中的数据导入 TiDB Cloud 之前,你需要通过以下任一方式创建表结构:
方法 1:在 TiDB Cloud 中为源数据创建目标数据库和数据表。
方法 2:在存放 Parquet 文件的 Amazon S3、GCS、Azure Blob Storage 或阿里云对象存储服务目录下,为源数据创建目标表结构文件:
为源数据创建数据库结构文件。
如果你的 Parquet 文件遵循 第 1 步 的命名规则,则数据库结构文件在数据导入时为可选项。否则,数据库结构文件为必需项。
每个数据库结构文件必须采用
${db_name}-schema-create.sql
格式,并包含一个CREATE DATABASE
DDL 语句。通过该文件,TiDB Cloud 会在导入数据时创建${db_name}
数据库以存储你的数据。例如,如果你创建了一个包含如下语句的
mydb-scehma-create.sql
文件,TiDB Cloud 会在导入数据时创建mydb
数据库。CREATE DATABASE mydb;为源数据创建数据表结构文件。
如果你没有在 Parquet 文件所在的 Amazon S3、GCS、Azure Blob Storage 或阿里云对象存储服务目录下包含表结构文件,TiDB Cloud 在导入数据时不会为你创建相应的数据表。
每个表结构文件必须采用
${db_name}.${table_name}-schema.sql
格式,并包含一个CREATE TABLE
DDL 语句。通过该文件,TiDB Cloud 会在导入数据时在${db_name}
数据库中创建${db_table}
表。例如,如果你创建了一个包含如下语句的
mydb.mytable-schema.sql
文件,TiDB Cloud 会在mydb
数据库中创建mytable
表。CREATE TABLE mytable ( ID INT, REGION VARCHAR(20), COUNT INT );
第 3 步:配置跨账号访问
为了让 TiDB Cloud 能够访问 Amazon S3、GCS、Azure Blob Storage 或阿里云对象存储服务桶中的 Parquet 文件,请执行以下操作之一:
如果你的 Parquet 文件位于 Amazon S3,请为集群 配置 Amazon S3 访问权限。
你可以使用 AWS 访问密钥或 Role ARN 访问你的桶。完成后,请记录访问密钥(包括访问密钥 ID 和密钥访问密钥)或 Role ARN 值,在 第 4 步 中会用到。
如果你的 Parquet 文件位于 GCS,请为集群 配置 GCS 访问权限。
如果你的 Parquet 文件位于 Azure Blob Storage,请为集群 配置 Azure Blob Storage 访问权限。
如果你的 Parquet 文件位于阿里云对象存储服务(OSS),请为集群 配置阿里云对象存储服务(OSS)访问权限。
第 4 步:导入 Parquet 文件
要将 Parquet 文件导入到 TiDB Cloud Starter 或 TiDB Cloud Essential,请按照以下步骤操作:
打开目标集群的 Import 页面。
登录 TiDB Cloud 控制台,进入项目的 Clusters 页面。
点击目标集群名称进入其概览页面,然后在左侧导航栏点击 Data > Import。
点击 Import data from Cloud Storage。
在 Import Data from Cloud Storage 页面,填写以下信息:
- Storage Provider:选择 Amazon S3。
- Source Files URI:
- 导入单个文件时,输入源文件 URI,格式为
s3://[bucket_name]/[data_source_folder]/[file_name].parquet
。例如,s3://sampledata/ingest/TableName.01.parquet
。 - 导入多个文件时,输入源文件夹 URI,格式为
s3://[bucket_name]/[data_source_folder]/
。例如,s3://sampledata/ingest/
。
- 导入单个文件时,输入源文件 URI,格式为
- Credential:你可以使用 AWS Role ARN 或 AWS 访问密钥访问你的桶。更多信息请参见 Configure Amazon S3 access。
- AWS Role ARN:输入 AWS Role ARN 值。
- AWS Access Key:输入 AWS 访问密钥 ID 和 AWS 密钥访问密钥。
点击 Next。
在 Destination Mapping 部分,指定源文件与目标表的映射方式。
当 Source Files URI 指定为目录时,默认勾选 Use File naming conventions for automatic mapping 选项。
若希望 TiDB Cloud 自动将所有遵循 File naming conventions 的源文件映射到对应表,请保持该选项勾选,并选择 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:选择要导入数据的目标数据库和表。
点击 Next。TiDB Cloud 会相应地扫描源文件。
查看扫描结果,检查找到的数据文件及其对应的目标表,然后点击 Start Import。
当导入进度显示 Completed 时,检查已导入的表。
打开目标集群的 Import 页面。
登录 TiDB Cloud 控制台,进入项目的 Clusters 页面。
点击目标集群名称进入其概览页面,然后在左侧导航栏点击 Data > Import。
点击 Import data from Cloud Storage。
在 Import Data from Cloud Storage 页面,填写以下信息:
- Storage Provider:选择 Google Cloud Storage。
- Source Files URI:
- 导入单个文件时,输入源文件 URI,格式为
[gcs|gs]://[bucket_name]/[data_source_folder]/[file_name].parquet
。例如,[gcs|gs]://sampledata/ingest/TableName.01.parquet
。 - 导入多个文件时,输入源文件夹 URI,格式为
[gcs|gs]://[bucket_name]/[data_source_folder]/
。例如,[gcs|gs]://sampledata/ingest/
。
- 导入单个文件时,输入源文件 URI,格式为
- Credential:你可以使用 GCS IAM Role Service Account key 访问你的桶。更多信息请参见 Configure GCS access。
点击 Next。
在 Destination Mapping 部分,指定源文件与目标表的映射方式。
当 Source Files URI 指定为目录时,默认勾选 Use File naming conventions for automatic mapping 选项。
若希望 TiDB Cloud 自动将所有遵循 File naming conventions 的源文件映射到对应表,请保持该选项勾选,并选择 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:选择要导入数据的目标数据库和表。
点击 Next。TiDB Cloud 会相应地扫描源文件。
查看扫描结果,检查找到的数据文件及其对应的目标表,然后点击 Start Import。
当导入进度显示 Completed 时,检查已导入的表。
打开目标集群的 Import 页面。
登录 TiDB Cloud 控制台,进入项目的 Clusters 页面。
点击目标集群名称进入其概览页面,然后在左侧导航栏点击 Data > Import。
点击 Import data from Cloud Storage。
在 Import Data from Cloud Storage 页面,填写以下信息:
- Storage Provider:选择 Azure Blob Storage。
- Source Files URI:
- 导入单个文件时,输入源文件 URI,格式为
[azure|https]://[bucket_name]/[data_source_folder]/[file_name].parquet
。例如,[azure|https]://sampledata/ingest/TableName.01.parquet
。 - 导入多个文件时,输入源文件夹 URI,格式为
[azure|https]://[bucket_name]/[data_source_folder]/
。例如,[azure|https]://sampledata/ingest/
。
- 导入单个文件时,输入源文件 URI,格式为
- Credential:你可以使用共享访问签名(SAS)令牌访问你的桶。更多信息请参见 Configure Azure Blob Storage access。
点击 Next。
在 Destination Mapping 部分,指定源文件与目标表的映射方式。
当 Source Files URI 指定为目录时,默认勾选 Use File naming conventions for automatic mapping 选项。
若希望 TiDB Cloud 自动将所有遵循 File naming conventions 的源文件映射到对应表,请保持该选项勾选,并选择 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:选择要导入数据的目标数据库和表。
点击 Next。TiDB Cloud 会相应地扫描源文件。
查看扫描结果,检查找到的数据文件及其对应的目标表,然后点击 Start Import。
当导入进度显示 Completed 时,检查已导入的表。
打开目标集群的 Import 页面。
登录 TiDB Cloud 控制台,进入项目的 Clusters 页面。
点击目标集群名称进入其概览页面,然后在左侧导航栏点击 Data > Import。
点击 Import data from Cloud Storage。
在 Import Data from Cloud Storage 页面,填写以下信息:
- Storage Provider:选择 Alibaba Cloud 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/
。
- 导入单个文件时,输入源文件 URI,格式为
- Credential:你可以使用 AccessKey 对访问你的桶。更多信息请参见 Configure Alibaba Cloud Object Storage Service (OSS) access。
点击 Next。
在 Destination Mapping 部分,指定源文件与目标表的映射方式。
当 Source Files URI 指定为目录时,默认勾选 Use File naming conventions for automatic mapping 选项。
若希望 TiDB Cloud 自动将所有遵循 File naming conventions 的源文件映射到对应表,请保持该选项勾选,并选择 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:选择要导入数据的目标数据库和表。
点击 Next。TiDB Cloud 会相应地扫描源文件。
查看扫描结果,检查找到的数据文件及其对应的目标表,然后点击 Start Import。
当导入进度显示 Completed 时,检查已导入的表。
当你运行导入任务时,如果检测到任何不支持或无效的类型转换,TiDB Cloud 会自动终止导入任务并报告导入错误。
如果你遇到导入错误,请按以下步骤操作:
删除部分已导入的表。
检查表结构文件,如有错误请修正表结构文件。
检查 Parquet 文件中的数据类型。
如果 Parquet 文件包含任何不支持的数据类型(如
NEST STRUCT
、ARRAY
或MAP
),你需要使用 支持的数据类型(如STRING
)重新生成 Parquet 文件。重新尝试导入任务。
支持的数据类型
下表列出了可导入到 TiDB Cloud Starter 和 TiDB Cloud Essential 的 Parquet 支持数据类型。
Parquet Primitive Type | Parquet Logical Type | Types in TiDB or MySQL |
---|---|---|
DOUBLE | DOUBLE | DOUBLE FLOAT |
FIXED_LEN_BYTE_ARRAY(9) | DECIMAL(20,0) | BIGINT UNSIGNED |
FIXED_LEN_BYTE_ARRAY(N) | DECIMAL(p,s) | DECIMAL NUMERIC |
INT32 | DECIMAL(p,s) | DECIMAL NUMERIC |
INT32 | N/A | INT MEDIUMINT YEAR |
INT64 | DECIMAL(p,s) | DECIMAL NUMERIC |
INT64 | N/A | BIGINT INT UNSIGNED MEDIUMINT UNSIGNED |
INT64 | TIMESTAMP_MICROS | DATETIME TIMESTAMP |
BYTE_ARRAY | N/A | BINARY BIT BLOB CHAR LINESTRING LONGBLOB MEDIUMBLOB MULTILINESTRING TINYBLOB VARBINARY |
BYTE_ARRAY | STRING | ENUM DATE DECIMAL GEOMETRY GEOMETRYCOLLECTION JSON LONGTEXT MEDIUMTEXT MULTIPOINT MULTIPOLYGON NUMERIC POINT POLYGON SET TEXT TIME TINYTEXT VARCHAR |
SMALLINT | N/A | INT32 |
SMALLINT UNSIGNED | N/A | INT32 |
TINYINT | N/A | INT32 |
TINYINT UNSIGNED | N/A | INT32 |
故障排查
解决数据导入过程中的警告
点击 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 进行修改来解决。之后,重新导入这些表。