# DataGen连接器
#### 概述
DataGen连接器用于按规则生成随机或序列测试数据，无需依赖任何外部数据源，是Flink内置的Source连接器。
表1连接器详情 
| **类别**         | **详情**     |
|:---|:---|
| 支持类型            | 源表        |
| 运行模式        | 批模式和流模式 |
| 数据格式          | 暂不适用       |
| API种类       | SQL       |
| 是否支持更新或删除结果表数据 | 不涉及     |
   
#### 适用场景
- **功能验证**：在无外部数据源时，快速验证Flink SQL作业逻辑。
- **性能压测**：通过控制数据生成速率和字段大小，模拟高吞吐量场景。
- **开发调试**：搭配Print/BlackHole连接器，构建零依赖的端到端调试链路。
 
#### 约束与限制
- 当同时设置number-of-rows和序列生成器的start/end时，任一条件先满足即停止生成。
 
#### 语法结构
```
CREATE TABLE {table_name} (
  {column_name} {column_type},
  ...
  WATERMARK FOR {time_column} AS {watermark_expression}
) WITH (
  'connector' = 'datagen',
  'rows-per-second' = '{生成速率}',
  'number-of-rows' = '{总行数}',
  'fields.{field_name}.kind' = 'random / sequence',
  'fields.{field_name}.min' = '{最小值}',
  'fields.{field_name}.max' = '{最大值}',
  'fields.{field_name}.length' = '{字符串/集合长度}',
  'fields.{field_name}.start' = '{起始值}',
  'fields.{field_name}.end' = '{结束值}'
  ...
);
```
![](https://support.huaweicloud.com/sqlref-flink-aidatalake/public_sys-resources/note_3.0-zh-cn.png)
参数中的 {field_name} 需替换为DDL中定义的实际字段名。例如字段名为user_id，则参数写为fields.user_id.kind。
#### WITH参数说明
**通用参数**
| 参数               | 是否必填 | 类型      | 默认值     | 取值范围       | 说明                                                                                                                                                              |
|:---|:---|:---|:---|:---|:---|
| connector       | 是    | String | 无      | datagen | 指定连接器类型为DataGen，必须固定填写 datagen。 这是Flink SQL识别连接器实现的唯一标识，填错会导致表注册失败。                            |
| rows-per-second | 否     | Long      | 10000 | 正整数     | 控制每秒生成数据的行数。 仅对Source生效。Flink运行时每个并行子任务独立按此速率向下游发射数据，实际总吞吐量 = 此值 × 并行度。                        |
| number-of-rows  | 否       | Long     | 无（无界流） | 正整数       | 控制生成数据的总行数，设置后Source在达到指定行数时自动停止，变为有界流。 与序列生成器的 end 值独立生效，任一条件先满足即停止。未设置时Source持续生成数据，不会自动停止。 |
   
**生成策略参数**
| 参数                     | 是否必填 | 类型   | 默认值  | 取值范围             | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|:---|:---|:---|:---|:---|:---|
| fields.{field_name}.kind | 否    | String | random | random / sequence | 指定字段的数据生成策略。 - random使用随机生成器，每次产生随机值。  - sequence使用序列生成器，从start递增到end。   未显式设置时所有字段默认使用随机生成器。同一个表中不同字段可以分别指定不同的生成策略。 |
   
**随机生成器参数（kind = random）**
| 参数                         | 是否必填 | 类型      | 默认值    | 取值范围 | 说明                                                                                                                                                                                                                |
|:---|:---|:---|:---|:---|:---|
| fields.{field_name}.min   | 否   | 与字段类型一致  | 见类型默认值表 | 数值    | 指定随机生成的最小值。 仅对数值类型（TINYINT/SMALLINT/INT/BIGINT/FLOAT/DOUBLE/DECIMAL）有效，对STRING、BOOLEAN等类型无效。Flink在生成随机值时以此值作为下界。                                      |
| fields.{field_name}.max     | 否   | 与字段类型一致 | 见类型默认值表 | 数值     | 指定随机生成的最大值。 仅对数值类型。min必须小于max，否则生成行为未定义。与min配合确定随机值的取值区间。                                                                                       |
| fields.{field_name}.length | 否    | Integer  | 100   | 正整数   | 控制随机生成的字符串长度（字符数）或集合元素个数。 适用于STRING/VARCHAR/CHAR/BYTES/BINARY/VARBINARY类型控制字符串/字节长度，适用于ARRAY/MAP/MULTISET类型控制集合元素个数。值越大单条记录占用内存越多，过大会影响吞吐量和GC性能。 |
| fields.{field_name}.max-past                             | 否                                | 与字段类型一致                                | 0                                    | 有效的持续时间，如30s、5min                    | 为TIMESTAMP类型生成"距当前时间不超过N的随机过去时间"。 只支持TIMESTAMP类型。                                                                                                                                                         |
| fields.{field_name}.null-rate                            | 否                                  | Float                               | 无                                    | 大于等于0且小于等于1                          | 控制该字段生成null值的概率。                                                                                                                                                                                                                                |
| **fields.{field_name}.var-len**                          | 否                               | BOOLEAN                              | false                               | true/false                         | 是控制VARCHAR/STRING/VARBINARY/BYTES生成长度是否可变的开关。                                                                                                                                                                                                    |
   
**随机生成器各类型默认范围：**
| 数据类型                       | 默认最小值                   | 默认最大值               | 可配置参数         |
|:---|:---|:---|:---|
| BOOLEAN                      | -                        | -                  | -              |
| TINYINT                    | -128                    | 127                 | min, max      |
| SMALLINT                   | -32768                 | 32767              | min, max      |
| INT                        | -2147483648              | 2147483647         | min, max         |
| BIGINT                      | -9223372036854775808     | 9223372036854775807 | min, max       |
| FLOAT                     | 最小正值                   | 最大正值                | min, max       |
| DOUBLE                     | 最小正值                    | 最大正值                 | min, max       |
| DECIMAL(p, s)             | 由精度决定                  | 由精度决定              | min, max        |
| STRING / VARCHAR / CHAR    | -                      | -                  | length          |
| BYTES / BINARY / VARBINARY | -                      | -                    | length          |
| DATE                       | 1970-01-01              | 当前日期                 | min, max        |
| TIME                         | 00:00:00                 | 23:59:59            | min, max       |
| TIMESTAMP                  | 1970-01-01 00:00:00.000  | 当前时间戳                | min, max         |
| TIMESTAMP_LTZ              | 1970-01-01 00:00:00.000 | 当前时间戳               | min, max        |
| ARRAY\<T\>                 | -                     | -                   | length（元素个数）   |
| MAP\<K, V\>               | -                        | -                   | length（键值对个数） |
| MULTISET\<T\>              | -                      | -                   | length（元素个数）  |
| ROW\<...\>                 | -                      | -                    | 各子字段独立配置       |
   
**序列生成器参数（kind = sequence）**
| 参数                        | 是否必填 | 类型      | 默认值 | 取值范围     | 说明                                                                                                                                            |
|:---|:---|:---|:---|:---|:---|
| fields.{field_name}.start | 是 | 与字段类型一致    | 无    | 数值类型范围   | 指定序列的起始值。 仅在使用序列生成器时需要设置。Flink从此值开始按步长1递增生成数据。                               |
| fields.{field_name}.end   | 是   | 与字段类型一致 | 无       | 数值类型范围 | 指定序列的结束值。 仅在使用序列生成器时需要设置。当序列达到此值后Source停止发送数据，变为有界流。在多并行度下，序列范围会在各子任务间均匀分配。 |
   
![](https://support.huaweicloud.com/sqlref-flink-aidatalake/public_sys-resources/note_3.0-zh-cn.png)
- **序列生成器支持的数据类型：** TINYINT、SMALLINT、INT、BIGINT、FLOAT、DOUBLE、DECIMAL、CHAR、VARCHAR、STRING。
- CHAR、VARCHAR、STRING是将整数转为STRING类型的数字字符串。
- BOOLEAN、DATE、TIMESTAMP等类型不支持序列生成器。
- 序列生成器总是在达到end值后变为有界流。
 
#### 使用示例
- **示例1：快速创建一个测试表，所有字段使用默认随机生成器，无需任何外部依赖。**
  ```
  -- 创建DataGen源表
  CREATE TABLE datagen_source (
    id BIGINT,
    data STRING,
    ts TIMESTAMP(3),
    WATERMARK FOR ts AS ts - INTERVAL '5' SECOND
  ) WITH (
    'connector' = 'datagen'
  );
  -- 创建Print结果表
  CREATE TABLE print_sink (
    id BIGINT,
    data STRING,
    ts TIMESTAMP(3)
  ) WITH (
    'connector' = 'print'
  );
  -- 提交作业
  INSERT INTO print_sink
  SELECT id, data, ts
  FROM datagen_source;
  ```
  
 
- **示例2：模拟用户行为数据，ID字段使用序列递增，其他字段控制生成范围。**
  ```
  -- 创建DataGen源表
  CREATE TABLE user_behavior_source (
    user_id INT,
    user_name STRING,
    score DOUBLE,
    age INT,
    event_time TIMESTAMP(3),
    WATERMARK FOR event_time AS event_time - INTERVAL '5' SECOND
  ) WITH (
    'connector' = 'datagen',
    'rows-per-second' = '500',
    'fields.user_id.kind' = 'sequence',
    'fields.user_id.start' = '1',
    'fields.user_id.end' = '1000',
    'fields.user_name.length' = '10',
    'fields.score.min' = '0.0',
    'fields.score.max' = '100.0',
    'fields.age.min' = '18',
    'fields.age.max' = '65'
  );
  -- 创建Print结果表
  CREATE TABLE print_sink (
    user_id INT,
    user_name STRING,
    score DOUBLE,
    age INT,
    event_time TIMESTAMP(3)
  ) WITH (
    'connector' = 'print',
    'print-identifier' = 'user-behavior'
  );
  -- 提交作业
  INSERT INTO print_sink
  SELECT user_id, user_name, score, age, event_time
  FROM user_behavior_source;
  ```
  

- **示例3：生成固定行数的测试数据，数据生成完毕后Source自动停止，适用于批处理测试。**
  ```
  -- 创建DataGen源表（有界流）
  CREATE TABLE datagen_bounded_source (
    id INT,
    data STRING
  ) WITH (
    'connector' = 'datagen',
    'rows-per-second' = '100',
    'number-of-rows' = '500',
    'fields.id.kind' = 'sequence',
    'fields.id.start' = '1',
    'fields.id.end' = '500'
  );
  -- 创建Print结果表
  CREATE TABLE print_sink (
    id INT,
    data STRING
  ) WITH (
    'connector' = 'print',
    'print-identifier' = 'bounded-output'
  );
  -- 提交作业
  INSERT INTO print_sink
  SELECT id, data
  FROM datagen_bounded_source;
  ```
  

- **示例4：生成包含ARRAY、MAP、ROW等复合类型字段的测试数据。**
  ```
  -- 创建DataGen源表（含复合类型字段）
  CREATE TABLE datagen_complex_source (
    id INT,
    tags ARRAY<STRING>,
    properties MAP<STRING, STRING>,
    address ROW<city STRING, street STRING>,
    payload BYTES
  ) WITH (
    'connector' = 'datagen',
    'rows-per-second' = '100',
    'fields.id.kind' = 'sequence',
    'fields.id.start' = '1',
    'fields.id.end' = '10000',
    'fields.tags.length' = '3',
    'fields.properties.length' = '5',
    'fields.payload.length' = '50'
  );
  -- 创建Print结果表
  CREATE TABLE print_sink (
    id INT,
    tags ARRAY<STRING>,
    properties MAP<STRING, STRING>,
    address ROW<city STRING, street STRING>,
    payload BYTES
  ) WITH (
    'connector' = 'print',
    'print-identifier' = 'complex-data'
  );
  -- 提交作业
  INSERT INTO print_sink
  SELECT id, tags, properties, address, payload
  FROM datagen_complex_source;
  ```
  

- **示例5：模拟高负载场景，控制数据量和速率进行性能压测。**
  ```
  -- 创建DataGen源表（高吞吐量压测配置）
  CREATE TABLE datagen_pressure_source (
    id BIGINT,
    payload STRING,
    event_time TIMESTAMP(3),
    WATERMARK FOR event_time AS event_time - INTERVAL '1' SECOND
  ) WITH (
    'connector' = 'datagen',
    'rows-per-second' = '100000',
    'number-of-rows' = '10000000',
    'fields.id.kind' = 'sequence',
    'fields.id.start' = '1',
    'fields.id.end' = '10000000',
    'fields.payload.length' = '1024'
  );
  -- 创建BlackHole结果表
  CREATE TABLE blackhole_sink (
    id BIGINT,
    payload STRING,
    event_time TIMESTAMP(3)
  ) WITH (
    'connector' = 'blackhole'
  );
  -- 提交作业：测试纯处理吞吐量
  INSERT INTO blackhole_sink
  SELECT id, payload, event_time
  FROM datagen_pressure_source;
  ```
  
 
