Title: 属性数据类型
Locale: zh
URL: https://sensorswave.com/docs/data-integration/property-data-types/
Description: 支持的属性数据类型和使用说明
Sensors Wave 支持多种属性数据类型，用于存储和分析不同类型的业务数据。正确选择属性数据类型不仅能确保数据的准确存储，还能提升查询性能并支持更丰富的数据分析功能。

## 为什么要了解属性数据类型？

了解属性数据类型可以帮助您：

- **确保数据准确性**：使用正确的数据类型可以避免数据存储错误和类型转换问题
- **提升查询性能**：合适的数据类型能够提高数据查询和聚合计算的效率
- **支持丰富的分析**：不同数据类型支持不同的分析操作（如数值计算、日期范围筛选等）
- **优化存储空间**：选择合适的数据类型可以降低存储成本
- **避免数据类型冲突**：保持同一属性在不同事件中使用相同的数据类型

## 属性类型的确定机制

属性的数据类型可以通过两种方式确定，理解这一机制对于正确设计埋点方案至关重要。

### 方式一：提前定义属性类型（推荐）

在埋点计划阶段，您可以在 Sensors Wave 的数据中心中提前创建属性并指定其数据类型。这种方式具有以下优势：

- **类型明确**：属性类型在创建时即已确定，避免因首次上报数据不当导致类型错误
- **数据一致**：所有上报数据必须符合预定义的类型，确保数据质量
- **便于管理**：集中管理属性定义，便于团队协作和维护
- **减少风险**：避免因类型推断错误导致的数据问题

**使用场景**：适用于有完整埋点规划的项目，特别是对数据质量要求较高的业务场景。

### 方式二：首次上报自动确定

如果没有提前创建属性，Sensors Wave 会根据**第一次上报的数据类型**自动确定该属性的类型。

**重要特性**：

- **类型锁定**：属性类型一旦确定（通过首次上报或提前定义），后续上报**不会**改变属性类型
- **自动转换**：如果后续上报的数据类型与已定义类型不一致，Sensors Wave 会尝试将数据转换为已定义的类型
- **转换风险**：类型转换可能导致以下问题：
  - **精度丢失**：如将高精度小数转换为整数，小数部分会被截断
  - **数据丢弃**：如果类型转换完全失败（如将字符串 `"abc"` 转换为数值），该属性值会被丢弃

**示例说明**：

```json
// 首次上报：属性 age 被识别为字符串类型
{
  "event": "UserSignup",
  "properties": {
    "age": "28"  // 字符串类型
  }
}

// 后续上报：尝试上报数值类型
{
  "event": "UserSignup",
  "properties": {
    "age": 28  // 数值类型（与已定义类型不一致）
  }
}
// 系统会尝试将 28 转换为字符串 "28"
```

> **最佳实践建议**：
> 1. 优先采用**方式一**，在埋点计划阶段提前定义属性类型
> 2. 如果采用方式二，务必确保首次上报的数据类型正确
> 3. 建立属性字典，记录每个属性的名称、类型和说明
> 4. 在开发环境充分测试，确认属性类型符合预期后再上线

## 支持的数据类型

Sensors Wave 支持以下五种属性数据类型，这些类型对**事件属性、用户属性、虚拟属性和多主体属性**等都保持统一：

| 属性类型 | 枚举值 | JSON 数据类型 | 示例数据 | 存储类型 |
|---------|-------|--------------|---------|---------|
| **数值** | NUMBER | NUMBER | `123`、`100.123` | INT64 或 DOUBLE |
| **字符串** | STRING | STRING | `"Chrome Browser"` | STRING |
| **日期时间** | DATETIME | STRING | `"2015-06-19T17:51:21.999Z"` | DATETIME(3) |
| **布尔** | BOOLEAN | BOOLEAN | `true`、`false` | BOOLEAN |
| **数组** | ARRAY | LIST\ | `["apple", "banana"]` | ARRAY\ |

## 数据类型详解

### 1. 数值（Numeric）

**描述**：用于存储整数或浮点数，支持数学计算和聚合分析。

**JSON 数据类型**：NUMBER

**示例数据**：
```json
{
  "total_amount": 299.00,
  "item_count": 5,
  "discount_rate": 0.15,
  "product_rating": 4.8
}
```

**存储类型**：根据首次上报数据的精度自动适配
- **INT64**：当首次上报属性值为整数时，会自动识别为 INT64 类型
- **DOUBLE**：当首次上报属性值为小数时，会自动识别为 DOUBLE 类型

**系统限制**：
- 整数最多支持 INT64 范围（-9,223,372,036,854,775,808 到 9,223,372,036,854,775,807）
- 浮点数最多支持 DOUBLE 类型（双精度浮点数）
- 如果有高精度小数的分析需求（如金融场景），建议采用 STRING 格式上报，之后再通过虚拟属性解析为 DECIMAL 类型

---

### 2. 字符串（String）

**描述**：用于存储文本数据，是最常用的属性类型。

**JSON 数据类型**：STRING

**示例数据**：
```json
{
  "product_name": "无线蓝牙耳机",
  "payment_method": "alipay",
  "page_url": "https://example.com/products/12345",
  "user_comment": "商品质量很好，物流也很快"
}
```

**存储类型**：STRING（以 UTF-8 编码存储）

**系统限制**：
- 最长支持 **1024 字节**（1 KB）数据长度
- 字符串以 UTF-8 编码存储，英文字符通常占 1 个字节，中文字符通常占 3 个字节
- 超出长度限制的字符串会被截断

---

### 3. 日期时间（Datetime）

**描述**：用于存储时间信息，最大精度为毫秒，支持时间范围筛选和时间维度分析。

**JSON 数据类型**：STRING（以字符串格式上报，服务端自动解析为日期时间类型）

**示例数据**：
```json
{
  "registration_date": "2026-01-23T10:30:00.123+08:00",  // ISO 8601 格式，包含时区（推荐）
  "last_login_date": "2026-01-23T10:30:00Z",            // ISO 8601 格式，UTC 时区
  "birth_date": "1995-06-15"                            // 仅日期格式
}
```

**支持的时间格式**：

Sensors Wave 支持 **ISO 8601** 标准格式的时间字符串，同时为了兼容性也支持以下常见格式：

| 格式类型 | 格式 | 示例 | 说明 |
|---------|------|------|------|
| **ISO 8601（推荐）** | yyyy-MM-ddTHH:mm:ss.SSSZ | `"2015-06-19T17:51:21.123Z"``"2015-06-19T17:51:21.123+08:00"` | ISO 8601 标准格式，包含时区信息（**强烈推荐**） |
| 扩展支持 | yyyy-MM-dd HH:mm:ss.SSS | `"2015-06-19 17:51:21.123"` | 精确到毫秒 |
| 扩展支持 | yyyy-MM-dd HH:mm:ss | `"2015-06-19 17:51:21"` | 精确到秒 |
| 扩展支持 | yyyy-MM-dd | `"2015-06-19"` | 仅日期 |

> **格式推荐优先级**：
> 1. **优先使用** ISO 8601 格式并包含时区字段（如 `"2015-06-19T17:51:21.123+08:00"`）
> 2. 其次使用满足精度需求的扩展时间格式（如 `"2015-06-19 17:51:21.123"`），注意：扩展时间格式不包含时区信息，此时系统会依赖服务端项目配置中的时区进行日期的解析和处理。

**存储类型**：DATETIME(3)（底层采用 DATETIME(3) 存储，最多支持时间精度到毫秒）

**系统限制**：
- 支持 ISO 8601 标准格式及常见的日期时间格式
- 推荐优先使用包含时区字段的 ISO 8601 格式（如 `"2015-06-19T17:51:21.123+08:00"`），以确保跨时区数据的准确性
- 底层数据存储采用 DATETIME 存储，**不会存储上报时间的时区信息**（时区仅用于解析时转换为统一时区）

**使用场景**：
- 用户注册时间、首次访问时间
- 订单创建时间、支付时间
- 最后登录时间、最后购买时间
- 会员到期时间、优惠券有效期

---

### 4. 布尔（Boolean）

**描述**：用于存储逻辑真假值，适用于二元判断场景。

**JSON 数据类型**：BOOLEAN

**示例数据**：
```json
{
  "is_vip": true,
  "has_purchased": false,
  "is_first_order": true,
  "email_verified": true
}
```

**存储类型**：BOOLEAN

**系统限制**：
- 仅支持 `true` 和 `false` 两个值
- 不要使用字符串 `"true"` 或 `"false"`，会被识别为字符串类型

**使用场景**：
- 是否会员、是否首次购买
- 功能开关状态（是否启用某功能）
- 验证状态（邮箱是否验证、手机是否验证）
- 订阅状态（是否订阅邮件、是否订阅短信）

---

### 5. 数组（List）

**描述**：用于存储多个值的集合，适用于标签、列表等多值场景。

**JSON 数据类型**：LIST\（数组元素为字符串）

**示例数据**：
```json
{
  "product_tags": ["hot", "new", "discount"],
  "favorite_categories": ["electronics", "books"],
  "purchased_product_ids": ["SKU001", "SKU002"],
  "interests": ["technology", "travel", "photography"]
}
```

**存储类型**：ARRAY\

**系统限制**：
- 数组元素仅支持**字符串类型**，不支持数值、布尔等其他类型
- 如需存储数值数组，建议转换为字符串后上报（如 `["1", "2", "3"]`）

**使用场景**：
- 商品标签、分类标签
- 用户兴趣列表、浏览过的类目
- 使用过的功能列表
- 购买的商品 ID 列表

---

## 最佳实践

### 1. 提前定义属性类型

在埋点计划阶段，建议在 Sensors Wave 的数据中心中提前创建属性并明确指定数据类型，这样可以：
- 避免因首次上报数据类型不当导致后续数据转换问题
- 确保团队成员对属性定义有统一的理解
- 降低数据质量风险

如果采用首次上报自动确定类型的方式，务必确保首次上报的数据类型正确，因为属性类型一旦确定就无法修改。

### 2. 保持数据类型一致性

同一属性在所有事件和用户中应使用相同的数据类型。例如 `total_amount` 在所有事件中都应该使用数值类型，不要在某些事件中使用字符串类型。类型不一致会导致系统尝试类型转换，可能引发精度丢失或数据丢弃问题。

### 3. 选择合适的数据类型

根据数据的性质和分析需求选择合适的数据类型：

| 数据内容 | 推荐类型 | 理由 |
|---------|---------|------|
| 商品价格、订单金额 | Numeric | 支持求和、平均值等聚合计算 |
| 商品 ID、订单 ID | String | 作为标识符，不需要数值计算 |
| 注册时间、购买时间 | Datetime | 支持时间范围筛选和时间维度分析 |
| 是否会员、是否首单 | Boolean | 明确的二元判断，语义清晰 |
| 商品标签、兴趣列表 | Array | 支持多值存储和列表操作 |

### 4. 注意字符串长度限制

对于长文本属性，注意 1 KB 的长度限制，建议对超长文本进行截断或摘要处理。

### 5. 时间格式统一规范

在团队内部统一时间格式，**强烈推荐使用 ISO 8601 格式并包含时区信息**（如 `"2026-01-23T10:30:00.123+08:00"`），这样可以：
- 明确时区信息，避免跨时区数据分析时的歧义
- 符合国际标准，提升系统兼容性
- 确保不同地区用户数据的准确性

如果使用其他格式（如 `yyyy-MM-dd HH:mm:ss.SSS`），需要确保服务端项目时区的配置满足对应上报数据的要求。

### 6. 数值单位保持一致

同一属性在不同事件中应保持相同的单位和精度，例如 `total_amount` 始终使用元作为单位，避免有时使用元、有时使用分。

## 代码示例

### JavaScript SDK

```javascript
// 追踪购买事件，使用多种数据类型
sensorswave.trackEvent('Purchase', {
  // 数值类型
  total_amount: 299.00,          // 浮点数
  item_count: 2,                 // 整数
  discount_rate: 0.15,           // 小数

  // 字符串类型
  product_name: "无线蓝牙耳机",
  payment_method: "alipay",
  order_status: "completed",

  // 日期时间类型（推荐使用 ISO 8601 格式并包含时区）
  order_date: "2026-01-23T10:30:00.123+08:00",

  // 布尔类型
  is_first_order: true,
  is_gift: false,

  // 数组类型
  product_tags: ["electronics", "wireless", "audio"]
});

// 设置用户属性
sensorswave.setUserProfile({
  user_name: "张三",
  age: 28,
  is_vip: true,
  registration_date: "2025-01-15T09:00:00+08:00",
  favorite_categories: ["electronics", "books", "sports"]
});
```

## 常见问题

### 1. 属性类型确定后可以修改吗？

不可以。属性的数据类型一旦确定（无论是通过提前定义还是首次上报），就无法再修改。如果后续上报的数据类型与已定义类型不一致，Sensors Wave 会尝试进行类型转换：

- **转换成功**：数据会被转换为已定义的类型存储，但可能存在精度丢失（如将 `299.99` 转换为整数 `299`）
- **转换失败**：该属性值可能被丢弃（如将字符串 `"abc"` 转换为数值）

**建议**：
- 在埋点计划阶段提前定义属性类型，避免因首次上报错误导致类型锁定错误
- 建立属性字典，明确记录每个属性的类型定义
- 在开发环境充分测试后再上线到生产环境

### 2. 如果同一属性在不同事件中使用了不同数据类型会怎样？

当同一属性在不同事件中使用不同数据类型时，系统会按照已定义的属性类型处理后续数据：
- Sensors Wave 会尝试将不一致的数据类型转换为已定义的类型
- 转换可能导致数据分析错误、筛选条件失效或查询性能下降
- 部分数据可能因转换失败而被丢弃

建议保持同一属性在所有事件中使用相同的数据类型，并定期检查数据质量。

### 3. 数值类型何时使用整数，何时使用浮点数？

如果没有提前在Sensors Wave 会根据首次上报的属性值进行自动识别
- **INT64**：当首次上报的属性值为整数时
- **DOUBLE**：当首次上报的属性值为小数时

建议对于计数类数据（如商品数量、登录次数）使用整数，对于金额、评分、比率等需要精度的数据使用浮点数。

### 4. 如何存储高精度小数？

对于金融等需要高精度计算的场景，建议使用 STRING 类型上报数据，在数据分析时通过虚拟属性将字符串解析为 DECIMAL 类型，避免直接使用 DOUBLE 类型导致精度丢失。

### 5. 时区如何处理?

Sensors Wave 在解析时间时会根据时区信息转换为统一时区存储，但**不会保存原始时区信息**（时区仅用于解析时转换）。

**推荐做法**：
- **优先使用 ISO 8601 格式并包含时区字段**（如 `"2026-01-23T10:30:00.123+08:00"`），这样系统可以准确解析不同时区的时间
- 如果使用不包含时区的扩展格式（如 `"2026-01-23 10:30:00"`），系统会依赖服务端项目配置中的时区进行日期的解析和处理，可能导致跨时区数据不准确
- 如需跨时区分析用户行为，需要保证客户端 SDK 上报时区偏移量属性（Android/iOS SDK 会自动采集 '$timezone_offset' 属性）

### 6. 数组属性可以存储数值吗？

数组元素仅支持字符串类型。如需存储数值数组，建议转换为字符串后上报，例如将 `[123, 456, 789]` 转换为 `["123", "456", "789"]`。

## 相关文档

- [事件和属性](events-and-properties.mdx)：了解如何设计事件和属性
- [预置事件和预置属性](preset-events-and-properties.mdx)：了解 SDK 自动采集的预置属性及其数据类型
- [数据模型](data-model.mdx)：了解 Sensors Wave 的整体数据模型

---

**最后更新时间**：2026 年 1 月 23 日