标签数据导出

导出概述（必读）

神策标签系统的数据导出，与神策分析基本一致，可参考神策分析 - 数据导出。其中标签最常见的导出方式有：

#	访问方式	场景	用于页面展示	< 5k 行导出	5k - 10W 行导出	> 10W 的无限制行导出
1	查询 API（不分页）	小量导出。	不建议使用	支持	支持	不建议使用
2	查询 API（分页）	不适合导出，仅做 Web 页面展示使用。	支持	支持	不建议使用
3	JDBC（包括 impala-shell）+ HDFS	任意数据量导出，使用 SQL 建 HDFS 表，并访问 HDFS 获得数据。	不建议使用	支持	支持	支持
4	HUE SQL 查询	SQL 分析、验证 SQL 正确性、数据导出	支持	支持	支持	不建议使用

使用 JDBC + HDFS 查询或导出标签

本章节为参考 https://www.sensorsdata.cn/manual/jdbc.html 编写，原文中包含更多内容如 ”和 Spark 集成“。

获取 JDBC 地址

登录任意的神策服务器

切换至 sa_cluster 账户

su - sa_cluster

使用以下命令获取地址

spadmin config get client -m impala

例如输出是

  {
      "hive_url_list": [
          "jdbc:hive2://192.168.1.2:21050/rawdata;auth=noSasl",
          "jdbc:hive2://192.168.1.3:21050/rawdata;auth=noSasl",
      ],
      "hive_user": "sa_cluster"
  }

其中，hive_url_list 中的任意一个地址都可用于连接。

如果使用代码访问，我们建议使用 1.1.0 版本的 Hive JDBC Driver 来进行访问，Maven 的依赖定义如下：

    
        org.apache.hive
        hive-jdbc
        1.1.0

另外，Impala 也支持使用官方的Impala Jdbc Drvier进行访问，不过为了兼容神策分析系统，请使用的时候务必开启 Native SQL 的选项，例如：

jdbc:impala://192.168.1.1:21050/rawdata;UseNativeQuery=1

注意：使用不同 Driver 访问时使用的 JDBC URI 也会有所不同。

使用 impala-shell 进行查询

可以直接使用 impala-shell 工具进行查询。通常有两种使用方式：

直接登录任意的神策服务器，运行 impala-shell 命令即可。
使用任意 2.6.0 以上的 impala-shell 客户端，连接到上面 hive_url_list 中的地址（无需指定端口）。

简单查询及 SA 注释

为了区分查询神策的数据与一般的 Impala 数据，需要在 SQL 中使用特殊的注解来进行标识，需要在 SQL 中使用特殊的注解来进行标识，例如查询默认项目的 events 数据：

SELECT * FROM events WHERE `date` = CURRENT_DATE() LIMIT 10 /*SA*/;

类似的，如果想看 events 表有哪些字段，可以使用：

DESC events /*SA*/;

如果不是查询默认项目，则需要指定项目名称，例如：

SELECT * FROM users LIMIT 10 /*SA(test_project)*/;

在 HUE 中不加 SA 注释地验证 SQL 正确性

在 HUE （既 ”自定义查询“）中可以不加注释地查询神策的数据，可用于快速验证 SQL 编写是否正确。

在 HUE 中，还可以方便地看到 users 表、user_tag_* 表、user_group_* 表的字段结构。

验证后，可再加适当注释再通过 JDBC、Impala-shell 等方式执行。

更多内容，可参考 ”在 HUE 中查询标签“ 一节。

获得标签英文名

在 SQL 中查询标签，需要先获取标签英文名字，方法如下图：

查询标签最新版本

假设 ”年龄“ 标签，英文名是 age，查询默认项目的标签 age 的最新 base_time 的数据：

SELECT first_id, age FROM users WHERE age IS NOT NULL LIMIT 10 /*SA*/;

观察 SQL 可见：

其中的 /*SA*/ 表示当前 SQL 是一个发给神策系统的查询；
且标签 age 在 SQL 中，是作为 users 表的一个字段进行查询的；
users 表的 age 字段，是 age 标签的最新 base_time 所代表的版本。

查询标签历史版本

历史版本无法从 users 表中查到，我们需要查询 user_tag_*（标签）和 user_group_* （用户群）表。

下面以 ”是否为红包用户“ 标签为例，其英文名是 is_hb_user。

SELECT base_time, COUNT(1) FROM user_tag_is_hb_user GROUP BY base_time /*SA*/;

结合 HDFS 进行数据导出

如果想把神策的数据导出成文本格式，用于备份或者其它用途，那可以使用以下方案：

一、创建一个文本格式的数据表，把待导出的数据插入此表。

我们可以让一个 SQL 的一部分使用神策的查询，其它部分使用正常的 Impala 查询如下：

CREATE TABLE default.age_export AS 
/*SA_BEGIN(test_project)*/ SELECT id, first_id, age FROM users WHERE age IS NOT NULL LIMIT 10 /*SA_END*/

注意： 普通 Impala/Hive 表不支持带 $ 的字段，因此如果导出这类字段需要使用 AS 重命名。

二、获取该数据表的 HDFS 路径：

SHOW TABLE STATS default.age_export

其中输出的 Location 列即是导出文件所在的 HDFS 目录，例如:

hdfs://data01:8020/user/hive/warehouse/age_export/

可以使用 hadoop 命令将 HDFS 文件取到本地：

hadoop fs -get hdfs://data01:8020/user/hive/warehouse/age_export/

上述目录里的文件是以 Hive 默认分隔符（即 \001）进行列分隔的文本文件。

按需拷贝走上面路径下的文件即可。

使用 API 查询或导出标签

请参考 https://www.sensorsdata.cn/manual/query_api.html

注意问题：可能有性能问题，不建议做大数据量的导出，导出大量数据最好使用 JDBC + HDFS。

导出 JSON /user_analytics/users

对应的 UI 操作

请求方法

POST

PATH

/v2/reports/user_analytics/users

Request (application/json)

{
    "filter":{
        "conditions":[
            {
                "field":"user.carrier_name",
                "function":"isSet"
            }
        ]
    },
    "num_per_page":50,
    "page":0,
    "all_page":false,
    "profiles":[
        "user.FirstUseTime",
        "user.Mobile",
        "user.age",
        "user.array",
        "user.bankName",
        "user.carrier_name"
    ],
    "limit":1000,
    "use_cache":false
}

Response

{"page_num":20,"size":1000,"column_name":["FirstUseTime","Mobile","age","array","bankName"],"permitted_properties":
["FirstUseTime","Mobile","age","array","bankName"],"users":[{"id":"-8809360118358200723","first_id":"00207d2931b40dc6","profiles":{}},
{"id":"-6760556487249273086","first_id":"004d8852b49e810f","profiles":{}},{"id":"-8822980603615477502","first_id":"006ff6de99d3234a","profiles":{}}]}

字段含义

关键字	选项	含义
by_fields	可选	分组，得到的人群是按某个/某些属性进行的分组，格式为 user.xxx
slice_by_values	可选	每个分组中的分组值，与 by_fields 同时存在
all_page	可选	是否下载全部用户，下载用户列表时为 true
profiles	必选	需要显示的列
detail	可选	用户列表结果中是否包括 profile 详情
use_cache	必选	是否使用缓存，下载用户列表时填 false
filter	可选	过滤条件
field	必填	标签的属性，格式为 user.xxx，其中 xxx 为标签名
function	必填	查询的功能，如果想要查询标签中某一个值中的用户 function 选择 equal
params	可选	查询的参数，如果 function 为 equal 的话，则必填。如："高价值"，表示筛选的用户在标签 xxx 中是"高价值"的
page	可选	分页请求中的第几页
num_per_page	可选	分页请求中单页多少条数据

导出 CSV /user_analytics/users/csv

PATH

与前者唯一不同是 PATH 结尾加 /csv，即 /reports/user_analytics/users/csv

Request(application/json)

与 /reports/user_analytics/users 相同，略.

Response

id,匿名id,注册id,FirstUseTime,关联设备 ID,姓名,是否删除,注册时间,测试运营商,渠道追踪匹配模式,用户 ID,省份,城市,首次广告系列媒介,首次广告系列来源,首次访问时间 // 表头
-9223174111097466405,7526b04e0463db72,,2019-02-22 05:10:14.633,,,,,,,,,,新浪,新浪,搜狐,搜狐,微信,,,,0,,电信,,-9223174111097466405,,,,,
-9196187200727468031,447c8f808ac11ae5,,2019-02-14 18:26:12.413,,,,,,,,,,微博,百度,微博,搜狐,新浪,,,,0,,电信,,-9196187200727468031,,,,,
-9192478033236701241,36c81078470f32fa,,2019-02-25 23:08:39.587,,,,,,,,,,微信,微信,新浪,搜狐,微博,,,,0,,电信,,-9192478033236701241,,,,,
-9163037612311257423,341651270f20e87f,,2019-03-01 23:02:06.315,,,,,,,,,,搜狐,新浪,百度,微信,新浪,,,,0,,电信,,-9163037612311257423,,,,,
-9137409658088515410,1a7080c84931f117,,2019-02-11 04:45:35.999,,,,,,,,,,百度,新浪,微博,搜狐,百度,,,,0,,电信,,-9137409658088515410,,,,,
-9105370563694013403,2f3afb3ce0d4ea7c,,2019-02-28 00:41:49.090,,,,,,,,,,微信,百度,百度,微博,百度,,,,0,,电信,,-9105370563694013403,,,,,
-9098029065884906907,046d3ed103e358fb,,2019-03-18 20:22:26.938,,,,,,,,,,新浪,新浪,微信,新浪,微博,,,,0,,电信,,-9098029065884906907,,,,,
-9090550161078373930,1da85bab27969438,,2019-02-14 01:43:48.570,,,,,,,,,,百度,新浪,微博,百度,搜狐,,,,0,,电信,,-9090550161078373930,,,,,
-9057722698726216012,655a95158dc1f119,,2019-02-28 05:16:44.650,,,,,,,,,,微信,微博,新浪,搜狐,新浪,,,,0,,电信,,-9057722698726216012,,,,,

查询条件举例

查询历史版本

对应的 UI 操作

Request(application/json)

{
    "profiles":[
        "user.carrier_name"
    ],
    "all_page":true,
    "detail":true,
    "from":"user_tags",
    "filter":{
        "conditions":[
            {
                "field":"user.carrier_name@1552233600000", // @后接 partition 的 base_time 毫秒时间戳
                "function":"isSet"
            }
        ]
    }
}

特定候选值

对应的 UI 操作

Request(application/json)

{
    "profiles":[ // 需要显示的列，用户属性列表 如：
        "user.FirstUseTime",
        "user.referer",
        "user.$utm_medium",
        "user.$utm_source",
        "user.$first_visit_time",
        "user.carrier_name"
    ],
    "all_page":true,
    "detail":true,
    "measures":[
        {
            "aggregator":"count",
            "field":""
        }
    ],
    "from":"user_tags",
    "by_fields":[ // 维度（分组）@ 后接标签/用户群的 base_time
        "user.carrier_name@1552147200000"
    ],
    "slice_by_values":[ // by_fields分组中的分组值，如标签 carrier_name 分组为"移动"的结果，与 by_fields 同时存在
        "移动"
    ]
}

交/并集

对应的 UI 操作

Request(application/json)

{
    "filter": {
        "conditions": [
          {
            "field": "user.his_trd_cnts",
            "function": "isSet",
            "params": [
            ]
          },{
            "field":"user.carrier_name_test",
            "function":"isSet",
            "params": [
            ]
          }
        ],
        "relation": "and" // 交集为 and，并集为 or
    },
    "all_page":true,
    "profiles":[
        "user.agentid",
        "user.companygroup",
        "user.companyindustry1",
        "user.companyindustry2",
        "user.companyname"
    ],
    "use_cache":true
}

在 HUE 中查询标签

在 HUE 中查询，有两种方式。

使用 user 表的字段，这种方式查询的是标签的最新版本。
使用 user_tag_* 表，这种方式可查询标签的历史版本。

使用 user 表查询

以下面的 “年龄” 标签为例，说下你需要知道标签名称，点击“查看规则”。

可以看到标签名称。

再打开 “自定义查询” 功能。

点开 HUE 中的 user 表，可以看到一个叫做 age 的字段。

这个字段代表的就是标签的最新版本数据。

在 HUE 中（即神策的 “自定义查询” 功能），可以看到 user 表存在一个对应字段。

使用标签表查询

HUE 左侧的 user_tag_* 是标签表，user_group_* 是用户群表，二者字段相同。

与 users 表的最大区别，在于标签表具有 base_time 字段，base_time 代表了标签版本，是毫秒的时间戳。

base_time 的产生方式：

例行规则标签：通常是每天的 00:00:00，其 base_time 与相对时间的计算有关，比如 base_time 为 4-10 0:00:00，那么 ”昨天“ 的含义就是 4-9 0:00:00 到 4-10 0:00:00。
外部导入：导入时参数指定。
单次标签、用户群：base_time 通常是标签创建时间。

下图展示了对 is_hb_user 进行 base_time 分组统计的情况。

标签数据导出

导出概述（必读）

使用 JDBC + HDFS 查询或导出标签

获取 JDBC 地址

使用 impala-shell 进行查询

简单查询及 SA 注释

在 HUE 中不加 SA 注释地验证 SQL 正确性

获得标签英文名

查询标签最新版本

查询标签历史版本

结合 HDFS 进行数据导出

使用 API 查询或导出标签

导出 JSON /user_analytics/users

对应的 UI 操作

请求方法

PATH

Request (application/json)

Response

字段含义

导出 CSV /user_analytics/users/csv

PATH

Request(application/json)

Response

查询条件举例

查询历史版本

对应的 UI 操作

Request(application/json)

特定候选值

对应的 UI 操作

Request(application/json)

交/并 集

对应的 UI 操作

Request(application/json)

在 HUE 中查询标签

使用 user 表查询

使用标签表查询

交/并集