数据格式

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

数据类型有以下几种：

详细说明：

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. 一个属性的类型由首次导入的数据类型决定，产品界面应用管理-数据管理中，可查看现有环境中属性的数据类型。

   

• 不同属性数据类型，可计算的指标

  类别	分析功能	数据类型	计算方法
  事件	事件分析	-（全部）	总次数 总人数 人均次数
  事件	分布分析	-（全部）	总次数 天数 小时数
  事件属性	通用	int float	按……求和 按……求平均值 按……求人均值 按……求分位数
  事件属性	通用	Int float string list datetime	按……求去重数 按……和用户去重

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

  类型	为空	不为空	=	≠	大于	小于	大于等于	小于等于	包含	不包含	正则匹配
  字符串	✓	✓	✓	✓					✓	✓	✓
  整型	✓	✓	✓	✓	✓	✓	✓	✓
  浮点型	✓	✓	✓	✓	✓	✓	✓	✓
  数组	✓	✓							✓	✓
  日期时间	✓	✓
  版本	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓	✓

  • 字符串类型可以选择“为空”和“不为空”用于匹配 null 或非 null。

  • 日期类型属性有一个单独的筛选规则（如下表）：

    操作符名称	说明
    固定范围	所选属性的时间在一个固定的时间范围内，可以是过去365天到未来365天内的任何一天或多天。
    在当前时间	所选属性的时间位于查询发起的时刻到用户所设定的相对时段之间。 可选条件： 过去 {N} 小时 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须大于 M，365 >= N > M >0） 未来 {N} 小时 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须小于 M，365 >= N > M >0）
    在今天和	所选属性的时间位于查询发起的当天（自然天）到用户所设定的相对天数（自然天）范围之间。 可选条件： 过去 {N} 天 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须大于 M，365 >= N > M >0） 未来 {N} 天 {之前,之内,至 {M} 天之间}（取值范围：1<= N <= 365，N 须小于 M，365 >= N > M >0）
    在事件发生	所选属性的时间位于相对当前事件的发生时间的一段时间内。由于用到了事件的发生时间，所以仅当作为事件的过滤条件时才会出现这种操作符。 可选条件： 当天、当周和当月：事件发生时所在的自然天、周或月 之前 {N} {天,秒,分,小时,周} 内（此时的天、周计算时不是自然天、自然周，而是相对事件发生时刻推算出的时刻） 之后 {N} {天 , 秒,分,小时,周} 内（同前） N 的取值范围： 天：1 <= N <= 365（当前都按天级的限制执行） 秒：1 <= N <= 365 分：1 <= N <= 365 小时：1 <= N <= 168 周：1 <= N <= 52

    产品界面示例 ：
    

  说明

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

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

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 属性长度和范围的限制 #

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

• 私有化

  {
      "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 计算，但只精确到天
  }
  

Q1：事件属性数据类型传输错误，需要修改怎么办？ #

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

A1 ：

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

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

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

   

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

   

   

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

   原数据类型	原数据示例	新数据类型	新数据示例	历史数据	新数据	其他说明
   值为数值类string	"1"	int	1	不丢失	按新数据类型上报，入库正常	允许修改，且历史数据不丢失，可以查询。
   值为数值类string	"0.1"	float	0.1	不丢失	按新数据类型上报，入库正常
   值为非数值类 string	"abc"	int	0	有损	按新数据类型上报，入库正常
   float	0.1，0.61.1，1.7	int	向下取整（取小数点之前的整数），0.1，0.6会变成0；1.1和1.7会变成1。	不丢失	按新数据类型上报，入库正常
   int	1	string	丢失	丢失	按新数据类型上报，入库正常	允许修改，但历史数据不再能查询，再变更回原类型，依然可用。比如string->int->string。
   int	1	float	丢失	丢失	按新数据类型上报，入库正常
   float	0.1	string	丢失	丢失	按新数据类型上报，入库正常
   除上述表中，其他情况的转换，例如string-datetime，历史数据会丢失，按新数据类型上报，入库正常，并且不可转换为原类型，操作不可逆，请谨慎操作。

4. 第四步：需要研发代码层面，按照新的数据格式进行上报。

Q2： 各端数据类型传输不一致，系统如何处理？如何修改？ #

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

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

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

Q3： 是否接受时间戳string的上报，会自动解析成datetime格式吗？ #

A3：时间戳不支持，只支持日期时间的格式。

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

A4：支持。（上报格式："yyyy-MM-dd"）

Q5： 埋点 设计时，如何选择正确的数据类型？ #

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

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