1. 导出概述(必读)

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

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

支持

支持支持
4HUE SQL 查询
  • SQL 分析、验证 SQL 正确性、数据导出
支持支持支持不建议使用

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

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

2.1. 获取 JDBC 地址

登录任意的神策服务器

切换至 sa_cluster 账户

su - sa_cluster
CODE

使用以下命令获取地址 

spadmin config get client -m impala
CODE

例如输出是

  {
      "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"
  }
CODE

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

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

    <dependency>
        <groupId>org.apache.hive</groupId>
        <artifactId>hive-jdbc</artifactId>
        <version>1.1.0</version>
    </dependency>
CODE

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

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

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

2.2. 使用 impala-shell 进行查询

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

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

2.3. 简单查询及 SA 注释

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

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

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

DESC events /*SA*/;
CODE

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

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

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

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

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

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

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

2.5. 获得标签英文名

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


2.6. 查询标签最新版本

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

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

观察 SQL 可见:

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

2.7. 查询标签历史版本

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

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

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

2.8. 结合 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*/
CODE

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

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

SHOW TABLE STATS default.age_export
CODE

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

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

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

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

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

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

3. 使用 API 查询或导出标签

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

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

3.1. 导出 JSON /user_analytics/users

3.1.1. 对应的 UI 操作

3.1.2. 请求方法

  • POST

3.1.3. PATH

  • /v2/reports/user_analytics/users

3.1.4. 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
}
CODE

3.1.5. 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":{}}]}
CODE

3.1.6. 字段含义

关键字选项含义
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可选

分页请求中单页多少条数据

3.2. 导出 CSV /user_analytics/users/csv

3.2.1. PATH

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

3.2.2. Request(application/json)

  • 与 /reports/user_analytics/users 相同,略.

3.2.3. 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,,,,,
CODE

3.3. 查询条件举例

3.3.1. 查询历史版本

3.3.1.1. 对应的 UI 操作

3.3.1.2. 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"
            }
        ]
    }
}
CODE

3.3.2. 特定候选值

3.3.2.1. 对应的 UI 操作

3.3.2.2. 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 同时存在
        "移动"
    ]
}
CODE

3.3.3. 交/并 集

3.3.3.1. 对应的 UI 操作

3.3.3.2. 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
}
CODE

4. 在 HUE 中查询标签

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

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

4.1. 使用 user 表查询

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


可以看到标签英文名。

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

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

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

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

4.2. 使用标签表查询

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 分组统计的情况。