大网数据广告活动
数据库部署与 SQL 参考

Apache Doris 中文参考:Amazon S3

· 52CE 我爱测

Doris 提供以下方式从 AWS S3 导入文件,可根据是否需要持续接入、是否需要同步等待结果,以及文件的生成方式选择:

Doris 提供以下方式从 AWS S3 导入文件,可根据是否需要持续接入、是否需要同步等待结果,以及文件的生成方式选择:

方式 类型 适用场景
S3 Load 异步导入 大批量数据导入、定时任务、对吞吐与稳定性要求较高的离线导入
TVF(Table Value Function) 同步导入 即席查询、ETL 加工、配合 INSERT INTO ... SELECT 的同步写入
Streaming Job 后台分批导入 持续接入新文件,或一次性导入文件并跟踪可恢复的分批进度

Streaming Job 提供三种模式:

  • 有序导入:文件名按字典序递增时持续扫描新文件。
  • 通知导入:通过 AWS S3 事件和独占 SQS 队列接入新文件,适合文件名无序的场景;不补导历史对象,且可能重复导入。
  • 一次性导入:对已准备好的静态文件分批导入,完成后作业自动结束。

对于一次性任务,已有 LOAD LABEL 异步流程可继续使用 S3 Load;需要同步执行 SQL 加工并等待结果时使用 TVF + INSERT;希望由作业维护分批进度、支持中断恢复并在完成后自动结束时,可以选择 Streaming Job 的一次性模式。

提示:S3 Load 基于 Broker Load 实现,详细行为可参考 Broker Load 手册。

方式一:使用 S3 Load 导入(异步)

S3 Load 是一种异步导入方式,提交后立即返回,由后台执行。适合数据量较大或需要后台批处理的场景。

第 1 步:准备数据

在 S3 上创建 CSV 文件 s3load_example.csv,其内容如下:

1,Emily,25
2,Benjamin,35
3,Olivia,28
4,Alexander,60
5,Ava,17
6,William,69
7,Sophia,32
8,James,64
9,Emma,37
10,Liam,64

第 2 步:在 Doris 中创建表

CREATE TABLE test_s3load(
    user_id            BIGINT       NOT NULL COMMENT "user id",
    name               VARCHAR(20)           COMMENT "name",
    age                INT                   COMMENT "age"
)
DUPLICATE KEY(user_id)
DISTRIBUTED BY HASH(user_id) BUCKETS 10;

第 3 步:使用 S3 Load 导入数据

LOAD LABEL s3_load_2022_04_01
(
    DATA INFILE("s3://your_bucket_name/s3load_example.csv")
    INTO TABLE test_s3load
    COLUMNS TERMINATED BY ","
    FORMAT AS "CSV"
    (user_id, name, age)
)
WITH S3
(
    "provider" = "S3",
    "s3.endpoint" = "https://s3.us-west-2.amazonaws.com",
    "s3.region" = "us-west-2",
    "s3.access_key" = "<your-ak>",
    "s3.secret_key" = "<your-sk>"
)
PROPERTIES
(
    "timeout" = "3600"
);

关键参数说明:

参数 说明
DATA INFILE S3 上待导入文件的 URI,格式为 s3://bucket/path
COLUMNS TERMINATED BY CSV 列分隔符
FORMAT AS 文件格式,例如 CSV
provider 对象存储提供商,AWS S3 填写 S3
s3.endpoint S3 服务的 Endpoint,例如 s3.us-west-2.amazonaws.com
s3.region S3 Bucket 所在的 Region
s3.access_key AWS Access Key
s3.secret_key AWS Secret Key
timeout 导入任务超时时间,单位秒

第 4 步:检查导入数据

SELECT * FROM test_s3load;

预期结果:

mysql> select * from test_s3load;
+---------+-----------+------+
| user_id | name      | age  |
+---------+-----------+------+
|       5 | Ava       |   17 |
|      10 | Liam      |   64 |
|       7 | Sophia    |   32 |
|       9 | Emma      |   37 |
|       1 | Emily     |   25 |
|       4 | Alexander |   60 |
|       2 | Benjamin  |   35 |
|       3 | Olivia    |   28 |
|       6 | William   |   69 |
|       8 | James     |   64 |
+---------+-----------+------+
10 rows in set (0.04 sec)

方式二:使用 TVF 导入(同步) {#method-2-load-with-tvf-synchronous}

TVF(Table Value Function)将 S3 上的文件视为一张表,可直接通过 SELECT 查询,并配合 INSERT INTO 同步写入 Doris 表中。适合对结果可见性要求较高、数据量适中的场景。

第 1 步:准备数据

在 S3 上创建 CSV 文件 s3load_example.csv,其内容如下:

1,Emily,25
2,Benjamin,35
3,Olivia,28
4,Alexander,60
5,Ava,17
6,William,69
7,Sophia,32
8,James,64
9,Emma,37
10,Liam,64

第 2 步:在 Doris 中创建表

CREATE TABLE test_s3load(
    user_id            BIGINT       NOT NULL COMMENT "user id",
    name               VARCHAR(20)           COMMENT "name",
    age                INT                   COMMENT "age"
)
DUPLICATE KEY(user_id)
DISTRIBUTED BY HASH(user_id) BUCKETS 10;

第 3 步:使用 TVF 导入数据

INSERT INTO test_s3load
SELECT * FROM S3
(
    "uri" = "s3://your_bucket_name/s3load_example.csv",
    "format" = "csv",
    "s3.endpoint" = "https://s3.us-west-2.amazonaws.com",
    "s3.region" = "us-west-2",
    "s3.access_key" = "<your-ak>",
    "s3.secret_key" = "<your-sk>",
    "column_separator" = ",",
    "csv_schema" = "user_id:int;name:string;age:int"
);

关键参数说明:

参数 说明
uri S3 上待读取文件的 URI
format 文件格式,例如 csv
s3.endpoint S3 服务的 Endpoint
s3.region S3 Bucket 所在的 Region
s3.access_key AWS Access Key
s3.secret_key AWS Secret Key
column_separator 列分隔符
csv_schema CSV 文件的 Schema 定义,格式为 列名:类型;...

第 4 步:检查导入数据

SELECT * FROM test_s3load;

预期结果:

mysql> select * from test_s3load;
+---------+-----------+------+
| user_id | name      | age  |
+---------+-----------+------+
|       5 | Ava       |   17 |
|      10 | Liam      |   64 |
|       7 | Sophia    |   32 |
|       9 | Emma      |   37 |
|       1 | Emily     |   25 |
|       4 | Alexander |   60 |
|       2 | Benjamin  |   35 |
|       3 | Olivia    |   28 |
|       6 | William   |   69 |
|       8 | James     |   64 |
+---------+-----------+------+
10 rows in set (0.04 sec)

使用 AWS Assume Role 鉴权

除了使用 Access Key / Secret Key,Doris 也支持通过 AWS Assume Role 的方式使用 S3 Load 与 TVF 进行鉴权,适合企业内对密钥下发受限的场景。详细配置请参考 AWS 集成 - Assumed Role 认证。

FAQ

Q1:S3 Load 与 TVF 应该如何选择?

  • 大批量、离线、定时任务:优先使用 S3 Load(异步、可后台执行、支持超时控制)。
  • 即席查询、需要在 SQL 中加工后写入:优先使用 TVF(同步、可与 SELECT/INSERT 组合)。

Q2:如何指定 S3 文件的 Region 与 Endpoint?

  • 通过 s3.region 指定 Bucket 所在 Region,例如 us-west-2。
  • 通过 s3.endpoint 指定服务地址,例如 s3.us-west-2.amazonaws.com。
  • 两者需保持一致,否则可能出现连接失败或重定向错误。

Q3:TVF 导入时是否必须提供 csv_schema?

当源文件为 CSV 时,建议显式提供 csv_schema,明确每列的名称与类型,避免类型推断带来的不确定性。

Q4:S3 Load 任务执行时间过长怎么办?

可以适当调大 PROPERTIES 中的 timeout(单位秒),示例中为 3600,可根据数据规模调整。

Troubleshooting

现象 可能原因 处理建议
连接 S3 失败 / 超时 s3.endpoint 与 s3.region 不匹配,或网络不通 校对 Endpoint 与 Region;确认 Doris BE 节点可访问 S3
鉴权失败(403) Access Key / Secret Key 错误,或权限不足 检查 AK/SK 是否正确;确认对应 Bucket 与 Object 的读权限
文件未找到 DATA INFILE / uri 路径错误 确认 Bucket 名称、Key 路径以及大小写
CSV 解析错误 分隔符或 Schema 不匹配 检查 COLUMNS TERMINATED BY / column_separator 与 csv_schema
任务超时 数据量大或网络较慢 增大 timeout;或拆分文件并行导入

相关文档

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。