# ClickHouse使用注意事项

## 数据插入最佳实践

### 1. 利用ClickHouse的默认值机制

在向ClickHouse插入数据时，对于有默认值的字段（如`event_id`、`timestamp`、`date`、`hour`等），可以不用显式提供这些值，让ClickHouse自动生成。这样可以：
- 简化代码
- 避免格式错误
- 确保数据一致性

示例：

```typescript
// 推荐做法：不指定有默认值的字段
await clickhouse.insert({
  table: 'events',
  values: [{
    // event_id, timestamp, date, hour 自动由ClickHouse生成
    user_id: 'test-user-123',
    influencer_id: 'influencer-456',
    // 其他必要字段...
  }],
  format: 'JSONEachRow'
});
```

### 2. 避免JSON格式问题

使用`JSONEachRow`格式时，可能会遇到时间戳等特殊格式字段的解析错误：

```
Cannot parse input: expected '"' before: '.749Z","date":"2025-03-12",...
```

解决方法：
- 让ClickHouse使用默认值自动生成时间相关字段
- 如必须手动指定，确保格式严格符合ClickHouse要求

### 3. 使用正确的方法

ClickHouse客户端库(@clickhouse/client)提供了多种插入数据的方法：

- **insert方法**：最适合结构化数据
  ```typescript
  await clickhouse.insert({
    table: 'table_name',
    values: [{ field1: value1, field2: value2 }],
    format: 'JSONEachRow'
  });
  ```

- **query方法**：适合原始SQL语句
  ```typescript
  await clickhouse.query({
    query: `INSERT INTO table_name (field1, field2) VALUES (?, ?)`,
    values: [[value1, value2]]
  });
  ```

### 4. Enum类型字段

对于Enum类型字段（如`event_type`、`funnel_stage`等），插入时使用定义的枚举字符串值，ClickHouse会自动转换为内部数字表示：

```typescript
// 正确：使用枚举字符串值
event_type: 'comment',
funnel_stage: 'consideration',
```

## 常见错误处理

1. **JSON格式错误**：通常与时间戳和日期字段有关，尽可能使用ClickHouse默认值
2. **枚举值错误**：确保使用表定义中的精确枚举字符串
3. **数据类型不匹配**：检查每个字段的类型是否与表定义匹配

## 性能考虑

1. 批量插入比单条插入更高效
2. 对于大批量数据，考虑使用流式插入
3. 高频小数据量插入，考虑使用异步插入方法