You need to enable JavaScript to run this app.
最新活动
产品
解决方案
定价
合作与生态
支持与服务
开发者
了解我们
导航

数据格式

更新时间:2023.05.17 15:49:26

底层数据模型需要统一的数据格式,根据不同数据的应用场景,可选择合适的数据格式进行上报,具体描述信息如下。

1.属性数据类型

数据类型有以下几种:

中文名JSON类型数据库类型额外说明示例数据
整数numberint64取值范围:[-9223372036854775808, 9223372036854775807]1024
浮点数numberfloat648字节,最大精度16位10.24
字符串stringstring长度不超过 1024 字符"1024"
数组arraylist最多支持500个元素,元素数据类型支持 string,一个数组中所有元素类型需保持一致。需注意:数据落库时,会对 list 的元素进行去重,例如 [5,5,5] ,变成[5] ; [5,5,6] ,变成[5,6] ; [5,6,5] ,变成[5,6] 。["10", "24"]
日期时间stringdatetime上报格式:"yyyy-MM-dd HH:mm:ss""yyyy-MM-dd HH:mm:ss+Offset"(其中 +Offset 为时区偏移)"yyyy-MM-dd HH:mm:ss.SSS"(其中 SSS 为毫秒)"yyyy-MM-dd HH:mm:ss.SSS+Offset"(同前)日期取值范围:[1970, 2099]"2020-10-24 23:47:12.102""2020-10-24 23:47:12""2020-10-24 23:47:12.102+08:00""2020-10-24 23:47:12+08:00"
版本stringstring上报格式:
1. 2段~6段 2. 英文句点分隔 3. 每段最长5位数字。
对应正则为:^[0-9]{1,5}(\.[0-9]{1,5}){1,5}$
系统发现值的格式匹配时,会自动将数据类型设置为版本类型。版本类型可按数值排序规则进行排序,也可进行大于及小于的运算符进行筛选。
"10.2"
"1.02.4"
"1.02.4.12345.22345.32345"

详细说明:

  1. 支持上报 object 和 boolean (bool-是/否)数据类型的数据,但会被转化成 string 进行存储。

  2. Profile 上报(用户属性上报) datetime说明:

    • 支持常规的 "2020-07-07 01:22:33" 的形式,同时支持形如 “2020-07-07T13:46:08.342+08:00” 格式的支持,即 datetime 字符串自带时区的方式上报属性;

    • 如果是形如 "2020-07-07 01:22:33" 的 datetime 上报,默认按应用级的时区;

    • 如果您需要指定 timezone,需要上报 “2020-07-07T13:46:08.342+08:00” 格式的方式。

  3. 一个属性的类型由首次导入的数据类型决定,产品界面应用管理-数据管理中,可查看现有环境中属性的数据类型。

    image.png

2.不同数据类型应用
  • 不同属性数据类型,可计算的指标

    类别分析功能数据类型计算方法

    事件

    事件分析

    -(全部)

    总次数
    总人数
    人均次数

    事件

    分布分析

    -(全部)

    总次数
    天数
    小时数

    事件属性

    通用

    int
    float

    按……求和
    按……求平均值
    按……求人均值
    按……求分位数

    事件属性

    通用

    Int
    float
    string
    list
    datetime

    按……求去重数
    按……和用户去重

  • 不同属性数据类型,作为筛选条件可用的操作符

    类型为空不为空=大于小于大于等于小于等于包含不包含正则匹配
    字符串
    整型
    浮点型
    数组
    日期时间
    版本
    • 字符串类型可以选择“为空”和“不为空”用于匹配 null 或非 null。

    • 日期类型属性有一个单独的筛选规则(如下表):

      操作符名称说明
      固定范围所选属性的时间在一个固定的时间范围内,可以是过去365天到未来365天内的任何一天或多天。

      在当前时间

      所选属性的时间位于查询发起的时刻到用户所设定的相对时段之间。
      可选条件:

      1. 过去 {N} 小时 {之前,之内,至 {M} 天之间}(取值范围:1<= N <= 365,N 须大于 M,365 >= N > M >0)

      2. 未来 {N} 小时 {之前,之内,至 {M} 天之间}(取值范围:1<= N <= 365,N 须小于 M,365 >= N > M >0)

      在今天和

      所选属性的时间位于查询发起的当天(自然天)到用户所设定的相对天数(自然天)范围之间。
      可选条件:

      1. 过去 {N} 天 {之前,之内,至 {M} 天之间}(取值范围:1<= N <= 365,N 须大于 M,365 >= N > M >0)

      2. 未来 {N} 天 {之前,之内,至 {M} 天之间}(取值范围:1<= N <= 365,N 须小于 M,365 >= N > M >0)

      在事件发生

      所选属性的时间位于相对当前事件的发生时间的一段时间内。由于用到了事件的发生时间,所以仅当作为事件的过滤条件时才会出现这种操作符。
      可选条件:

      1. 当天、当周和当月:事件发生时所在的自然天、周或月

      2. 之前 {N} {天,秒,分,小时,周} 内(此时的天、周计算时不是自然天、自然周,而是相对事件发生时刻推算出的时刻)

      3. 之后 {N} {天 , 秒,分,小时,周} 内(同前)

      N 的取值范围:

      • 天:1 <= N <= 365(当前都按天级的限制执行)

      • 秒:1 <= N <= 365

      • 分:1 <= N <= 365

      • 小时:1 <= N <= 168

      • 周:1 <= N <= 52

      产品界面示例
      image.png

    说明

    选择不同数据格式注意事项:

    • 需要求和、平均值、按照区间范围筛选的必须要用int、float数值类型。
    • 需要时间筛选条件的必须定义数据类型为datetime格式。
3.上报数据限制

3.1 一般限制

  • 单个应用的上报的事件数总量不限制;

  • 单个应用支持元事件种类不超过1000个(不同应用之间互不影响,不含虚拟事件);

  • 单个事件的属性数量推荐300个以内,最多不超过500个(不同事件之间互不影响);

  • 用户属性的属性数量最多不超过 500个;

  • 单个应用自定义事件公共属性数量不超过100个;

  • 事件名建议不超过64个字符,最长不超过255个字符;

  • 事件属性名和用户属性名称最长不超过64个字符;

  • 属性值长度建议不超过255字符,特殊情况如url等最大支持1024字符;

  • 事件属性名称禁止命名为user_unique_id、ssid、event_id;

  • 属性名不允许和预置属性名称相同;预置属性文档可查看预置属性

说明

超过上述限制时,超过的事件、属性数据可能会被系统自动丢弃。更多请查看数据质量

3.2 事件时间限制

使用客户端 SDK (iOS、Android)导入的数据,服务端默认只接收事件发生时间在接收时间向前 7 天内和向后24小时内数据。

3.3 命名限制

  1. events表中,同一个属性名,不允许存在多个属性类型,只有一种属性类型。
  2. users表中,同一个属性名,不允许存在多个属性类型,只有一种属性类型。
  3. 同一个属性名,如果在events和users表中同时存在,在两表中数据类型可以相同,也可以不同。

3.4 属性长度和范围的限制

中文名数据库类型额外说明
整数int64取值范围:[-9223372036854775808, 9223372036854775807]
浮点数float648字节,最大精度16位
字符串string最大支持 1024 字符。
版本(字符串)version(string)格式:1. 2段~6段 2. 英文句点分隔 3. 每段最长5位
示例:1.1.2.4321
数组list最多支持500个元素,元素数据类型支持 string,一个数组中所有元素类型需保持一致。
日期时间datetime日期取值范围:[1900, 2099]
4.日志结构

入库后可看到的数据格式分别如下:

  • 私有化

    {
        "time": 1606301031,
        "server_time": 1606249381,
        "local_time_ms": 1606301031000,
        "device_id": "6912716898461553676",
        "os": "ios",
        "params": {
            "package": "package",
            "app_version": "1.0.6",
            "device_model": "iphone 6s plus",
            "timezone": "8.0",
            "os_version": "10.3.2",
            "session_depth_range": "5",
            "session_id": "762891435873043",
            "network_carrier": "TELCEL",
            "language": "zh",
            "exit_page": "http://datarangers.com.cn/pages/index/3",
            "product_name": "default_to_b",
            "resolution": "375x667",
            "platform": "ios",
            "loc_country_id": "1814991",
            "app_channel": "线下扫码下载",
            "device_brand": "苹果",
            "browser": "chrome",
            "os_name": "ios",
            "loc_province_id": "1280239",
            "session_duration_range": "100-200",
            "client_ip": "118.213.201.135",
            "loc_city_id": "1279540",
            "browser_version": "68.0.3440",
            "network_type": "mobile",
            "duration": 117,
            "session_depth": 5,
            "screen_width": 375,
            "localtime_ms": 1606301031000,
            "screen_height": 667,
            "session_duration": 117,
            "is_login": 1
        }
    }
  • SaaS

    {
            "user": {
                "ssid": "",                // SSID
                "user_unique_id": "",      // user_unique_id,存储于 string_profiles{'uuid'}
                "web_id": 0,               // 网页端的匿名ID,存储于 string_profiles{'web_id'}
                "device_id": 0,            // 移动端,小程序端的匿名ID
                "user_register_time": ""   // 用户首次事件触发时间
            },
            "params": {
                "language": "zh-CN",
                "region": "",
                "app_version": "unknown",
                "app_region": "",
                "app_channel": "",
                "app_language": "",
                "os_version": "10",
                "os_name": "10",
                "device_model": "Windows NT 10.0",
                "device_brand": "",
                "network_type": "",
                "network_carrier": ""
            },
            "items":{
                "sku": [{
                    "id": "",
                    "property_1": "",     // 当前item定义的属性1
                    "property_1": "",     // 当前item定义的属性2
                }]
            },
            "event_name": "predefine_pageview",
            "app_id": "2174",             // string, rangers 中的应用id
            "app_name": "数据发现者",       // string, rangers 中的应用名
            "server_time": 1606783082,    // int(timestamp), 服务端收到事件的时间, 精确到 ms
            "time": 1606783080,           // int(timestamp), time = local_time_ms/1000,单位为秒。
            "event_date": 1606783080      // date, 基于 time 计算,但只精确到天
    }
5.FAQ

Q1:事件属性数据类型传输错误,需要修改怎么办?

描述:在业务迭代过程中,属性含义出现变化,或者上报过程中出现错误,需要修改怎么办?

A1

  1. 第一步:管理员在产品前端界面修改,选择应用管理-数据管理。
    image.png

  2. 第二步:找到对应属性名称。

    图中预置属性(增长分析SDK默认采集的属性,无需手动上报)数据类型为灰色,表示不可修改。只有代码埋点过程中手动上报的属性,才可以修改属性类型。

    image.png

  3. 第三步:选择修改的属性类型。

    image.png

    image.png

    系统会根据修改的数据类型进行提示,其中转换数据规则如下。仅针对事件属性,不适用于用户属性。

    原数据类型原数据示例新数据类型新数据示例历史数据新数据其他说明
    值为数值类string"1"int1不丢失按新数据类型上报,入库正常允许修改,且历史数据不丢失,可以查询。
    值为数值类string"0.1"float0.1不丢失按新数据类型上报,入库正常
    值为非数值类 string"abc"int0有损按新数据类型上报,入库正常
    float0.1,0.61.1,1.7int向下取整(取小数点之前的整数),0.1,0.6会变成0;1.1和1.7会变成1。不丢失按新数据类型上报,入库正常
    int1string丢失丢失按新数据类型上报,入库正常允许修改,但历史数据不再能查询,再变更回原类型,依然可用。比如string->int->string。
    int1float丢失丢失按新数据类型上报,入库正常
    float0.1string丢失丢失按新数据类型上报,入库正常
    除上述表中,其他情况的转换,例如string-datetime,历史数据会丢失,按新数据类型上报,入库正常,并且不可转换为原类型,操作不可逆,请谨慎操作。
  4. 第四步:需要研发代码层面,按照新的数据格式进行上报。

注意

修改前端数据类型后,请及时修改代码,否则会有入库失败或者数据丢失。

Q2: 各端数据类型传输不一致,系统如何处理?如何修改?

描述:例如IOS端先传入A属性的格式为数值类型,安卓端后传入A属性的格式为字符串类型,此时系统如何处理,结果会如何?

A2:一个属性的类型由首次导入的数据类型决定,如果后续传入不同数据类型的数据,系统会尝试做转换,如果转换成功,则入库。如果转换失败,则属性信息值为‘0’入库,相当于属性信息丢失,但事件正常上报。

具体转换成功信息如下表:

原数据类型新数据类型是否转换成功其他说明
int、float、datetime、liststring
数值型string,例如‘1’,‘0.1’int、float原数据类型虽为string,但是值为数字123456
floatint但是会丢失小数点后面的数据。
intfloat
其余数据类型均转换失败。

注意

需要在数据校验侧规避这一问题,如果发生,请错误端及时调整数据格式,否则会引发数据丢失。

Q3: 是否接受时间戳string的上报,会自动解析成datetime格式吗?

A3:时间戳不支持,只支持日期时间的格式。

Q4:datetime是否接受按天级别格式的数据,"yyyy-MM-dd"

A4:支持。(上报格式:"yyyy-MM-dd")

Q5: 埋点 设计时,如何选择正确的数据类型?

中文名数据库类型应用场景
整数int64需要数值求和,平均值等计算,并且不会出现小数的情况。例如:年龄,整数金额。
浮点数float64需要数值求和,平均值等计算,并且会出现小数的情况。例如:折扣金额,时长。
字符串string常用的文本类属性,例如:页面标题,按钮名称,商品分类。不需要计算的ID类型,例如:内容ID,商品ID。
数组list集合,一个属性有多个值,但筛选又需要按单个筛选的。例如:一篇娱乐新闻属于多个内容标签,{‘热门’,‘娱乐’,‘新闻’}例如:一个商品属于多个商品标签{'折扣',‘秋季’,‘女性’}
日期时间datetime需要按照日期范围筛选的
版本string需要对版本进行排序时

Q6:为什么会一段的版本值?不是版本格式要求至少两段么?

默认情况下,系统在遇到被“.”切割为至少两段的数据时(例如 2.0),会自动判断其为版本类型。而对于已知的版本类型的字段,我们会将这个限制放开,允许没有”.“,例如:2 这样的值上报。因为在一些情况下,版本号只有一段。当然对于这种情况,你也可以选择将版本号作为 int 类型上报。