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

持续导入概览

· 52CE 我爱测

Doris 支持通过 **Streaming Job** 的方式,从多种数据源持续导入数据到 Doris 表中。提交 Job 后,Doris 会持续运行导入作业,实时读取数据源中的数据并写入到 Doris 表中。

Doris 持续导入为实验性功能,自 Doris 4.1.5 版本起支持。

Doris 支持通过 Streaming Job 的方式,从多种数据源持续导入数据到 Doris 表中。提交 Job 后,Doris 会持续运行导入作业,实时读取数据源中的数据并写入到 Doris 表中。

本文将帮助你解决以下问题:

  • 持续导入支持哪些数据源和同步模式?
  • SQL 映射同步与自动建表同步该如何选择?
  • 作业的运行状态如何流转、如何自动恢复?
  • 日常如何查看、暂停、恢复、删除导入作业?
  • 有哪些通用的 FE 与 Job 配置参数?

支持的数据源与同步模式

持续导入支持以下数据源和同步模式。S3 通知导入和一次性导入自 Doris 4.1.6 版本起支持:

数据源 支持版本 SQL 映射同步 自动建表同步 配置指南
MySQL 5.6、5.7、8.0.x MySQL CDC SQL 映射同步 MySQL CDC 自动建表同步 Amazon RDS MySQL · Amazon Aurora MySQL
PostgreSQL 14、15、16、17 PostgreSQL CDC SQL 映射同步 PostgreSQL CDC 自动建表同步 Amazon RDS PostgreSQL · Amazon Aurora PostgreSQL
OceanBase MySQL 兼容模式 - OceanBase CDC 自动建表同步 -
S3 - S3 导入概览 - -

上游列类型如何映射为 Doris 类型,见 MySQL、PostgreSQL和 OceanBase 数据类型映射。

如何选择同步方式

SQL 映射同步和自动建表同步是两种实现机制完全不同的持续导入方式,并非"表数量"的区别。自动建表同步也支持通过 include_tables 只同步一张表,因此选型应以能力需求为准。

能力对比

能力维度 SQL 映射同步 自动建表同步
底层机制 Job + TVF(INSERT INTO tbl SELECT * FROM tvf()) Job + 原生整库 DDL(FROM src TO DATABASE db)
目标层级 一张已存在的 Doris 表 一个 Doris 数据库
同步范围 单张表 一张到多张到整库(由 include_tables 控制)
自动建表 需预建 首次同步自动创建主键表
SQL 灵活表达 支持列映射、过滤、转换(SELECT 子句) 支持目标表重命名和排除非主键列;不支持 SQL 表达式、行过滤或数据转换
语义保证 CDC 与 S3 扫描模式为 exactly-once;S3 通知模式为 at-least-once at-least-once
所需权限 Load Load + Create(自动建表时)
典型适用场景 需要 SQL 表达式、类型转换或条件过滤的实时同步 整库或一组表的镜像复制,允许简单的表重命名或列裁剪

选型建议

  • 需要对数据做 SQL 加工,或 CDC 同步对精确一次语义有严格要求 → 选 SQL 映射同步
  • 希望 Doris 自动建表、一次配置同步一组表 → 选 自动建表同步
  • 数据源是 OceanBase → 目前仅支持 MySQL 兼容模式下的自动建表同步
  • 数据源是 S3 对象存储 → 只支持 SQL 映射同步(S3 TVF 方式)

S3 文件导入支持三种模式:默认的 ORDERED_LIST 按 key 字典序持续扫描;NOTIFICATION 通过 AWS S3 和独占 SQS 队列发现乱序到达的文件;ONE_TIME 分批导入文件后自动结束。通知模式端到端采用 at-least-once 语义,可能重复导入同一对象,不具备全部历史通知的持久化去重能力。选型、权限与使用限制见 S3 导入。

作业状态流转

Streaming Job 在运行过程中会在以下状态之间迁移,SQL 映射同步和自动建表同步遵循同一套状态机:

[图示请参阅官方原文]

状态说明

状态 含义
PENDING 作业已创建但尚未调度出子任务;等待下一次调度创建 StreamingTask
RUNNING 已派生子任务并在执行中,从源端读取增量数据并写入 Doris
FINISHED 源消费完成,作业终止。例如 S3 ONE_TIME 最后一批提交成功,或 CDC 仅全量同步完成;S3 ORDERED_LIST 和 NOTIFICATION 不会因暂时无数据而结束
PAUSED 子任务执行失败,作业自动暂停并记录 failReason;可通过 select * from jobs(...) 的 ErrorMsg 字段查看原因

自动恢复(autoResume)

作业进入 PAUSED 后,调度器会按指数退避策略定时尝试恢复,恢复时回到 PENDING 继续创建子任务。无需人工介入临时故障(网络抖动、上游短暂不可用等)会被自动消化。

检测到不支持的 Schema Change 时,作业以 [SCHEMA_CHANGE_UNSUPPORTED] 暂停,不会自动恢复。需先检查并准备兼容的目标表,再手动执行 RESUME JOB 确认接受本轮变更。

不同场景下应使用的命令:

  • 立即恢复或排查故障后手动启动:使用 RESUME JOB
  • 彻底停止不再调度:使用 PAUSE JOB(手动暂停不会被 autoResume 唤醒)或 DROP JOB

CDC 任务身份与失败处理(4.1.5 起)

自 4.1.5 版本起,Streaming CDC 的数据写入、表结构查询和 Schema Change 使用作业创建者的 Doris 身份,不再使用固定管理员身份。创建者需要目标表的 LOAD 权限;自动建表还需要 CREATE,同步结构变化需要相应 ALTER 权限及可查看目标表的权限。运行期间撤销权限也会影响后续任务,应按作业记录的创建者检查授权。

基于 cdc_stream() 的 Streaming INSERT 任务失败后不会进入普通任务的自动重试流程。应先查看 jobs() / tasks() 的错误信息、修复数据源或权限问题,再按作业状态恢复,避免假定失败任务会自动重放。

通用操作

查看导入状态

查询所有 Streaming 类型的 Insert Job:

select * from jobs("type"="insert") where ExecuteType = "STREAMING";

返回结果列说明:

结果列 说明
ID Job ID
NAME Job 名称
Definer Job 定义者
ExecuteType Job 调度的类型:ONE_TIME/RECURRING/STREAMING/MANUAL
RecurringStrategy 循环策略。普通的 Insert 会用到,ExecuteType=Streaming 时为空
Status Job 状态
ExecuteSql Job 的 Insert SQL 语句
CreateTime Job 创建时间
SucceedTaskCount 成功任务数量
FailedTaskCount 失败任务数量
CanceledTaskCount 取消任务数量
Comment Job 注释
Properties Job 的属性
CurrentOffset Job 当前处理完成的 Offset。只有 ExecuteType=Streaming 才有值
EndOffset Job 获取到数据源端最大的 EndOffset。只有 ExecuteType=Streaming 才有值
LoadStatistic Job 的统计信息
ErrorMsg Job 执行的错误信息
JobRuntimeMsg Job 运行时的一些提示信息
LagBytes 数据源端日志(MySQL / OceanBase Binlog、PostgreSQL WAL)的积压字节数,-1 表示当前不可用(例如 S3 数据源或全量快照阶段)
LastSourceEventTimestamp 已提交 Offset 中记录的数据源端最新事件时间戳(Unix 秒),为空表示不可用
LastTaskSuccessTime 最近一次 Task 成功完成的时间

查看 Task 状态

按 Job ID 查询其下所有子任务:

select * from tasks("type"="insert") where jobId='<job_id>';

返回结果列说明:

结果列 说明
TaskId 任务 ID
JobID JobID
JobName Job 名称
Label Task 导入的 Label
Status Task 的状态
ErrorMsg Task 失败信息
CreateTime Task 的创建时间
StartTime Task 的开始时间
FinishTime Task 的完成时间
LoadStatistic Task 的统计信息
User Task 的执行者
RunningOffset 当前 Task 同步的 Offset 信息。只有 Job.ExecuteType=Streaming 才有值

暂停导入作业

手动暂停指定作业(暂停后不会被 autoResume 自动唤醒):

PAUSE JOB WHERE jobname = <job_name>;

恢复导入作业

恢复处于 PAUSED 状态的作业:

RESUME JOB WHERE jobName = <job_name>;

删除导入作业

彻底删除指定作业,删除后不再调度:

DROP JOB WHERE jobName = <job_name>;

通用参数

FE 配置参数

参数 默认值 说明
max_streaming_job_num 1024 最大的 Streaming 作业数量
job_streaming_task_exec_thread_num 10 用于执行 StreamingTask 的线程数
max_streaming_task_show_count 100 StreamingTask 在内存中最多保留的 task 执行记录

Job 通用导入配置参数

以下参数通过 CREATE JOB ... PROPERTIES (...) 配置。除特别说明外,MySQL、PostgreSQL 和 OceanBase 的持续导入作业均可使用。

参数 默认值 说明
max_interval 10 当上游没有新增数据时,空闲的调度间隔,单位为秒。只接受不小于 1 的整数,不支持 10s 等单位后缀。
compute_group 当前会话或用户默认计算组 仅存算分离模式支持,用于指定作业运行的计算组。显式设置时不能为空,用户必须具有该计算组的 USAGE 权限;未设置且当前会话、用户均没有可用的默认计算组时,创建作业失败。
session.<variable_name> 对应会话变量的默认值 仅 TVF 模式支持。为 Job 的 INSERT 任务设置会话变量,例如 session.insert_max_filter_ratio。变量名和值必须是 Doris 支持的有效会话变量。

offset 作为 Job Property 时不用于设置 CDC 作业的初始位点;创建作业时应在 FROM MYSQL、FROM POSTGRES、FROM OCEANBASE 或 cdc_stream(...) 的数据源参数中设置。暂停 CDC 作业后,可以通过 ALTER JOB ... PROPERTIES ("offset" = '<json_offset>') 重置位点;MySQL 和 OceanBase 使用 {"file":"binlog.000001","pos":"154"},PostgreSQL 使用 {"lsn":"12345678"}。ALTER JOB 仅接受 JSON 形式的精确位点。

使用限制

同步范围、自动建表、一致性语义(exactly-once / at-least-once)已在能力对比中说明。本节只列出不支持的约束与行为。

主键表

仅支持同步带主键的上游表(两种同步方式均如此)。对应的 Doris 表为 Unique Key 表——自动建表同步下由 Doris 自动建成,SQL 映射同步下由你自己创建。无主键的表不支持。

Schema Change(DDL)

DDL 同步仅适用于自动建表方式同步,SQL 映射方式不同步 DDL。默认自动同步支持的新增列、删除列操作;检测到不支持的列或主键变更时暂停作业,需手动处理后恢复。自行维护目标表结构时,可通过 schema_change_behavior=ignore 关闭结构同步。

支持范围、开关配置和恢复步骤见 MySQL、PostgreSQL 和 OceanBase Schema Change 同步。

FAQ

MySQL 连接报错 Public Key Retrieval is not allowed

原因: 配置的 MySQL 用户使用 SHA256 密码认证方式,需要通过 TLS 等协议传输密码。

解决方案一: 在 JDBC URL 中添加 allowPublicKeyRetrieval=true 参数:

jdbc:mysql://127.0.0.1:3306?allowPublicKeyRetrieval=true

解决方案二: 将 MySQL 用户的认证方式改为 mysql_native_password:

ALTER USER 'username'@'%' IDENTIFIED WITH mysql_native_password BY 'password';
FLUSH PRIVILEGES;

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

资料来源与适用范围

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

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

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