---
code: data_format
name: "数据规则"
wikiToken: BxBWwrjHYiJGgbkKVxtcaKOmnNv
parentWikiToken: Bmhewqk5PiJirhk1GJzcJliqnOh
updateTime: 1768384216000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=data_format
---
# 数据规则

本章节将会详细介绍 AE 后台的数据结构、数据类型以及数据限制。通过本章节，您将了解如何构建符合规则的数据，排查数据传输问题。

**如果您使用的是 LogBus 或 RESTful API 上传数据，需要按照本章节中的数据规则对数据进行格式处理。**

### 一、数据结构

AE 后台接受的是符合规则的 JSON 数据：如果使用的是 SDK 接入，则数据将会被转化成 JSON 数据进行传输。如果使用 LogBus 或 POST 方法上传数据，则数据需要是符合规则的 JSON 数据。

JSON 数据以行为单位：即一行一条 JSON 数据，对应物理意义上的一条数据，数据意义上对应的是用户产生一次行为，或者是设置一次用户属性。

数据格式及要求如下（为了方便阅读，数据经过排版，真实环境下请勿换行）：

- 以下是事件数据的样例：
```
{
  "#account_id": "ABCDEFG-123-abc",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "track",
  "#ip": "192.168.171.111",
  "#uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "#time": "2017-12-18 14:37:28.527",
  "#event_name": "test",
  "properties": {
    "argString": "abc",
    "argNum": 123,
    "argBool": true
  }
}
```

- 以下是用户属性设置的样例：
```
{
  "#account_id": "ABCDEFG-123-abc",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "user_set",
  "#uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "#time": "2017-12-18 14:37:28.527",
  "properties": {
    "userArgString": "abc",
    "userArgNum": 123,
    "userArgBool": true
  }
}
```

*"#type"的值可以替换为"user_setOnce"、"user_add"、"user_unset"、"user_append"、"user_del"*

从结构和功能上，可以将一条 JSON 数据分为两个部分：

**properties 的同层其他字段，组成了该条数据的基本信息，其中只包括以下几项：**

- 表示触发用户的账号 ID`#account_id`与访客 ID`#distinct_id`
- 表示触发时间`#time`，可精确到秒或毫秒
- 表示数据类型（事件还是用户属性设置）的`#type`
- 表示事件名称的`#event_name`（仅事件数据带有）
- 表示用户 IP 的`#ip`
- 表示数据唯一性的`#uuid`
请注意，除以上几项外，其余以“#”开头的属性都需要放在 properties 的内层

**properties 的内层，是该条数据的内容，也就是事件中的属性，或者需要设置的用户属性，在后台分析时作为属性或分析对象被直接使用。**

从结构上来看，这两部分与报文头（Header）和报文体（Content）有些类似，接下来将会详细介绍这两部分各字段的含义。

#### 1.1 数据信息部分

如下图红框标识，与"properties"同层的数个字段组成了该条数据的信息部分：

这些字段包含了这条数据的触发用户、触发时间等数据信息，其特点是所有字段都以“#”开头，本节将会梳理各字段的意义以及如何配置。

<!-- unsupported block: 22 -->

##### 1.1.1 用户信息（`#account_id`与`#distinct_id`）

`#account_id`与`#distinct_id`是 AE 后台用来识别用户的两个字段，其中`#account_id`为用户在登录状态下的 ID，`#distinct_id`为用户在未登录状态下标识，AE 后台会根据这个两个字段判断该行为的触发用户，其中优先根据`#account_id`进行判断，具体规则参见用户识别规则一章。

`#account_id`与`#distinct_id`至少要传入一个，如果所有事件都是在用户登录状态下触发的，则只传入`#account_id`是可行的，如果有事件是在未登录状态（包括注册前）触发的，则建议将两个字段都填入。

<!-- unsupported block: 22 -->

##### 1.1.2 数据类型信息（`#type`与`#event_name`）

`#type`决定了该条数据的类型，是用户的行为记录、还是修改用户属性的操作处理，**每一条数据都需要配置**`#type`**字段**。`#type`的取值分为两类，`track`代表这条数据是用户行为记录，以`user_`开头代表对用户属性进行操作，具体意义如下：

1. track：向事件表传入一个事件，事件的上传都为 track
1. user_set：对用户表进行操作，覆盖一个或多个用户属性，如果该属性已有值存在，覆盖先前值
1. user_setOnce：对用户表进行操作，初始化一个或多个用户属性，如果该属性已有值存在，则忽略本次操作
1. user_add：对用户表进行操作，为一个或多个数值型用户属性做累加计算
1. user_unset：对用户表进行操作，清空该名用户的一个或多个用户属性的属性值
1. user_del：对用户表进行操作，删除该名用户
1. user_append：对用户表进行操作，为用户的列表类型属性值添加元素
1. user_uniq_append: 对用户表进行操作，为用户的列表类型属性值添加元素，并会进行一次全列表去重（去重保证前后原有的元素顺序不变）
当`#type`的取值为`track`时，即该条数据是行为记录时，**必须配置事件的名称**`#event_name`，必须以字母开头，只能包含：字母（区分大小写）、数字和下划线“_”，长度最大为 50 个字符。请注意配置时不要带有空格。如果该条数据是修改用户属性的操作，则不需要`#event_name`字段。

需要注意的是，用户属性是用户具有节点意义的属性，不建议在短时间内进行频繁修改，对于需要频繁变更的属性，建议放在事件中作为事件属性

<!-- unsupported block: 22 -->

##### 1.1.3 触发时间（`#time`）

`#time`为事件产生的时间，**必须要配置**，格式必须是精确到毫秒（"yyyy-MM-dd HH:mm:ss.SSS"）或秒（"yyyy-MM-dd HH:mm:ss"）的字符串

尽管对 User 表的操作数据也需要配置`#time`，但对于用户属性的操作会按照后台收到数据的先后顺序进行操作。

*比如用户重传了过去某天的 User 表操作数据，则无论是属性的覆盖还是初始化都会照常进行，并不会根据#time 字段进行判断*

<!-- unsupported block: 22 -->

##### 1.1.4 触发地点（`#ip`）

`#ip`是设备的 IP 地址，可选配置，AE 将会根据 IP 地址计算用户的地理位置信息，如果您在"properties"中传入了#country、#province、#city 等地理位置属性，则会以您传入的值为准

<!-- unsupported block: 22 -->

##### 1.1.5 数据唯一 ID（`#uuid`）

`#uuid`是用以表示数据唯一性的字段，可选配置，格式必须为 uuid 的标准格式。AE 将会根据数据量，将会在一段时间内，在接收端校验是否短时间内出现相同`#uuid`的数据（即重复数据），并将重复数据直接抛弃，不再入库

**需注意，通过**`#uuid`**进行的接收端校验只会对近几个小时接收到的数据进行校验，主要解决因网络抖动问题造成的短时数据重复，无法将接收到的数据与全量数据进行校验。如需对数据进行去重，请联系 T****E**** 工作人员。**

<!-- unsupported block: 22 -->

#### 1.2 数据主体部分

数据的另一部分，则是`properties`内层所包含的数据，`properties`是一个 JSON 对象，里面的数据以键值对的形式表示。如果是用户行为数据，其代表了该行为的属性及指标（相当于行为表中的字段），这些属性及指标可在分析时直接使用；如果是用户属性的操作处理，则代表需要设置的属性内容。

key 值为该属性的名称，类型是字符串，自定义的属性必须以字母开头，只能包含：字母（忽略大小写）、数字和下划线“_”，且长度最大只能 50 个字符；另外还存在以`#`开头的 AE 预置属性，您可以在预置属性一章中了解更多信息，但需要注意，大多数情况下建议只使用自定义的属性，不使用#。

value 值为该属性的值，可以是数值、文本、时间、布尔、列表、对象、对象组，数据类型的表示方式如下表所示：

**T****E**** 数据类型**

**取值样例**

**取值说明**

**数据类型**

数值

123,1.23

数据范围是-9E15 至 9E15

Number

文本

"ABC","上海"

字符的默认上限是 2KB

String

时间

"2019-01-01 00:00:00","2019-01-01 00:00:00.000"

"yyyy-MM-dd HH:mm:ss.SSS"或"yyyy-MM-dd HH:mm:ss"，如需表示日期，可使用"yyyy-MM-dd 00:00:00"

String

布尔

true,false

-

Boolean

列表

["a","1","true"]

列表中的元素都会转变为字符串类型，列表内最多500个元素

Array(String)

对象

{"hero_name":"刘备","hero_level":22,"hero_equipment": ["雌雄双股剑","的卢"],"hero_if_support":false}

对象内的每个子属性(Key)都有自己的数据类型，取值说明请参考上面对应类型的普通属性

对象内最多100个子属性

Object

对象组

[{"hero_name":"刘备","hero_level":22,"hero_equipment": ["雌雄双股剑","的卢"],"hero_if_support":false}, {"hero_name":"刘备","hero_level":22,"hero_equipment": ["雌雄双股剑","的卢"],"hero_if_support":false}]

对象组内的每个子属性(Key)都有自己的数据类型，取值说明请参考上面对应类型的普通属性

对象组内最多500个对象

Array(Object)

需要注意，所有属性的类型会根据第一次收到该属性值的类型所决定，后续数据的类型必须与相应属性的类型一致，类型不匹配的属性将被丢弃（该条数据其余符合类型的属性将保留），AE 不会进行类型的兼容转换。

### 二、数据处理规则

AE 服务器在收到数据之后，会进行一些处理，本节将会结合实际使用场景，AE 后台的处理规则：

#### 2.1 收到新事件数据

在收到新增事件的数据后，AE 后台会自动地创建新增事件与其属性的关联模型；如果收到了新的属性，则首次收到该属性时的属性类型将会设置为该属性的类型，属性的类型之后将不能修改。

<!-- unsupported block: 22 -->

#### 2.2 增添事件的属性

如果需要对已有事件增添属性，只需要在上传数据时将新增属性一并传入即可，AE 后台将会动态地关联事件与新增属性，不需要进行其他配置。

<!-- unsupported block: 22 -->

#### 2.3 属性不一致的处理

当收到一条事件数据，其中某属性的类型与后台已存的该属性的类型不一致，则该属性的值将会被抛弃（即取值为 null）。

<!-- unsupported block: 22 -->

#### 2.4 弃用事件属性

如果需要弃用事件某个属性，则只需要在 AE 后台的数据管理模块中将该属性隐藏即可，后续传输的数据可不传该属性。AE 后台不会删除该属性的数据，隐藏操作也是可逆的，如果在属性被隐藏后仍传输该属性，该属性的值仍会被保留。

<!-- unsupported block: 22 -->

#### 2.5 多事件共有属性

不同事件的同名属性被视为是同一属性，类型一致，因此需要保证所有同名属性的类型一致，以避免由于类型不一致而导致的属性值被抛弃。

<!-- unsupported block: 22 -->

#### 2.6 用户表操作逻辑

修改用户在用户表中的数据，也就是上报数据中`#type`字段为`user_set`、`user_setOnce`、`user_add`、`user_unset`、`user_append`或`user_del`的数据，本质上可以看作是一条指令，也就是对该条数据所指用户的用户表数据进行操作，操作的类型由`#type`字段决定，而操作的内容以`properties`中的属性所决定。

以下是主要的用户表属性操作的具体逻辑：

##### 2.6.1 覆盖用户属性(user_set)

根据数据中的用户 ID 确定进行操作的用户，再根据`properties`中的属性，覆盖所有属性，如果某个属性不存在则新建该属性。

##### 2.6.2 初始化用户属性(user_setOnce)

根据数据中的用户 ID 确定进行操作的用户，再根据`properties`中的属性，对未赋值（为空）的属性进行设置，如果该用户的某需要设置的属性已经有值，则不会进行覆盖，如果某个属性不存在则新建该属性。

##### 2.6.3 累加用户属性(user_add)

根据数据中的用户 ID 确定进行操作的用户，再根据`properties`中的属性，对数值型的属性进行累加操作，如果传入负值相当于原属性值减去传入值，如果该用户的某需要设置的属性未赋值（为空），则会默认设置为 0 后再进行累加操作，如果该属性不存在则新建该属性。

##### 2.6.4 清空用户属性值(user_unset)

根据数据中的用户 ID 确定进行操作的用户，再根据`properties`中的属性，清空其中的所有属性（即设置成 NULL），如果某个属性不存在**不会**新建该属性。

##### 2.6.5 添加列表型用户属性的元素(user_append)

根据数据中的用户 ID 确定进行操作的用户，再根据`properties`中的属性，对列表型的属性进行添加元素操作

##### 2.6.6 删除用户(user_del)

根据数据中的用户 ID 确定进行操作的用户，将该用户从用户表中删除，该用户的事件数据**不会**被删除。

##### 2.6.7 添加列表去重型用户属性的元素(user_uniq_append)

根据数据中的用户 ID 确定进行操作的用户，再根据`properties`中的属性，对列表型的属性进行添加元素操作，并进行一次全列表去重（去重保证前后原有的元素顺序不变）

<!-- unsupported block: 22 -->

### 三、数据限制

- **事件类型及属性数量限制**
出于性能考虑，AE 后台会默认地对项目的事件类型及属性的数量进行限制：

**限制**

**事件种类上限**

**事件属性上限**

**用户属性上限**

建议不超过

100

300

100

硬件上限

500

1000

500

管理员可以进入“项目管理”页面，可查询各项目已经使用的事件类型以及属性数，联系 AE 工作人员可申请上调事件种类、属性属性的上限。

- **账号 ID(#account_id)、访客 ID(#distinct_id)长度限制**
```
  * 3.1版本之前创建的项目：64个字符；如需扩大至128个字符，请联系TE工作人员

  * 3.1版本及之后创建的项目：128个字符
```

- **事件、属性名称限制**
```
  * 事件名：`String`类型，以字母开头，可包含数字，大小写字母和下划线“\_”，长度最大为50个字符

  * 属性名：`String`类型，以字母开头，可包含数字，字母（忽略大小写）和下划线“\_”，长度最大为50个字符。只有预置属性能以#号开头。
```

- **文本、数值、列表、对象、对象组类型属性数据范围**
```
  * 文本：字符串上限是2KB

  * 数值：数据范围是-9E15至9E15

  * 列表：最多包含500个元素；每个元素为字符串类型，且上限为255字节
  
  * 对象：最多包含100个子属性；
  
  * 对象组：最多包含500个对象；
```

- **数据接收时限**
```
  * 服务端数据接收事件上限：相对服务器时间的前三年至后3天

  * 客户端数据接收事件上限：相对服务器时间的前10天至后3天
```

### 四、其他规则

1. 请以 UTF-8 对数据进行编码，以避免乱码问题
1. AE 后台的属性名不区分大小写，建议使用"_"作为分词分隔符
1. AE 后台默认只接收最近三年的数据，超过三年的数据将无法录入，如需录入三年之前的数据，可联系 AE 工作人员放宽时限
### 五、常见问题

本节总结了由于数据不符合数据规则而引起的常见问题，如果出现了数据传输问题，可以先根据本节内容进行排查

#### 5.1 AE 后台没有收到数据

**如果使用的是 SDK 传输：**

1. 请确认 SDK 是否被成功集成
1. 排查 APPID 与传输的 URL 是否设置正确，传输端口号及传输方式对应后缀有无遗漏
**如果使用的是 LogBus 或 POST 方法传输：**

1. 请确认 APPID 与传输的 URL 是否设置正确，传输端口号及传输方式对应后缀有无遗漏
1. 请检查数据是否以 JSON 格式传输，并确保一行一条 JSON 数据
1. 请检查数据信息部分的 key 值是否以"#"开头，是否遗漏了必要字段
1. 请检查数据信息部分的 value 值的类型与格式（时间格式）是否正确
1. 请检查"#event_name"的 value 值是否符合规范，不包含汉字，空格等字符
1. "properties"请不要以"#"开头
- 另外，请注意用户属性设置并不会产生行为记录，因此如果只上传了`user_set`等数据，在后台的行为分析模型（除 SQL 查询外）中无法直接查询到数据
- 请注意上传数据的时间，过早时间（超过三年）的数据将不会录入；如果上传数据为历史数据，则可能是查询时段没有涵盖上传数据的时间，请调整查询时段
#### 5.2 数据有缺失，某些属性没有收到

1. 请确认数据主体部分的属性 key 值符合规范，不包含汉字，空格等字符
1. 请确认数据主体部分的属性中，以"#"开头 key 值属于预置属性
1. 请检查缺失属性在上传时的类型是否与后台该属性的类型一致，可在后台的元数据管理中查看已收到属性的类型
#### 5.3 数据传输有误，希望删除数据

1. 私有化服务的用户，可使用数据删除工具自助式的删除数据；如果是云服务的用户，可联系 AE 工作人员进行数据删除
1. 如果数据有较大改动，建议直接新建项目，建议用户在正式传输数据之前先在测试项目下进行完备的数据测试
