DataX/tdengine20writer/doc/tdengine20writer-CN.md

DataX TDengineWriter

简体中文| English

1 快速介绍

TDengineWriter插件实现了写入数据到TDengine数据库目标表的功能。底层实现上，TDengineWriter通过JDBC连接TDengine，按照TDengine的SQL语法，执行insert语句/schemaless语句，将数据写入TDengine。

TDengineWriter可以作为数据迁移工具供DBA将其它数据库的数据导入到TDengine。

2 实现原理

TDengineWriter 通过 DataX 框架获取 Reader生成的协议数据，通过JDBC Driver连接TDengine，执行insert语句/schemaless语句，将数据写入TDengine。

在TDengine中，table可以分成超级表、子表、普通表三种类型，超级表和子表包括colum和tag，子表的tag列的值为固定值，普通表与关系型数据库中表的概念一致。（详细请参考：数据模型 ）

TDengineWriter支持向超级表、子表、普通表中写入数据，按照table的类型和column参数中是否包含tbname，使用以下方法进行写入：

1. table为超级表，column中指定tbname：使用自动建表的insert语句，使用tbname作为子表的名称。
2. table为超级表，column中未指定tbname：使用schemaless写入，TDengine会根据超级表名、tag值计算一个子表名称。
3. table为子表：使用insert语句写入，ignoreTagUnmatched参数为true时，忽略record中tag值与table的tag值不一致的数据。
4. table为普通表：使用insert语句写入。

3 功能说明

3.1 配置样例

配置一个写入TDengine的作业 先在TDengine上创建超级表：

create database if not exists test;
create table test.weather (ts timestamp, temperature int, humidity double) tags(is_normal bool, device_id binary(100), address nchar(100));

使用下面的Job配置，将数据写入TDengine：

{
  "job": {
    "content": [
      {
        "reader": {
          "name": "streamreader",
          "parameter": {
            "column": [
              {
                "type": "string",
                "value": "tb1"
              },
              {
                "type": "date",
                "value": "2022-02-20 12:00:01"
              },
              {
                "type": "long",
                "random": "0, 10"
              },
              {
                "type": "double",
                "random": "0, 10"
              },
              {
                "type": "bool",
                "random": "0, 50"
              },
              {
                "type": "bytes",
                "value": "abcABC123"
              },
              {
                "type": "string",
                "value": "北京朝阳望京"
              }
            ],
            "sliceRecordCount": 1
          }
        },
        "writer": {
          "name": "tdengine20writer",
          "parameter": {
            "username": "root",
            "password": "taosdata",
            "column": [
              "tbname",
              "ts",
              "temperature",
              "humidity",
              "is_normal",
              "device_id",
              "address"
            ],
            "connection": [
              {
                "table": [
                  "weather"
                ],
                "jdbcUrl": "jdbc:TAOS-RS://192.168.56.105:6041/test"
              }
            ],
            "batchSize": 100,
            "ignoreTagsUnmatched": true
          }
        }
      }
    ],
    "setting": {
      "speed": {
        "channel": 1
      }
    }
  }
}

3.2 参数说明

• jdbcUrl
  • 描述：数据源的JDBC连接信息，TDengine的JDBC信息请参考：Java连接器的使用
  • 必选：是
  • 默认值：无
• username
  • 描述：用户名
  • 必选：是
  • 默认值：无
• password
  • 描述：用户名的密码
  • 必选：是
  • 默认值：无
• table
  • 描述：表名的集合，table应该包含column参数中的所有列（tbname除外）。注意，column中的tbname会被当作TDengine中子表名使用。
  • 必选：是
  • 默认值：无
• column
  • 描述：字段名的集合，字段的顺序应该与record中column的
  • 必选：是
  • 默认值：无
• batchSize
  • 描述：每batchSize条record为一个batch进行写入
  • 必选：否
  • 默认值：1
• ignoreTagsUnmatched
  • 描述：当table为TDengine中的一张子表，table具有tag值。如果数据的tag值与table的tag值不想等，数据不写入到table中。
  • 必选：否
  • 默认值：false

3.3 类型转换

datax中的数据类型，可以映射到TDengine的数据类型

DataX 内部类型	TDengine 数据类型
INT	TINYINT, SMALLINT, INT
LONG	TIMESTAMP, TINYINT, SMALLINT, INT, BIGINT
DOUBLE	FLOAT, DOUBLE
STRING	TIMESTAMP, BINARY, NCHAR
BOOL	BOOL
DATE	TIMESTAMP
BYTES	BINARY

3.4 各数据源到TDengine的参考示例

下面是一些数据源到TDengine进行数据迁移的示例

数据迁移示例	配置的示例
TDengine到TDengine	超级表到超级表，指定tbname
TDengine到TDengine	超级表到超级表，不指定tbname
TDengine到TDengine	超级表到子表
TDengine到TDengine	普通表到普通表
RDBMS到TDengine	普通表到超级表，指定tbname
RDBMS到TDengine	普通表到超级表，不指定tbname
RDBMS到TDengine	普通表到子表
RDBMS到TDengine	普通表到普通表
OpenTSDB到TDengine	metric到普通表

4 性能报告

4.1 环境准备

4.1.1 数据特征

建表语句：

单行记录类似于：

4.1.2 机器参数

• 执行DataX的机器参数为:

  1. cpu:
  2. mem:
  3. net: 千兆双网卡
  4. disc: DataX 数据不落磁盘，不统计此项

• TDengine数据库机器参数为:

  1. cpu:
  2. mem:
  3. net: 千兆双网卡
  4. disc:

4.1.3 DataX jvm 参数

-Xms1024m -Xmx1024m -XX:+HeapDumpOnOutOfMemoryError

4.2 测试报告

4.2.1 单表测试报告

通道数	DataX速度(Rec/s)	DataX流量(MB/s)	DataX机器网卡流出流量(MB/s)	DataX机器运行负载	DB网卡进入流量(MB/s)	DB运行负载	DB TPS
1
4
8
16
32

说明：

4.2.4 性能测试小结

5 约束限制

FAQ

源表和目标表的字段顺序一致吗？

是的，TDengineWriter按照column中字段的顺序解析来自datax的数据。