菜单

数据导出

通过 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 安装与配置

1、下载 SeaTunnel
SeaTunnel (2.3.9.71)

解压后进入

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 包括:

  • "yyyy-MM-dd HH:mm:ss.SSS"

  • "yyyy-MM-dd HH:mm:ss"

  • "yyyy-MM-dd HH:mm"

  • "yyyy-MM-dd"

  • "yyyyMMdd_HHmmss"

  • "yyyyMMdd"

可指定自定义 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 ,依赖少,使用简单。
  • 缺点:对神策集群资源消耗比较大;只能导出实体数据,无法导出事件数据。

通过OpenApi 导出实体列表

上一个
导数
下一个
通过OpenApi 导出实体列表
最近修改: 2025-07-09