通过 Query API 导出(推荐中小数据量)
适合场景:中小数据量的数据清洗、环境 / 项目迁移。
导出数据格式:标准的神策上报数据 JSON 格式
优缺点:
- 优点:接口兼容历史版本;curl 直接查询,使用简单。
- 缺点:
- 支持的数据量级有限,数据量过大容易接口超时;
- 导出用户数据占用磁盘多,导入慢
- 接口老架构设计,新架构需要额外的数据清洗
环境版本:任意版本(新老架构都支持)
注意:需要同时确保 $device_id_list 的 is_visible = 1,查看和修改参考:检查字段可见性
SeaTunnel 导出(数据量级较大,不支持云版客户)
适合场景:从神策导出数据量级较大的数据,仅支持 SDH 环境
导出数据格式:标准的神策 JSON 格式,可用于直接上报
优缺点:
- 优点:支持较大数据量级,相对 Query API 导出数据对导入更友好。
- 缺点:使用相对复杂,需要下载 seatunnel 包,手写任务 config 复杂。
依赖产品组件:SA3.0+ 套餐
请注意,该方式暂不支持云版客户导出数据。
准备 Hive JDBC 连接信息
seatunnel 依赖 SDH 提供的 Hive JDBC 接口读取数据。
如何获取 hive jdbc 连接信息:获取Hive Jdbc连接信息
可以获取到的的 hive jdbc 信息:
- jdbc url 格式: jdbc:hive2://127.0.0.1:8416
- user
- password
SeaTunnel 安装与配置
解压后进入
cd seatunnel/apache-seatunnel-2.3.9-sensorsdata
编写导出配置文件
导出用户表
env {
parallelism = 1 # 单线程执行(适合小数据量)
job.mode = "BATCH" # 批量模式
}
source {
jdbc {
url = "jdbc:hive2://xxxx:8416/{database}?useLocalSessionState=true&useUnicode=true&characterEncoding=UTF-8" # database = horizon_{project_name}_{project_id} , 比如 项目名:default, 项目id = 1 ;database = horizon_default_1
driver = "org.apache.hive.jdbc.HiveDriver"
user = "admin" # 神策用户名, 需要有读表的权限
password = "API-KEY" # 替换为实际密钥
query = "SELECT * FROM users" # 查用户表,字段较少可以列出具体字段
}
}
transform {
SensorsDataJson {
record_type = users # 数据类型标识
distinct_id_column = "$identity_distinct_id" # 数据唯一标识
identity_fields = [ # 身份映射规则
{ source = "$identity_distinct_id", target = "$identity_distinct_id" },
{ source = "$identity_anonymous_id", target = "$identity_anonymous_id" }
]
property_fields = [ # 属性映射规则
{ source = "age", target = "age", type = INT }
]
}
}
sink {
LocalFile {
path = "/data/sa_export/users/" # 本地存储路径(需提前创建)
file_format_type = "json"
sink_columns = ["json_content"]
}
}
在具体使用过程中,需要根据具体场景补全以下几个配置信息:
- url:根据 hive jdbc 信息补全
- user:根据 hive jdbc 信息获取
- password:根据 hive jdbc 信息获取
- identity_fields: 用户身份标识
- property_fields: 事件属性
- path:输出路径,需要提前创建
导出事件表
事件表数据量过大,建议按根据日期,批导出事件数据,每批数据百万级。
env {
# You can set engine configuration here
parallelism = 1
job.mode = "BATCH"
}
# 通过 JDBC 读出事件数据
source {
jdbc {
url = "jdbc:hive2://xxxx:8416/{database}?useLocalSessionState=true&useUnicode=true&characterEncoding=UTF-8" # database = horizon_{project_name}_{project_id} , 比如 项目名:default, 项目id = 1 ;database = horizon_default_1
driver = "org.apache.hive.jdbc.HiveDriver"
user = "admin"
password = "API-KEY"
query = "SELECT * FROM events WHERE `date` BETWEEN '2024-11-01' AND '2024-11-01'"
}
}
# 转换成神策可导入的 json 格式
transform {
SensorsDataJson {
time_free = true
record_type = events
schema = events
event_name = "${event}"
time_column = time
distinct_id_column = distinct_id
identity_fields = [
{ source = "$identity_distinct_id", target = "$identity_distinct_id" }
{ source = "$identity_anonymous_id", target = "$identity_anonymous_id" }
{ source = "$identity_login_id", target = "$identity_login_id" }
]
property_fields = [
{ source = "$is_first_day", target = "$is_first_day", type = BOOLEAN}
{ source = "$update_time", target = "$update_time", type = DECIMAL}
{ source = "$app_version", target = "$app_version", type = STRING}
{ source = "$screen_width", target = "$screen_width", type = DECIMAL}
{ source = "location_info", target = "location_info", type = STRING}
{ source = "previous_action", target = "previous_action", type = STRING}
{ source = "$model", target = "$model", type = STRING}
]
}
}
# 输出到本地文件
sink {
LocalFile {
path = "/home/sa_cluster/events/"
file_format_type = "text"
sink_columns = ["json_content"]
field_delimiter = "\t"
}
}
在具体使用过程中,需要根据具体场景补全以下几个配置信息:
- url:根据 hive jdbc 信息补全
- user:根据 hive jdbc 信息获取
- password:根据 hive jdbc 信息获取
- identity_fields: 用户身份标识
- property_fields: 事件属性
- path:输出路径,需要提前创建
property_fields 支持的数据类型
类型 | 说明 | 示例 |
---|---|---|
BOOLEAN |
布尔型,将转为神策的 Bool 类型 |
INT(1) => true DOUBLE(0.0) => false STRING("true") => true STRING("f") => false |
DECIMAL |
高精度型 基于 org.apache.commons.lang3.math.NumberUtils# createBigDecimal () 转换 |
|
INT |
数值型,将转为神策的 Number 类型 参见:神策官网帮助中心 - 数据格式 - 属性数据类型 |
INT(123) => 123.0 |
BIGINT |
LONG(123) => 123.0 | |
FLOAT |
FLOAT(123.1) => 123.1 | |
DOUBLE |
DOUBLE(123.1) => 123.1 | |
NUMBER |
|
|
LIST |
字符串数组,尽支持将字符串转为数组,以 '\n' 为分隔符 |
"abc\nbcd\ncde" => ["abc", "bcd", "cde"] |
LIST_COMMA |
字符串数组,尽支持将字符串转为数组,以 ',' 为分隔符 | "abc,bcd,cde" => ["abc", "bcd", "cde"] |
LIST_SEMICOLON |
字符串数组,尽支持将字符串转为数组,以 ';' 为分隔符 | "abc;bcd;cde" => ["abc", "bcd", "cde"] |
TIMESTAMP |
时间戳 解析字符串的内置 Formatter 包括:
可指定自定义 Formatter,格式如 "TIMESTAMP ${formatter}" |
STRING("2024-03-16 19:25:07") => 1710588307000L STRING("2024-03-16 19:25:07.123") => 1710588307123L
当 type = "TIMESTAMP yyyy-MM-dd'T'HH:mm:ssZ" 时,"2024-03-16T19:25:07+0100" => 1710613507000L |
DATE |
日期类型 | |
STRING |
字符串 |
Tips:
如果 identity 和 property 的列很多,一个一个写起来很麻烦。
可以从 元数据管理 → 用户表 / 事件表 中导出属性列表为一个 excel 文件,然后交给大模型生成 identity_fields 、property_fields
运行导出任务
单机模式执行( qps 大约 6000 ~ 10000)
# 进入 seatunnel 目录执行
./bin/seatunnel.sh --config ./config/user_export.conf -m local # 执行用户表导出
./bin/seatunnel.sh --config ./config/event_export.conf -m local # 执行事件表导出
任务日志存储在 seatunnel/logs/
目录,可通过 tail -f seatunnel.log
监控进度。
注意:
local 模式写文件时,会先写到 /tmp 目录下,确保 /tmp 所在磁盘空间足够。
常见问题
1、报错信息:The property key 'distinct_id' is invalid
distinct_id 不能作为 property_fields 映射,删除即可
SDH Open API 导出实体数据
适用场景:仅导出实体数据(不能导出事件数据), 用于数据备份或者导出到客户数仓。
导出的数据格式:
- 导出到一个神策的 impala 表
- 导出成一个文件(不是 json)并且通过 openApi 接口下载。
优缺点:
- 优点:直接调用 Open API ,依赖少,使用简单。
- 缺点:对神策集群资源消耗比较大;只能导出实体数据,无法导出事件数据。