# 数据回溯功能

# 一、概述

数据回溯功能是通过 SQL 语句对 TA 数据库内的数据进行查询后，再将返回结果录入到 TA 数据库中，以生成新事件或新的用户属性的功能。

# 二、使用说明

# 2.1 命令说明

登录到任意一台 TA 服务器，执行su - ta命令，切换至 ta 用户

执行ta-tool user_event_import -conf读取配置文件，命令如下：

ta-tool user_event_import -conf <config文件> [--date 数据日期]

# 2.2 命令参数说明

# 2.2.1 -conf

必传，参数为对应数据回溯任务配置文件的路径，支持通配符的方式，例如：/data/config/*或者 ./config/*.json

# 2.2.1 --date

可选，参数表示数据日期，时间宏会基于此基准时间进行替换，可不传，不传则默认取当前日期，格式为YYYY-MM-DD，时间宏的具体使用方法，可参考时间宏使用方法

# 2.2.3 示例

ta-tool user_event_import -conf /data/home/ta/import_configs/*.json

参数为配置文件的完整路径，支持使用通配符读取多个配置文件

# 2.3 配置文件说明

# 2.3.1 配置文件样例如下：

数据回溯功能的核心，是包含查询语句与配置参数的配置文件。一个配置文件，对应了一个数据回溯任务，一条回溯事件的配置文件如下：

{
  "event_desc": {
    "ltv_event": "用户生命周期"
  },
  "appid": "APPID",
  "type": "event",
  "property_desc": {
    "register_date": "注册日期",
    "date_prop": "LTV日数"
  },
  "sql": "SELECT 'thinkinggame' \"#account_id\",'ltv_event' \"#event_name\",register_date \"#time\",register_date,ltv,date_prop FROM  (SELECT recharge_money ltv,register_date,CASE date_trunc('day', cast(register_date AS TIMESTAMP)) WHEN CURRENT_DATE - interval '1' DAY THEN '次日' WHEN CURRENT_DATE - interval '2' DAY THEN '三日' WHEN CURRENT_DATE - interval '6' DAY THEN '七日' WHEN CURRENT_DATE - interval '13' DAY THEN '十四日' WHEN CURRENT_DATE - interval '29' DAY THEN '三十日' ELSE NULL END date_prop FROM (SELECT sum(recharge_money) recharge_money ,register_date FROM (SELECT \"#user_id\" ,sum(recharge_value) recharge_money ,\"$part_date\" recharge_date FROM v_event_0 WHERE \"$part_event\" = 'recharge' AND \"$part_date\" > '2018-06-30' AND \"$part_date\" < '2018-07-30' GROUP BY \"#user_id\" , \"$part_date\") a LEFT JOIN (SELECT \"#user_id\" , \"$part_date\" register_date FROM v_event_0 WHERE \"$part_event\" = 'player_register' AND \"$part_date\" > '2018-06-30' AND \"$part_date\" < '2018-07-30') b ON a.\"#user_id\" = b.\"#user_id\" WHERE b.\"#user_id\" IS NOT NULL AND recharge_date >= register_date GROUP BY register_date) c) d WHERE date_prop IS NOT NULL"
}

注意

需要回溯 List 类型时,因为底层存储列表类型为字符串用\t 分隔，所以需要做如下处理：

split("arrayColumn", chr(0009)) as arrayColumn

# 2.3.2 配置参数说明

每个配置文件都是以 JSON 来表示的，以下是每个元素的意义：

event_desc：
- 描述: 可选配置，JSON 对象，用以设置新建事件的显示名
- key: 事件名
- value: 显示名
appid：
- 描述：必须配置，写入查询结果的目标项目的 APPID
type：
- 描述：必须配置，写入目标项目的event表还是user表
- 可取值：event、user
property_desc：
- 描述：可选配置，JSON 对象，用以设置属性名的显示名
- key: 属性名
- value: 显示名
sql：
- 描述：必须配置，字符串，为查询的语句，请注意，返回结果的列名，将会决定该列数据的具体含义，其中必须要有以下：
  - 必要列名 1：#account_id 或 #distinct_id ，至少要有其中一个，对应触发用户的账号 ID 与匿名 ID，如果生成的事件不是由个人触发的，比如上述例子中的 LTV，建议使用 ID 规则外的定值表示，比如"system"，"admin"等
  - 必要列名 2：#event_name，事件名称，建议设置定值
  - 必要列名 3：#time，事件发生的时间，格式必须是yyyy-MM-dd HH:mm:ss或yyyy-MM-dd HH:mm:ss.SSS

除了上述列名，其余列的数据将会作为该事件的属性，列名即为属性名

除了回溯事件外，也支持通过查询结果生成新的用户属性或覆盖已有用户属性，配置文件如下所示：

{
  "appid": "8d1820678a064397bbfcc9732f352e75",
  "type": "user",
  "property_desc": {
    "user_level": "用户等级",
    "coin_num": "金币存量"
  },
  "sql": "select \"#account_id\",localtimestamp \"#time\",user_level,coin_num from v_user_0"
}

与回溯事件类似，其配置文件也是以 JSON 来表示，与回溯事件的配置文件有如下不同：

不需要event_desc
type的取值为"user"
sql 中的必要列名不需要#event_name，只需要以下两条：
- 必要列名 1：#account_id 或 #distinct_id，至少要有其中一个
- 必要列名 2：#time，表示时间

# 2.4 时间宏使用方法

在数据回溯任务配置文件内部可以使用时间宏替换时间参数，在执行数据回溯命令时，ta-tool 工具会以--date为基准，基于时间宏的参数做时间的偏移计算，并替换掉配置文件中的时间宏，支持的时间宏格式：@[{yyyyMMdd}], @[{yyyyMMdd}-{nday}], @[{yyyyMMdd}+{nday}]等等

yyyyMMdd可以替换成任意可以被 Java dateFormat解析的日期格式，例如：yyyy-MM-dd HH:mm:ss.SSS, yyyyMMddHH000000
n 可以是任意整数，表示时间的偏移值
day 表示时间的偏移单位，可以取如下几种: day, hour, minute, week, month
举例：假设当前时间为2018-07-01 15:13:23.234
- @[{yyyyMMdd}] 替换为 20180701
- @[{yyyy-MM-dd}-{1day}] 替换为 2018-06-31
- @[{yyyyMMddHH}+{2hour}] 替换为 2018070117
- @[{yyyyMMddHHmm00}-{10minute}] 替换为 20180701150300

← 数据去重工具自定义表数据导入功能 →