# Doris连接器
#### 概述
Doris连接器用于读写[表格存储服务CloudTable Doris](https://support.huaweicloud.com/productdesc-cloudtable/cloudtable_01_0002.html)数据库中的数据，支持通过Stream Load方式高效写入数据，并通过Doris FE的查询接口读取数据。
表1连接器详情 
| **类别**         | **详情**           |
|:---|:---|
| 支持类型           | 源表、维表和结果表      |
| 运行模式           | 流模式和批模式       |
| 数据格式          | 暂不支持          |
| 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的身份认证。                                                     |
   
**Source参数**
| 参数                                 | 是否必填 | 类型      | 默认值   | 取值范围          | 说明                                                                                                                                                                       |
|:---|:---|:---|:---|:---|:---|
| 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参数**
| 参数                               | 是否必填 | 类型       | 默认值  | 取值范围         | 说明                                                                                                                                                                                                         |
|:---|:---|:---|:---|:---|:---|
| 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参数**
| 参数                     | 是否必填 | 类型     | 默认值    | 取值范围    | 说明                                                                                                                                                                 |
|:---|:---|:---|:---|:---|:---|
| 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;
  ```
  
 
