# 数据格式支持指南

## 目录
1. [支持的文件格式](#支持的文件格式)
2. [格式规范](#格式规范)
3. [最佳实践](#最佳实践)
4. [常见问题](#常见问题)

## 支持的文件格式

### CSV (Comma-Separated Values)
- **扩展名**: `.csv`
- **用途**: 通用表格数据
- **特点**: 
  - 文本格式，可读性好
  - 支持多种编码
  - 适合中小规模数据

### JSON (JavaScript Object Notation)
- **扩展名**: `.json`
- **用途**: 半结构化数据
- **特点**:
  - 支持嵌套结构
  - 灵活的 schema
  - 适合复杂数据

### Parquet
- **扩展名**: `.parquet`
- **用途**: 列式存储
- **特点**:
  - 压缩率高
  - 查询性能优秀
  - 适合大规模数据分析

## 格式规范

### CSV 格式规范
```csv
id,name,email,age,created_at
1,张三,zhangsan@example.com,28,2024-01-01
2,李四,lisi@example.com,32,2024-01-02
```

**要求**:
- 首行为列名
- 使用逗号分隔
- 支持的编码: UTF-8 (推荐), GBK
- 日期格式: YYYY-MM-DD 或 ISO 8601

### JSON 格式规范
```json
[
  {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com",
    "age": 28,
    "created_at": "2024-01-01"
  }
]
```

**要求**:
- 数组格式（每行一个对象也支持）
- UTF-8 编码
- 日期使用 ISO 8601 格式

### Parquet 格式规范
- 使用标准 Parquet 格式
- 推荐使用 Snappy 或 Gzip 压缩
- 支持所有原始数据类型

## 最佳实践

### 数据预处理
1. **清理数据**: 移除重复行、处理缺失值
2. **统一格式**: 确保日期、数字等格式一致
3. **适当分区**: 大规模数据可按日期等字段分区

### 查询优化
1. **使用 LIMIT**: 探索数据时限制返回行数
2. **选择需要的列**: 避免 SELECT *
3. **利用过滤条件**: WHERE 子句减少数据量
4. **抽样验证**: 复杂查询先在小样本上验证

### 错误处理
1. **语法错误**: 检查 SQL 语法，表名、列名是否正确
2. **类型错误**: 确保数据类型匹配
3. **性能问题**: 使用 EXPLAIN 分析查询计划

## 常见问题

**Q: 我的 CSV 文件用分号分隔怎么办？**
A: 当前版本自动识别逗号分隔，如需支持其他分隔符，请先转换为标准 CSV 格式。

**Q: 如何处理包含特殊字符的列名？**
A: 在 SQL 中使用双引号包裹列名，如 `"column name"`。

**Q: 查询超时怎么办？**
A: 1. 使用 LIMIT 减少返回行数；2. 添加 WHERE 条件过滤数据；3. 考虑使用数据抽样。

**Q: 支持 Excel 文件吗？**
A: 当前版本不直接支持 Excel 文件，请先转换为 CSV 或 Parquet 格式。