Doris连接器
概述
Doris连接器用于读写表格存储服务CloudTable Doris数据库中的数据,支持通过Stream Load方式高效写入数据,并通过Doris FE的查询接口读取数据。
| 类别 | 详情 |
|---|---|
| 支持类型 | 源表、维表和结果表 |
| 运行模式 | 流模式和批模式 |
| 数据格式 | 暂不支持 |
| API种类 | SQL,Datastream |
| 是否支持更新或删除结果表数据 | 是 |
适用场景
- 实时数据写入:将Flink处理后的实时数据写入Doris OLAP表,支撑实时报表查询。
- 数据同步:将Kafka等数据源的数据同步到Doris,实现实时数仓建设。
- OLAP分析:从Doris读取维度数据,与实时流进行关联分析。
- ETL输出:将Flink ETL处理结果落库到Doris,供BI工具直接查询。
约束与限制
- Exactly-Once写入需开启Flink Checkpoint,并设置唯一的sink.label-prefix。
- 写入Doris时,字段类型需与Doris表列类型兼容。
- CloudTable Doris需要为3.x及以上版本。
语法结构
Source
CREATE TABLE {table_name} (
{column_name} {column_type},
...
) WITH (
'connector' = 'doris',
'fenodes' = '{fe_host:http_port}',
'table.identifier' = '{database}.{table}',
'username' = '{username}',
'password' = '{password}'
); Sink
CREATE TABLE {table_name} (
{column_name} {column_type},
...
) WITH (
'connector' = 'doris',
'fenodes' = '{fe_host:http_port}',
'table.identifier' = '{database}.{table}',
'username' = '{username}',
'password' = '{password}',
'sink.label-prefix' = '{label_prefix}',
'sink.properties.format' = '{data_format}',
'sink.enable-delete' = '{enable_delete}'
); WITH参数说明
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| connector | 是 | String | 无 | doris | 标识连接器类型为Doris连接器。 必须填写且值固定为doris。Flink运行时根据此值加载Doris连接器工厂类,将表声明为Doris数据源或输出表。 |
| fenodes | 是 | String | 无 | host:port列表 | 指定Doris FE节点HTTP地址,多个地址以逗号分隔。 Source和Sink均必填。Flink运行时使用此地址连接Doris FE获取查询计划或提交Stream Load请求,建议配置多个FE地址以实现高可用故障切换。 |
| table.identifier | 是 | String | 无 | database.table | 指定Doris表标识,格式为数据库名.表名。 Source和Sink均必填。Flink运行时根据此标识定位Doris中的目标表,影响数据的读取和写入目标。 |
| username | 是 | String | 无 | 有效的用户名 | 指定Doris数据库用户名。 Source和Sink均必填。Flink运行时使用此用户名进行Doris的身份认证,用户需具有对应表的读写权限。 |
| password | 是 | String | 无 | 有效的密码 | 指定Doris数据库密码。 Source和Sink均必填。Flink运行时使用此密码配合用户名完成Doris的身份认证。 |
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| doris.read.field | 否 | String | 无 | 列名列表 | 指定读取的列,多个列以逗号分隔。 未指定时读取所有列。Flink运行时将此列列表下推到Doris查询SQL的SELECT子句中,减少不必要的数据传输,提高读取效率。 |
| doris.filter.query | 否 | String | 无 | SQL过滤条件 | 指定读取时的过滤条件,下推到Doris执行。 Flink运行时将此条件追加到Doris查询SQL的WHERE子句中,在Doris侧完成数据过滤,减少传输到Flink的数据量。 |
| doris.request.tablet.size | 否 | Integer | 2 | 正整数 | 设置每个Doris BE分区并行读取的Tablet数。 Flink运行时根据此值将Tablet分配给多个读取子任务并行执行,增大此值可提高读取并行度但增加Doris侧负载。 |
| doris.request.connect.timeout.ms | 否 | Integer | 30000 | 正整数 | 设置连接Doris BE的超时时间(毫秒)。 Flink运行时在建立与Doris BE的连接时,超过此时间未建立成功则抛出超时异常,网络不稳定时可适当增大。 |
| doris.request.read.timeout.ms | 否 | Integer | 30000 | 正整数 | 设置读取Doris BE数据的超时时间(毫秒)。 Flink运行时在从Doris BE读取数据时,超过此时间未收到响应则抛出超时异常,大查询场景可适当增大。 |
| doris.request.query.timeout.s | 否 | Integer | 3600 | 正整数 | 设置查询Doris的超时时间(秒)。 Flink运行时在提交查询到Doris后,超过此时间未完成则取消查询,大表全量读取场景可适当增大。 |
| doris.request.retries | 否 | Integer | 3 | 正整数 | 设置请求Doris的重试次数。 Flink运行时在请求失败时自动重试,重试次数耗尽后抛出异常,网络不稳定时可适当增大。 |
| doris.deserialize.arrow.async | 否 | Boolean | false | true / false | 控制是否异步将Arrow数据反序列化。 默认为false即同步反序列化。设置为true时Flink运行时使用独立线程池异步执行Arrow到RowData的转换,可提高读取吞吐但增加内存消耗。 |
| doris.deserialize.queue.size | 否 | Integer | 64 | 正整数 | 设置异步反序列化队列大小。 仅在doris.deserialize.arrow.async为true时生效。Flink运行时在异步反序列化模式下使用此队列缓冲已反序列化的数据,队列满时反序列化线程阻塞等待。 |
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| sink.label-prefix | 否 | String | 无 | 有效的标签前缀 | 指定Stream Load标签前缀。 建议每个作业设置唯一前缀,用于确保Exactly-Once语义。Flink运行时使用标签前缀+唯一标识生成Stream Load的label,Doris通过label去重保证同一批数据不会重复写入。 |
| sink.properties.format | 否 | String | json | json / csv | 指定Stream Load数据传输格式。 默认为json。Flink运行时根据此格式将Flink行数据序列化为对应格式后发送给Doris Stream Load接口,json格式兼容性好,csv格式传输量更小。 |
| sink.properties.max_filter_ratio | 否 | String | 0 | 0~1 | 指定Stream Load最大过滤比率。 超过此比率的异常数据将导致整个写入批次失败。Flink运行时在Stream Load完成后检查过滤比率,超限则抛出异常触发重试,设置为0表示不允许任何过滤错误。 |
| sink.enable-delete | 否 | Boolean | true | true / false | 控制是否启用删除操作。 默认为false。启用后Flink的retract记录(-U、-D)将被转换为Doris的DELETE操作。Flink运行时在序列化记录时,对retract记录生成Doris的删除标记而非普通写入,仅Doris Unique Key模型表支持删除。 |
| sink.buffer-size | 否 | MemorySize | 1mb | 有效的内存大小,如128mb、256mb | 设置Sink缓冲区大小。 Flink运行时在内存中缓冲写入数据,缓冲区满后触发Stream Load提交,增大此值可减少提交次数提高吞吐但增加内存占用和数据延迟。 |
| sink.buffer.count | 否 | Integer | 3 | 正整数 | 设置Sink缓冲区数量。 Flink运行时维护多个缓冲区轮流使用,当一个缓冲区正在提交时其他缓冲区继续接收数据,增大此值可提高写入并发度但增加内存占用。 |
| sink.max-retries | 否 | Integer | 1 | 正整数 | 设置写入失败的最大重试次数。 Flink运行时在Stream Load提交失败时自动重试,重试次数耗尽后作业失败,网络或Doris不稳定时可适当增大。 |
| sink.check-interval | 否 | Duration | 0s | 有效的持续时间,如30s、5min | 设置检查缓冲区是否需要刷新的间隔(毫秒)。 Flink运行时启动后台线程按此间隔检查缓冲区状态,满足刷新条件时触发Stream Load提交,间隔越短数据延迟越低但检查开销越大。 |
| 参数 | 是否必填 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|---|
| lookup.cache.max-rows | 否 | Long | -1 | 正整数 | 设置维表查询缓存的最大行数。 仅对Lookup JOIN场景生效。Flink运行时在内存中维护LRU缓存,缓存行数达到此上限后淘汰最久未访问的记录,增大此值可提高查询命中率但增加内存消耗。 |
| lookup.cache.ttl | 否 | Duration | 10s | 正整数+时间单位 | 设置维表查询缓存的TTL(存活时间)。 仅对Lookup JOIN场景生效。Flink运行时在缓存记录超过TTL后将其失效,下次访问时重新从Doris查询加载,用于平衡数据时效性与查询性能。 |
| lookup.max-retries | 否 | Integer | 1 | 正整数 | 设置维表查询的最大重试次数。 Flink运行时在查询Doris失败时自动重试,重试次数耗尽后抛出异常,Doris负载较高时可适当增大。 |
| jdbc-url | 是 | String | 无 | 无 | 连接Doris的MySQL协议地址。 |
使用示例
- 示例1:从Doris表中批量读取数据。
-- 创建Doris源表 CREATE TABLE doris_source ( user_id BIGINT, user_name STRING, age INT, city STRING ) WITH ( 'connector' = 'doris', 'fenodes' = 'doris-fe:8030', 'table.identifier' = 'user_db.user_info', 'username' = 'root', 'password' = 'xxxx' ); -- 创建Print结果表 CREATE TABLE print_sink ( user_id BIGINT, user_name STRING, age INT, city STRING ) WITH ( 'connector' = 'print', 'print-identifier' = 'doris-data' ); -- 提交作业 INSERT INTO print_sink SELECT user_id, user_name, age, city FROM doris_source;
- 示例2:将数据以JSON格式写入Doris表。
-- 创建DataGen源表 CREATE TABLE datagen_source ( user_id BIGINT, event_type STRING, event_time TIMESTAMP(3), event_count BIGINT ) WITH ( 'connector' = 'datagen', 'rows-per-second' = '100', 'fields.user_id.kind' = 'sequence', 'fields.user_id.start' = '1', 'fields.user_id.end' = '100000', 'fields.event_count.kind' = 'sequence', 'fields.event_count.start' = '1', 'fields.event_count.end' = '100' ); -- 创建Doris结果表 CREATE TABLE doris_sink ( user_id BIGINT, event_type STRING, event_time TIMESTAMP(3), event_count BIGINT ) WITH ( 'connector' = 'doris', 'fenodes' = 'doris-fe:8030', 'table.identifier' = 'analytics_db.user_events', 'username' = 'root', 'password' = 'xxxx', 'sink.label-prefix' = 'flink-user-events', 'sink.properties.format' = 'json', 'sink.max-retries' = '3' ); -- 提交作业 INSERT INTO doris_sink SELECT user_id, event_type, event_time, event_count FROM datagen_source;
- 示例3:从Kafka消费实时事件数据,聚合计算后写入Doris,支撑实时OLAP查询。
-- Kafka源表 CREATE TABLE kafka_event_source ( user_id BIGINT, event_type STRING, page_url STRING, event_time TIMESTAMP(3), WATERMARK FOR event_time AS event_time - INTERVAL '5' SECOND ) WITH ( 'connector' = 'kafka', 'topic' = 'user-events', 'properties.bootstrap.servers' = 'kafka-broker:9092', 'properties.group.id' = 'doris-writer', 'scan.startup.mode' = 'latest-offset', 'format' = 'json', 'json.ignore-parse-errors' = 'true' ); -- Doris结果表 CREATE TABLE doris_event_sink ( window_start TIMESTAMP(3), window_end TIMESTAMP(3), event_type STRING, event_count BIGINT, unique_users BIGINT ) WITH ( 'connector' = 'doris', 'fenodes' = 'doris-fe:8030', 'table.identifier' = 'analytics_db.event_stats', 'username' = 'root', 'password' = 'xxxx', 'sink.label-prefix' = 'flink-event-stats', 'sink.properties.format' = 'json', 'sink.enable-delete' = 'false' ); -- 5分钟窗口聚合写入 INSERT INTO doris_event_sink SELECT window_start AS window_start, window_end AS window_end, event_type, COUNT(*) AS event_count, COUNT(DISTINCT user_id) AS unique_users FROM TABLE( HOP(TABLE kafka_event_source, DESCRIPTOR(event_time), INTERVAL '1' MINUTE, INTERVAL '5' MINUTE) ) GROUP BY window_start, window_end, event_type;
- 示例4:将Doris表作为维表,通过Lookup JOIN关联Kafka实时流。
-- Doris维表 CREATE TABLE doris_dim ( user_id BIGINT, user_name STRING, city STRING, PRIMARY KEY (user_id) NOT ENFORCED ) WITH ( 'connector' = 'doris', 'fenodes' = 'doris-fe:8030', 'table.identifier' = 'user_db.user_info', 'jdbc-url' = 'jdbc:mysql://FE实例IP地址:FE查询连接端口', 'username' = 'root', 'password' = 'xxxx', 'lookup.cache.max-rows' = '10000', 'lookup.cache.ttl' = '10min' ); -- Kafka实时流 CREATE TABLE kafka_realtime_source ( user_id BIGINT, event_type STRING, event_time TIMESTAMP(3), proctime AS PROCTIME() ) WITH ( 'connector' = 'kafka', 'topic' = 'events', 'properties.bootstrap.servers' = 'kafka-broker:9092', 'properties.group.id' = 'doris-lookup', 'scan.startup.mode' = 'earliest-offset', 'format' = 'json' ); -- 创建Print结果表 CREATE TABLE print_sink ( user_id BIGINT, user_name STRING, city STRING, event_type STRING, event_time TIMESTAMP(3) ) WITH ( 'connector' = 'print', 'print-identifier' = 'doris-lookup-result' ); -- 提交作业:Lookup JOIN后输出 INSERT INTO print_sink SELECT e.user_id, d.user_name, d.city, e.event_type, e.event_time FROM kafka_realtime_source e LEFT JOIN doris_dim FOR SYSTEM_TIME AS OF e.proctime AS d ON e.user_id = d.user_id;
- 示例5:启用Doris Sink的删除能力,将Flink的回撤记录转换为Doris删除操作。
-- 创建DataGen源表 CREATE TABLE datagen_source ( user_id BIGINT, user_name STRING, city STRING ) WITH ( 'connector' = 'datagen', 'rows-per-second' = '100', 'fields.user_id.kind' = 'sequence', 'fields.user_id.start' = '1', 'fields.user_id.end' = '10000', 'fields.user_name.length' = '10' ); -- 创建Doris Upsert结果表 CREATE TABLE doris_upsert_sink ( user_id BIGINT, user_name STRING, city STRING, PRIMARY KEY (user_id) NOT ENFORCED ) WITH ( 'connector' = 'doris', 'fenodes' = 'doris-fe:8030', 'table.identifier' = 'user_db.user_info', 'username' = 'root', 'password' = 'xxxx', 'sink.label-prefix' = 'flink-user-upsert', 'sink.properties.format' = 'json', 'sink.enable-delete' = 'true' ); -- 提交作业 INSERT INTO doris_upsert_sink SELECT user_id, user_name, city FROM datagen_source;