# 数据格式
方舟支持多种 SDK 上报数据，接口会有所不同，但底层数据都使用统一的数据格式，尤其是通过工具导入数据时，也需要符合相应的数据格式。同时，不同的属性，会有不同的数据类型，在分析时对应不同的计算方式，所以在上报数据时需要注意采用合适的格式。
## 上报数据的格式
数据整体是 JSON 格式，描述一条事件或者属性。
**Event 数据样例**
```javascript
[
{
"appid":"demo",
"xwho":"9692043c-7d85-417a-b84e-fd37e1b7a67e",
"xwhat":"confirmOrder",
"xwhen":1533110482778,
"xcontext":{
"$pagename":"com.analysys.demo.activity.MainActivity",
"$channel":"豌豆荚",
"$manufacturer":"Xiaomi",
"$app_version":"4.0.4.001",
"$model":"MIX 2S",
"$os":"Android",
"$os_version":"8.0.0",
"$network":"WIFI",
"$screen_width":1080,
"$screen_height":2030,
"$brand":"Xiaomi",
"$is_first_day":true,
"$lib":"Android",
"$platform":"Android",
"$is_login":false,
"$lib_version":"4.0.4",
"$debug":2，
"order_price":1213.23
}
}
]
```
上述字段说明：
* `appid`：字符串类型，记录项目的 AppKey，创建项目后生成；
* `xwho`：字符串类型，记录用户 ID，调用接口生成；
* `xwhat`：字符串类型，记录事件 ID，必须是合法的变量名，由字母、数字和下划线组成，不能以数字开头，对于系统预置的事件以 $ 开头 ;
* `xwhen`：数据值类型，记录事件发生的时间戳，精确到毫秒；
* `xcontext`：事件的属性，以 dict 的形式存在，其中每个属性，有相应格式。以 $ 开头表示为系统预置的属性，其属性值数据类型都是约定好的，自定义的属性不要以 $ 开头，同一个属性 ID 在不同事件中的定义和数据类型应该保持一致。
**Profile 数据样例**
```javascript
[
{
"appid":"demo",
"xwho":"9692043c-7d85-417a-b84e-fd37e1b7a67e",
"xwhat":"$profile_set",
"xwhen":1533110558121,
"xcontext":{
"Email":"yonghu@163.com",
"$mac":"9c:2e:a1:fe:b7:eb",
"$lib":"Android",
"$platform":"Android",
"$is_login":false,
"$lib_version":"4.0.4",
"$debug":2
}
}
]
```
Profile 信息是通过一些特殊的事件上报，数据格式要求和事件相同。Profile 系列事件包括：
* $profile\_set
* $profile\_set\_once
* $profile\_unset
* $profile\_increment
* $profile\_append
* $profile\_delete
> 特别说明：
>
> 建议您在上报数据时，用户属性ID 和 事件属性ID 使用小写英文字母和下划线组合命名，例如 pagename 、page\_name；
>
> 不建议使用含大写字母的属性ID，例如 pageName 、pageTitle。
>
> 因为易观方舟会将 事件属性ID 和 用户属性ID 中的大写字母强制转换为小写字母。
## 属性值的数据类型
除了整体数据要以 JSON 作为数据传输格式之外，属性值的数据类型也会对应一定格式。
方舟定义了以下数据类型：
| 数据类型 | JSON类型 | 说明 | 示例 |
| ---- | -------- | ------------------------------------------------------------------------------ | ------------------------- |
| 字符串 | string | 使用UTF-8编码后最大长度1024字节 | "易观方舟" |
| 数值 | number | -9E14到9E14, 小数点后最多保留3位 | 123 或者123.12 |
| 布尔 | boolean | true/false | true/false |
| 日期 | datetime | 格式：yyyy-MM-dd HH:mm:ss.SSS 或yyyy-MM-dd HH:mm:ss 或yyyy-mm-dd | "2018-06-18 18:18:18.188" |
| 集合 | array | 元素为字符串，去重后最大元素个数 100，其中每个元素使用 UTF-8 编码后最大长度 255字节；是去重的无序的字符串集合，输入可有重复，导入过程中会去重 | \[ "写作","摄影","烹饪" ] |
方舟预置的一些事件属性和用户属性，也会同时定义好数据类型，详见[《预置事件和属性》](https://arkdocs.analysys.cn/integration/prepare/default-data)。
{% hint style="danger" %}
**方舟不会自动对数据类型错误的属性进行转换**
假如我们有一个表示商品数量的属性 product\_number 首次上报时是数值（number）类型，那么数据库就会将存储这个属性的字段的类型设置为数值（number）。如果接下来 product\_number 收到非数值类型的值时，这一整条日志都会被标记为异常，进入错误队列，而不会进入方舟参与到正常计算中。
错误队列中的数据会保留7天，如果需要恢复当中的数据，请随时联系我们。
{% endhint %}
{% hint style="info" %}
如果发现数据异常变少，可以通过“**数据入库检查**”中的“**错误数据日志**”查看日志是否因为此种情况而被抛弃。
{% endhint %}
{% content-ref url="../data-verification/data\_debug" %}
[data\_debug](https://arkdocs.analysys.cn/integration/data-verification/data_debug)
{% endcontent-ref %}
**不同数据类型属性值的应用**
数据上报中的属性，在分析时可以作为条件查询，也可以作为维度去细分，之所以需要定义不同属性值的数据类型，就是为了进行合适的运算和维度细分，例如 “支付订单金额” ，分析时希望对它进行求和、最大值、最小值、均值等运算，这就要求这个属性值的类型应该是数值型。
以下说明不同数据类型作为细分维度和过滤条件时的使用差异：
### 维度
| 数据类型 | 维度处理方式 | 举例属性 | 查询用户数，按举例维度细分 |
| ---- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 字符串 | 按离散值 | 商品类别
上报的属性值：
3C电器、服装、化妆品……
| 3C电器：12人
服装：12人
化妆品：18人
|
| 数值型 | 按离散值
自定义区间分组
| 商品价格
上报的属性：
12、20、90、300……
| 按离散值：
12：2人
20：3人
90：13人
300：1人
按用户自定义区间的话可能是：
(-∞,50)：5人
\[50,200)：13人
\[200,+∞]：1人
|
| 布尔值 | 按离散值 | 是否使用优惠券
上报的属性值：
true、false
| 使用了优惠券的：12人
没有使用优惠券的：18人
|
| 日期时间 | 按分钟、小时、日、周、月、季、年
按时段汇总：按分钟、小时、日、周，月
| 下单时间
上报的属性值：
2017-03-12 12:12:32、
2018-03-15 12:12:32、
2018-04-12 12:12:32……
| 不按时段汇总，按月：
2017年3月：23人
2018年3月：27人
2018年4月：12人
按时段汇总，按月：
每年3月：50人
每年4月：12人
|
| 集合 | 按集合字符串 | 用户爱好
上报的属性值：
\[网球，摄影]、\[户外，摄影]、\[户外、壁球]……
| \[网球，摄影]：34人
\[户外，摄影]：53人
\[户外、壁球]：23人
|
### 条件
**字符串类型**
| 操作符 | 使用场景 | e.g. |
| ------------ | -------------------------------------------- | ------------------------------- |
| =(等于) | 当输入一个值时，表示等于某个具体确定的属性值；当输入多个时，表示满足其中的一项或多项 | 设备品牌 = 苹果，小米；设备品牌满足苹果、小米中的任意一个 |
| ≠（不等于） | 完全排除输入的某个或多个属性值 | 设备品牌 ≠ 苹果，小米；设备品牌不满足苹果、小米中的任何一个 |
| like（包含） | 查找属性值中包含某些字符的值 | 设备品牌中包含苹果这个词的 |
| notlike（不包含） | 排除属性值中包含某些字符的值 | 设备品牌中不包含苹果这个词的 |
| 有值 | 查找有属性值的数据 | 有设备品牌名称的 |
| 无值 | 查找无属性值的数据 | 无设备品牌名称的 |
| 正则匹配 | 用来检查一个串是否含有某种子串、将匹配的子串替换或者从某个串中取出符合某个条件的子串等 | - |
| 正则不匹配 | 用来检查一个串是否不含有某种子串、将匹配的子串替换或者从某个串中排除符合某个条件的子串等 | - |
**数值型**
| 操作符 | 使用场景 | e.g. |
| ------- | ----------- | ---------------- |
| = (等于) | 等于某个具体数字 | 商品金额 = 100 |
| ≠（不等于） | 不等于某个数字 | 商品金额 ≠ 100 |
| <（小于） | 小于某个数字 | 商品金额 < 100 |
| ≤（小于等于） | 小于等于某个数字 | 商品金额 ≤ 100 |
| >（大于） | 大于某个数字 | 商品金额 ＞ 100 |
| ≥（大于等于） | 大于等于某个数字 | 商品金额 ≥ 100 |
| 介于区间 | 在某个数据区间内的数值 | 100＜商品金额 ≤ 500 |
| 有值 | 查找有属性值的数据 | 有商品金额的 |
| 无值 | 查找无属性值的数据 | 无商品金额的 |
**布尔值**
| 操作符 | 使用场景 | e.g. |
| --- | --------- | -------- |
| 为真 | 某个判断为真 | 是否成功 = 是 |
| 为假 | 某个判断为假 | 是否成功 = 否 |
| 有值 | 查找有属性值的数据 | 有值 |
| 无值 | 查找无属性值的数据 | 无值 |
**日期时间**
| 操作符 | 使用场景 | e.g. |
| -------- | ------------- | -------------------------- |
| 绝对时间 | 在某个具体的时间范围 | 在 2018/12/14- 2018/12/17 |
| 相对当前时间点 | 在相对当前的某段时间里 | 在近 30 天内 |
| 相对事件发生时间 | 在相对事件发生的某段时间里 | 登录之前的 5 分钟里 |
| 有值 | 查找有属性值的数据 | 有日期 |
| 无值 | 查找无属性值的数据 | 无日期 |
**字符串集合**
| 操作符 | 使用场景 | e.g. |
| ------------ | ------------ | ----------- |
| like（包含） | 集合中包含某个字符的值 | 用户标签中包含 摄影 |
| notlike（不包含） | 集合中不包含某个字符的值 | 用户标签不包含设计摄影 |
| 有值 | 查找有属性值的数据 | 有用户标签 |
| 无值 | 查找无属性值的数据 | 无用户标签 |
{% hint style="info" %}
以上内容没有解答我的问题？[点击我进入方舟论坛去反馈](https://www.analysysdata.com/forum/index) 🚀
{% endhint %}