Title: Property Data Types
Locale: en
URL: https://sensorswave.com/en/docs/data-integration/property-data-types/
Description: Supported property data types and usage guidelines
Sensors Wave supports multiple property data types for storing and analyzing different types of business data. Choosing the correct property data type not only ensures accurate data storage but also improves query performance and supports richer data analysis capabilities.

## Why Should You Understand Property Data Types?

Understanding property data types can help you:

- **Ensure data accuracy**: Using the correct data type avoids data storage errors and type conversion issues
- **Improve query performance**: Appropriate data types can improve the efficiency of data querying and aggregation calculations
- **Support richer analysis**: Different data types support different analysis operations (e.g., numeric calculations, datetime range filtering, etc.)
- **Optimize storage space**: Choosing the appropriate data type can reduce storage costs
- **Avoid data type conflicts**: Maintain the same data type for the same property across different events

## How Property Types Are Determined

Property data types can be determined in two ways. Understanding this mechanism is crucial for designing a correct tracking plan.

### Method 1: Pre-define Property Types (Recommended)

During the tracking planning phase, you can pre-create properties and specify their data types in Sensors Wave's Data Center. This approach offers the following advantages:

- **Explicit types**: The property type is determined at creation time, avoiding type errors caused by inappropriate first-reported data
- **Data consistency**: All reported data must conform to the predefined type, ensuring data quality
- **Easy management**: Centralized property definitions make team collaboration and maintenance easier
- **Reduced risk**: Avoids data issues caused by incorrect type inference

**Use case**: Suitable for projects with a complete tracking plan, especially business scenarios with high data quality requirements.

### Method 2: Automatically Determined on First Report

If a property is not pre-created, Sensors Wave will automatically determine the property type based on the **data type of the first report**.

**Important characteristics**:

- **Type locking**: Once a property type is determined (via first report or pre-definition), subsequent reports **will not** change the property type
- **Automatic conversion**: If subsequently reported data types are inconsistent with the defined type, Sensors Wave will attempt to convert the data to the defined type
- **Conversion risks**: Type conversion may cause the following issues:
  - **Precision loss**: Converting a high-precision decimal to an integer will truncate the decimal portion
  - **Data discard**: If the type conversion completely fails (e.g., converting the string `"abc"` to a number), the property value will be discarded

**Example**:

```json
// First report: the property "age" is identified as String type
{
  "event": "UserSignup",
  "properties": {
    "age": "28"  // String type
  }
}

// Subsequent report: attempting to report a Number type
{
  "event": "UserSignup",
  "properties": {
    "age": 28  // Number type (inconsistent with the defined type)
  }
}
// The system will attempt to convert 28 to the string "28"
```

> **Best practice recommendations**:
> 1. Prefer **Method 1** — pre-define property types during the tracking planning phase
> 2. If using Method 2, ensure the data type of the first report is correct
> 3. Establish a property dictionary that records the name, type, and description of each property
> 4. Thoroughly test in the development environment to confirm property types meet expectations before going live

## Supported Data Types

Sensors Wave supports the following five property data types, which are consistent across **Event Properties, User Properties, virtual properties, and multi-entity properties**:

| Property Type | Enum Value | JSON Data Type | Example Data | Storage Type |
|---------|-------|--------------|---------|---------|
| **Number** | NUMBER | NUMBER | `123`, `100.123` | INT64 or DOUBLE |
| **String** | STRING | STRING | `"Chrome Browser"` | STRING |
| **Datetime** | DATETIME | STRING | `"2015-06-19T17:51:21.999Z"` | DATETIME(3) |
| **Boolean** | BOOLEAN | BOOLEAN | `true`, `false` | BOOLEAN |
| **Array** | ARRAY | LIST\ | `["apple", "banana"]` | ARRAY\ |

## Data Type Details

### 1. Number (Numeric)

**Description**: Used to store integers or floating-point numbers, supports mathematical calculations and aggregation analysis.

**JSON Data Type**: NUMBER

**Example Data**:
```json
{
  "total_amount": 299.00,
  "item_count": 5,
  "discount_rate": 0.15,
  "product_rating": 4.8
}
```

**Storage Type**: Automatically adapted based on the precision of the first reported data
- **INT64**: When the first reported property value is an integer, it is automatically identified as INT64 type
- **DOUBLE**: When the first reported property value is a decimal, it is automatically identified as DOUBLE type

**System Limits**:
- Integers support up to INT64 range (-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807)
- Floating-point numbers support up to DOUBLE type (double-precision floating point)
- If you have high-precision decimal analysis requirements (e.g., financial scenarios), it is recommended to report in STRING format and then parse to DECIMAL type through a virtual property

---

### 2. String

**Description**: Used to store text data; the most commonly used property type.

**JSON Data Type**: STRING

**Example Data**:
```json
{
  "product_name": "Wireless Bluetooth Headphones",
  "payment_method": "alipay",
  "page_url": "https://example.com/products/12345",
  "user_comment": "Great product quality, fast shipping too"
}
```

**Storage Type**: STRING (stored in UTF-8 encoding)

**System Limits**:
- Maximum supported data length of **1024 bytes** (1 KB)
- Strings are stored in UTF-8 encoding; English characters typically take 1 byte, Chinese characters typically take 3 bytes
- Strings exceeding the length limit will be truncated

---

### 3. Datetime

**Description**: Used to store time information with a maximum precision of milliseconds; supports time range filtering and time-dimension analysis.

**JSON Data Type**: STRING (reported as a string; the server automatically parses it as a datetime type)

**Example Data**:
```json
{
  "registration_date": "2026-01-23T10:30:00.123+08:00",  // ISO 8601 format with timezone (recommended)
  "last_login_date": "2026-01-23T10:30:00Z",            // ISO 8601 format, UTC timezone
  "birth_date": "1995-06-15"                            // Date-only format
}
```

**Supported Time Formats**:

Sensors Wave supports **ISO 8601** standard format time strings, and also supports the following common formats for compatibility:

| Format Type | Format | Example | Description |
|---------|------|------|------|
| **ISO 8601 (Recommended)** | yyyy-MM-ddTHH:mm:ss.SSSZ | `"2015-06-19T17:51:21.123Z"``"2015-06-19T17:51:21.123+08:00"` | ISO 8601 standard format with timezone information (**strongly recommended**) |
| Extended support | yyyy-MM-dd HH:mm:ss.SSS | `"2015-06-19 17:51:21.123"` | Millisecond precision |
| Extended support | yyyy-MM-dd HH:mm:ss | `"2015-06-19 17:51:21"` | Second precision |
| Extended support | yyyy-MM-dd | `"2015-06-19"` | Date only |

> **Format priority recommendation**:
> 1. **Preferred**: Use ISO 8601 format with timezone field (e.g., `"2015-06-19T17:51:21.123+08:00"`)
> 2. Alternatively, use an extended time format that meets your precision requirements (e.g., `"2015-06-19 17:51:21.123"`). Note: Extended time formats do not include timezone information; the system will rely on the server-side project timezone configuration for date parsing and processing.

**Storage Type**: DATETIME(3) (stored as DATETIME(3) internally, supporting up to millisecond precision)

**System Limits**:
- Supports ISO 8601 standard format and common datetime formats
- It is recommended to use ISO 8601 format with timezone field (e.g., `"2015-06-19T17:51:21.123+08:00"`) to ensure accuracy of cross-timezone data
- The underlying storage uses DATETIME and **does not store the timezone information from the reported time** (the timezone is only used for conversion during parsing)

**Use Cases**:
- User registration time, first visit time
- Order creation time, payment time
- Last login time, last purchase time
- Membership expiration time, coupon validity period

---

### 4. Boolean

**Description**: Used to store logical true/false values; suitable for binary judgment scenarios.

**JSON Data Type**: BOOLEAN

**Example Data**:
```json
{
  "is_vip": true,
  "has_purchased": false,
  "is_first_order": true,
  "email_verified": true
}
```

**Storage Type**: BOOLEAN

**System Limits**:
- Only supports two values: `true` and `false`
- Do not use the strings `"true"` or `"false"`, as they will be identified as String type

**Use Cases**:
- Whether a member, whether a first purchase
- Feature toggle status (whether a feature is enabled)
- Verification status (whether email is verified, whether phone is verified)
- Subscription status (whether subscribed to email, whether subscribed to SMS)

---

### 5. Array (List)

**Description**: Used to store a collection of multiple values; suitable for tags, lists, and other multi-value scenarios.

**JSON Data Type**: LIST\ (array elements are strings)

**Example Data**:
```json
{
  "product_tags": ["hot", "new", "discount"],
  "favorite_categories": ["electronics", "books"],
  "purchased_product_ids": ["SKU001", "SKU002"],
  "interests": ["technology", "travel", "photography"]
}
```

**Storage Type**: ARRAY\

**System Limits**:
- Array elements only support **String type**; Number, Boolean, and other types are not supported
- If you need to store numeric arrays, it is recommended to convert them to strings before reporting (e.g., `["1", "2", "3"]`)

**Use Cases**:
- Product tags, category tags
- User interest lists, browsed categories
- Lists of used features
- Lists of purchased product IDs

---

## Best Practices

### 1. Pre-define Property Types

During the tracking planning phase, it is recommended to pre-create properties in Sensors Wave's Data Center and explicitly specify data types. This can:
- Avoid data conversion issues caused by inappropriate first-reported data types
- Ensure team members have a unified understanding of property definitions
- Reduce data quality risks

If using the automatically-determined-on-first-report approach, make sure the data type of the first report is correct, as the property type cannot be changed once determined.

### 2. Maintain Data Type Consistency

The same property should use the same data type across all events and users. For example, `total_amount` should use the Number type in all events — do not use the String type in some events. Type inconsistency will cause the system to attempt type conversion, which may lead to precision loss or data discard issues.

### 3. Choose the Appropriate Data Type

Choose the appropriate data type based on the nature of the data and analysis requirements:

| Data Content | Recommended Type | Rationale |
|---------|---------|------|
| Product price, order amount | Numeric | Supports sum, average, and other aggregation calculations |
| Product ID, order ID | String | Used as identifiers; no numeric calculations needed |
| Registration time, purchase time | Datetime | Supports time range filtering and time-dimension analysis |
| Whether a member, whether a first order | Boolean | Clear binary judgment with clear semantics |
| Product tags, interest lists | Array | Supports multi-value storage and list operations |

### 4. Be Aware of String Length Limits

For long text properties, be mindful of the 1 KB length limit. It is recommended to truncate or summarize overly long text.

### 5. Standardize Time Formats

Standardize time formats within your team. **It is strongly recommended to use ISO 8601 format with timezone information** (e.g., `"2026-01-23T10:30:00.123+08:00"`), which:
- Provides explicit timezone information, avoiding ambiguity in cross-timezone data analysis
- Conforms to international standards, improving system compatibility
- Ensures accuracy of user data from different regions

If using other formats (e.g., `yyyy-MM-dd HH:mm:ss.SSS`), ensure the server-side project timezone configuration meets the requirements for the reported data.

### 6. Keep Numeric Units Consistent

The same property should maintain the same unit and precision across different events. For example, `total_amount` should always use the same currency unit (e.g., dollars or yuan) — avoid sometimes using dollars and sometimes using cents.

## Code Examples

### JavaScript SDK

```javascript
// Track a purchase event using multiple data types
sensorswave.trackEvent('Purchase', {
  // Number type
  total_amount: 299.00,          // Float
  item_count: 2,                 // Integer
  discount_rate: 0.15,           // Decimal

  // String type
  product_name: "Wireless Bluetooth Headphones",
  payment_method: "alipay",
  order_status: "completed",

  // Datetime type (recommended: ISO 8601 format with timezone)
  order_date: "2026-01-23T10:30:00.123+08:00",

  // Boolean type
  is_first_order: true,
  is_gift: false,

  // Array type
  product_tags: ["electronics", "wireless", "audio"]
});

// Set User Properties
sensorswave.setUserProfile({
  user_name: "John",
  age: 28,
  is_vip: true,
  registration_date: "2025-01-15T09:00:00+08:00",
  favorite_categories: ["electronics", "books", "sports"]
});
```

## FAQ

### 1. Can a property type be changed after it's been determined?

No. Once a property's data type is determined (whether through pre-definition or first report), it cannot be changed. If subsequently reported data types are inconsistent with the defined type, Sensors Wave will attempt type conversion:

- **Conversion succeeds**: The data will be stored converted to the defined type, but there may be precision loss (e.g., converting `299.99` to the integer `299`)
- **Conversion fails**: The property value may be discarded (e.g., converting the string `"abc"` to a number)

**Recommendations**:
- Pre-define property types during the tracking planning phase to avoid type locking errors caused by incorrect first reports
- Establish a property dictionary that clearly records the type definition for each property
- Thoroughly test in the development environment before deploying to production

### 2. What happens if the same property uses different data types in different events?

When the same property uses different data types in different events, the system will process subsequent data according to the defined property type:
- Sensors Wave will attempt to convert inconsistent data types to the defined type
- Conversion may cause data analysis errors, filter condition failures, or query performance degradation
- Some data may be discarded due to conversion failure

It is recommended to use the same data type for the same property across all events and to regularly check data quality.

### 3. When should I use integers vs floating-point numbers for numeric types?

If not pre-defined, Sensors Wave will automatically identify based on the first reported property value:
- **INT64**: When the first reported property value is an integer
- **DOUBLE**: When the first reported property value is a decimal

It is recommended to use integers for count-type data (e.g., product quantity, login count) and floating-point numbers for amounts, ratings, ratios, and other data requiring precision.

### 4. How do I store high-precision decimals?

For scenarios requiring high-precision calculations such as finance, it is recommended to use STRING type to report data, then parse the string to DECIMAL type through a virtual property during data analysis, avoiding precision loss from using DOUBLE type directly.

### 5. How are timezones handled?

Sensors Wave converts time to a unified timezone during parsing based on timezone information, but **does not save the original timezone information** (the timezone is only used for conversion during parsing).

**Recommended practices**:
- **Use ISO 8601 format with timezone field** (e.g., `"2026-01-23T10:30:00.123+08:00"`) so the system can accurately parse times from different timezones
- If using extended formats without timezone (e.g., `"2026-01-23 10:30:00"`), the system will rely on the server-side project timezone configuration for date parsing and processing, which may lead to inaccurate cross-timezone data
- If cross-timezone user behavior analysis is needed, ensure the client SDK reports the timezone offset property (Android/iOS SDKs automatically collect the `$timezone_offset` property)

### 6. Can array properties store numbers?

Array elements only support String type. If you need to store numeric arrays, it is recommended to convert them to strings before reporting, for example, converting `[123, 456, 789]` to `["123", "456", "789"]`.

## Related Documentation

- [Events and Properties](events-and-properties.mdx): Learn how to design events and properties
- [Preset Events and Preset Properties](preset-events-and-properties.mdx): Learn about the Preset Properties automatically collected by the SDK and their data types
- [Data Model](data-model.mdx): Understand the overall Sensors Wave data model

---

**Last updated**: January 19, 2026