从 MinIO 导入
StarRocks 支持通过以下方式从 MinIO 导入数据:
- 使用 INSERT+
FILES()
进行同步导入。 - 使用 Broker Load 进行异步导入。
两种导入方式各有优势,具体将在下面分章节详细阐述。
一般情况下,建议您使用 INSERT+FILES()
,更为方便易用。
但是,INSERT+FILES()
当前只支持 Parquet 和 ORC 文件格式。因此,如果您需要导入其他格式(如 CSV)的数据、或者需要在导入过程中执行 DELETE 等数据变更操作,可以使用 Broker Load。
准备工作
准备数据源
确保待导入数据已保存在 MinIO 存储桶。建议您将数据保存在与 StarRocks 集群同处一个地域(Region)的 MinIO 存储桶,这样可以降低数据传输成本。
本文中,我们提供了 Parquet 格式的样例数据集 user_behavior_ten_million_rows.parquet
,您可以通过 curl
实现数据导入:
curl -O https://starrocks-examples.s3.amazonaws.com/user_behavior_ten_million_rows.parquet
将 Parquet 文件导入 MinIO,注意存储桶名称的正确性。上述示例以存储桶 /starrocks
为例。
查看权限
导入操作需要目标表的 INSERT 权限。如果您的用户账号没有 INSERT 权限,请参考 GRANT 给用户赋权,语法为 GRANT INSERT ON TABLE <table_name> IN DATABASE <database_name> TO { ROLE <role_name> | USER <user_identity>}
。
获取资源访问配置
概括来说,如果选择使用 MinIO Access Key 认证方式,您需要提前获取以下 MinIO 资源信息:
- 数据所在的 MinIO 存储桶
- MinIO 对象键(或“对象名称”)(只在访问 MinIO 存储桶中某个特定数据对象时才需要。)
- MinIO 终端节点(Endpoint)
- 作为访问凭证的 Access Key 和 Secret Key
通过 INSERT+FILES() 导入
该特性从 3.1 版本起支持。当前只支持 Parquet 和 ORC 文件格式。
INSERT+FILES() 优势
FILES()
会根据给定的数据路径等参数读取数据,并自动根据数据文件的格式、列信息等推断出表结构,最终以数据行的形式返回文件中的数据。
通过 FILES()
,您可以:
- 使用 SELECT 语句直接从 MinIO 查询数据。
- 通过 CREATE TABLE AS SELECT(简称 CTAS)语句实现自动建表和导入数据。
- 手动建表,然后通过 INSERT 导入数据。
操作示例
通过 SELECT 直接查询数据
您可以通过 SELECT+FILES()
直接查询 MinIO 里的数据,从而在建表前对待导入数据有一个整体的了解,其优势包括:
- 您不需要存储数据就可以对其进行查看。
- 您可以查看数据的最大值、最小值,并确定需要使用 哪些数据类型。
- 您可以检查数据中是否包含
NULL
值。
下面示例查询您保存在 MinIO 系统里的 Parquet 文件:
下面命令示例中灰色底纹强化显示的参数配置,需要您根据情况进行替换:
endpoint
和path
需要设置为 MinIO 系统的终端节点和文件存储路径。- 如果 MinIO 系统启用了 SSL,须把
enable_ssl
设置为true
。 - 把
AAA
和BBB
替换为可以用于访问 MinIO 系统的真实有效的 Access Key 和 Secret Key。
SELECT * FROM FILES
(
"aws.s3.endpoint" = "http://minio:9000",
"path" = "s3://starrocks/user_behavior_ten_million_rows.parquet",
"aws.s3.enable_ssl" = "false",
"aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
"aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
"format" = "parquet",
"aws.s3.use_aws_sdk_default_behavior" = "false",
"aws.s3.use_instance_profile" = "false",
"aws.s3.enable_path_style_access" = "true"
)
LIMIT 3;
系统返回如下查询结果:
+--------+---------+------------+--------------+---------------------+
| UserID | ItemID | CategoryID | BehaviorType | Timestamp |
+--------+---------+------------+--------------+---------------------+
| 543711 | 829192 | 2355072 | pv | 2017-11-27 08:22:37 |
| 543711 | 2056618 | 3645362 | pv | 2017-11-27 10:16:46 |
| 543711 | 1165492 | 3645362 | pv | 2017-11-27 10:17:00 |
+--------+---------+------------+--------------+---------------------+
3 rows in set (0.41 sec)
以上返回结果中的列名是源 Parquet 文件中定义的列名。
通过 CTAS 自动建表并导入数据
该示例是上一个示例的延续。该示例中,通过在 CREATE TABLE AS SELECT (CTAS) 语句中嵌套上一个示例中的 SELECT 查询,StarRocks 可以自动推断表结构、创建表、并把数据导入新建的表中。Parquet 格式的文件自带列名和数据类型,因此您不需要指定列名或数据类型。
使用表结构推断功能时,CREATE TABLE 语句不支持设置副本数,因此您需要在建表前把副本数设置好。例如,您可以通过如下命令设置副本数为 1
:
ADMIN SET FRONTEND CONFIG ('default_replication_num' = '1');
通过如下语句创建数据库、并切换至该数据库:
CREATE DATABASE IF NOT EXISTS mydatabase;
USE mydatabase;
通过 CTAS 自动创建表、并把保存在 MinIO 里的样例数据集 user_behavior_ten_million_rows.parquet
中的数据导入到新建表中:
下面命令示例中灰色底纹强化显示的参数配置,需要您根据情况进行替换:
endpoint
和path
需要设置为 MinIO 系统的终端节点和文件存储路径。- 如果 MinIO 系统启用了 SSL,须把
enable_ssl
设置为true
。 - 把
AAA
和BBB
替换为可以用于访问 MinIO 系统的真实有效的 Access Key 和 Secret Key。
CREATE TABLE user_behavior_inferred AS
SELECT * FROM FILES
(
"aws.s3.endpoint" = "http://minio:9000",
"path" = "s3://starrocks/user_behavior_ten_million_rows.parquet",
"aws.s3.enable_ssl" = "false",
"aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA",
"aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
"format" = "parquet",
"aws.s3.use_aws_sdk_default_behavior" = "false",
"aws.s3.use_instance_profile" = "false",
"aws.s3.enable_path_style_access" = "true"
);
Query OK, 10000000 rows affected (3.17 sec)
{'label':'insert_a5da3ff5-9ee4-11ee-90b0-02420a060004', 'status':'VISIBLE', 'txnId':'17'}
建表完成后,您可以通过 DESCRIBE 查看新建表的表结构:
DESCRIBE user_behavior_inferred;
系统返回如下查询结果:
+--------------+------------------+------+-------+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+--------------+------------------+------+-------+---------+-------+
| UserID | bigint | YES | true | NULL | |
| ItemID | bigint | YES | true | NULL | |
| CategoryID | bigint | YES | true | NULL | |
| BehaviorType | varchar(1048576) | YES | false | NULL | |
| Timestamp | varchar(1048576) | YES | false | NULL | |
+--------------+------------------+------+-------+---------+-------+
您可以查询新建表中的数据,验证数据已成功导入。例如:
SELECT * from user_behavior_inferred LIMIT 3;
系统返回如下查询结果 ,表明数据已成功导入:
+--------+--------+------------+--------------+---------------------+
| UserID | ItemID | CategoryID | BehaviorType | Timestamp |
+--------+--------+------------+--------------+---------------------+
| 58 | 158350 | 2355072 | pv | 2017-11-27 13:06:51 |
| 58 | 158590 | 3194735 | pv | 2017-11-27 02:21:04 |
| 58 | 215073 | 3002561 | pv | 2017-11-30 10:55:42 |
+--------+--------+------------+--------------+---------------------+
手动建表并通过 INSERT 导入数据
在实际业务场景中,您可能需要自定义目标表的表结构,包括:
- 各列的数据类型和默认值、以及是否允许
NULL
值 - 定义哪些列作为键、以及这些列的数据类型
- 数据分区分桶
要实现高效的表结构设计,您需要深度了解表中数据的用途、以及表中各列的内容。本文不对表设计做过多赘述,有关表设计的详细信息,参见表设计。
该示例主要演示如何根据源 Parquet 文件中数据的特点、以及目标表未来的查询用途等对目标表进行定义和创建。在创建表之前,您可以先查看一下保存在 MinIO 中的源文件,从而了解源文件中数据的特点,例如:
- 源文件中包含一个数据类 型为
datetime
的Timestamp
列,因此建表语句中也应该定义这样一个数据类型为datetime
的Timestamp
列。 - 源文件中的数据中没有
NULL
值,因此建表语句中也不需要定义任何列为允许NULL
值。 - 根据未来的查询类型,可以在建表语句中定义
UserID
列为排序键和分桶键。根据实际业务场景需要,您还可以定义其他列比如ItemID
或者定义UserID
与其他列的组合作为排序键。
通过如下语句创建数据库、并切换至该数据库:
CREATE DATABASE IF NOT EXISTS mydatabase;
USE mydatabase;