TcaplusDB导数工具

TcaplusDB导数工具（Importer），是基于Tcaplus C++ SDK开发的，用于从外部数据源（如MySQL、本地CSV文件、HDFS等）向TcaplusDB批量导入数据的工具。

数据导入的链路是：数据源（source）-> 数据转换（transform，可选项）-> 目标数据表（target）。

1. 使用限制

目前只支持向Generic表导入数据，暂不支持向List表导入数据。

目前不支持向包含复杂类型（如array，struct）字段的表导入数据。

导数工具暂时只支持在Linux系统上运行。

目前只支持一次向单表TcaplusDB表导入数据，如果要同时向多张表导入数据，或者提高并行度，可以启动多个独立的导数任务。

高版本的导数工具不能向低版本的服务端导入数据。

2. 使用场景

用于从外部数据源（如MySQL、本地CSV文件、HDFS等）向TcaplusDB批量导入数据的工具。

3. 使用方法

3.1. 下载导数工具

下载 导数工具 ，并解压到本地（本文档将以解压到/data/目录为例）。

3.2. 配置导数任务

导数任务配置文件为JSON格式，以从MySQL向TcaplusDB导数为例，在/data/目录下创建task1.conf文件（任务配置文件名可以任意指定，启动任务时，以参数的形式传入），文件内容参见下方：

{
  "source": {
    "type": "SQL_MySQL",
    "parameters": {
      "SQL": "SELECT * FROM test",
      "host": "x.x.x.x",
      "port": "3306",
      "database": "test",
      "username": "root",
      "password": "****",
      "readTimeout": "5",
      "charset": "utf8"
    }
  },
  "transform": {
    "type": "CUSTOM",
    "libraries": [
      "./libcustom_record_transformer.so"
    ],
    "parameters": {
    }
  },
  "target": {
    "dirs": [
      "tcp://x.x.x.x:9999"
    ],
    "appId": 1,
    "appPassword": "****************",
    "tableGroupId": 1,
    "table": "test",
    "tableType": "PB",
    "writeMode": "REPLACE",
    "writeRetryInterval": 1000,
    "writeRetryCount": 10
  },
  "config": {
    "badDataHandlePolicy": "IGNORE"
  }
}

任务配置文件的内容分为4个部分：

  • source部分：配置数据源；

  • transform部分：配置数据转换逻辑，这部分参数是选配的，如果没有数据转换的需求，可以不进行配置，如果需要自定义转换逻辑，参见后续的“自定义数据转换插件”章节的内容；

  • target部分：配置目标TcaplusDB表的相关信息；

  • config部分：设置导数任务的一些通用设置，如限速、导入失败的数据的处理方式等，这部分参数是选配的。

各个部分配置参数的详细介绍参见下表：

配置项名称 说明
source 【必配】数据源相关信息。
source.type 数据源类型，当前只支持SQL_MySQL一种，即将MySQL数据库的查询结构作为数据源。
source.parameters 数据源参数列表。
以Key-Value的形式提供，Key为参数名，Value为参数值，当前参数值只支持字符串。
例如选择SQL_MySQL数据源时，需要提供查询语句（SQL），数据库实例地址，端口，用户名，密码，数据库名称等必要信息。
不同类型的数据源，对应的参数与有些不同，详见工具发布中的各个样例任务配置文件。
transform 【选配】数据转换器相关信息。
transform.type 数据转换器类型。当前支持DEFAULT和CUSTOM两种。
DEFAULT：默认数据转换器是工具内置的转换器，未配置transform和transform类型为DEFAULT的时候，使用的都是默认数据转换器。默认数据转换器只能用于目标表的字段集是数据源字段集的子集，且字段值类型一致的场景，否则会报错。
CUSTOM：用户自定义数据转换器。可以根据需要，实现复杂的数据转换逻辑。自定义数据转换器继承自RecordTransformer基类，详见record_transformer.h和record_transformer_plugin.h文件中的相关说明。最终以so文件的形式提供。
transform.libraries 数据转换器程序文件（so文件）的路径。
当数据转换器类型为CUSTOM时，该参数为必填参数，用于指定数据转换器程序文件路径。
transform.parameters 数据转换器参数列表。
以Key-Value的形式提供，Key为参数名，Value为参数值，当前参数值只支持字符串。
参数列表将会作为数据换器的Initialize函数入参传入，用于初始化数据转换器。
target 【必配】目标表信息。
target.dirs 目标表所在集群的tcaplus dir节点地址列表。可从集群管理员处获取。
target.appId 目标表所属业务ID。可从集群管理员处获取。
target.appPassword 目标表所属业务密码。可从集群管理员处获取。
target.tableGroupId 目标表所属表格组ID（Zone ID）。可从集群管理员处获取。
target.table 目标表表名。
target.tableType 目标表类型。当前只有TDR和PB两种。
target.writeMode 目标表数据写入模式。当前支持INSERT和REPLACE两种模式：
INSERT：当相同Key值的数据存在时，本条数据导入失败；
REPLACE：当相同Key值的数据存在时，则覆盖原数据，否则插入新数据。
target.writeRetryInterval 目标表写入失败重试时间间隔，单位微秒，默认是1000微秒（1毫秒）。
target.writeRetryCount 目标表写入失败重试次数，默认是5次。
target.handleAsynCallbackInterval 处理异步回调的间隔，单位是写请求的次数。
例如间隔是10，表示每发送10次写请求，集中处理一次回调。
处理异步回调的频率过高，可能会因为空转，导致资源的浪费，适当地降低频率，可以提高整体QPS。
target.handleAsynCallbackBatch 每次可以处理的异步回调个数的上限。
单次处理异步回调的个数过多，导致处理时间过长，会导致写请求大量积压，因为当前发送写请求和处理回调的是同一个线程。
config 【选配】导数任务其它配置。
config.badDataHandlePolicy 导入失败的数据处理策略。当前只支持IGNORE和OUTPUT_TO_FILE两种策略。
IGNORE表示直接丢弃导入失败的数据，OUTPUT_TO_FILE表示将导入失败的数据输出的指定文件，两种策略都不会中断导数任务执行。
当指定使用OUTPUT_TO_FILE策略时，必须指定config.badDataOutputFilePath参数值。
config.badDataOutputFilePath 存放导入失败的数据的文件。输出的数据文件为CSV格式，如果需要将导入失败的数据重新导入，则可以重新配置一个从本地CSV文件向TcaplusDB导数的任务，再执行导入。
config.QPSLimit 导入速度（QPS）限制，0表示不限制，默认不限制。

3.3. 执行导数任务

运行以下命令，启动导数任务，等待任务执行完毕。

cd /data/TcaplusImporterX.XX.X.XXXXXX.x86_64_release_XXXXXXXX/release/x86_64/
./tcaplus_data_importer /data/task1.conf

注意：如果任务配置文件名不是/data/task1.conf，则将命令参数修改为对应的文件名即可。路径中的X根据实际版本号填写。

3.4. 查看进度日志和运行日志

默认情况下，导数的进度日志和运行日志都是输出在当前目录下，其中monitor.log为进度日志（主要用于查看导入进度和成功率等），run.log和run_NetThread_X.log为运行日志（主要用于问题定位）。

默认日志输出级别是INFO，如果需要修改日志输出级别，需要将/data/TcaplusImporterX.XX.X.XXXXXX.x86_64_release_XXXXXXXX/release/x86_64/example/tlogconf.xml文件复制到与工具同级目录下，并将其中的PriorityLow参数由INFO修改为目标级别（如DEBUG）。

注意：日志输出配置文件名必须固定为tlogconf.xml

3.5. 自定义数据转换插件

用户可以根据需要自定义数据转换器，实现复杂的数据转换逻辑。

自定义数据转换器继承自RecordTransformer基类，详见record_transformer.h和record_transformer_plugin.h文件中的相关说明。最终以so文件的形式提供。

详见 /data/TcaplusImporterX.XX.X.XXXXXX.x86_64_release_XXXXXXXX/release/x86_64/example/extension/README.md 中的说明（路径中的X根据实际版本号填写）。

results matching ""

    No results matching ""