名称

csv-schema-infer

描述

当拿到一份来源不明的 CSV/TSV 需要快速判断字段类型、主键、脏数据并把结构固化为建表语句时使用。该技能先做逐列画像（类型、空值率、取值分布、最大长度、格式异常），再推断主键与枚举，输出建模建议、清洗规则和可直接执行的 DDL。适用于数据接入、报表迁移、上下游对账和临时数据集摸底。关键词：CSV、字段类型推断、数据画像、主键、枚举、空值率、数据清洗、建表语句、DDL、表结构、数据接入、对账、数据质量、TSV、编码。

CSV 结构推断与建模建议

把一份“先看数据再定表”的 CSV 变成可执行的表结构与清洗规则。

何时使用

业务方给来一份导出文件，需要落到数仓或业务库。
迁移旧系统，没有数据字典。
两份导出文件要对账，先确认字段语义。
需要快速评估数据质量。

不适用：超大文件（>数 GB）请先采样；需要复杂嵌套结构请用 JSON 分析。

输入

文件路径、编码、分隔符、是否有表头。
业务背景：每行代表什么实体。
目标库类型（MySQL、PostgreSQL、ClickHouse 等）。
是否包含个人数据。

业务背景缺失时，先按“每行一个业务实体”假设，并在结论中标注待确认。

工作流

第 1 步：读入与基础检查

确认编码（UTF-8 BOM、GBK 常见）。
确认分隔符与引号规则。
检查列数与每行列数是否一致，定位坏行。
统计总行数、完全重复行数。

第 2 步：逐列画像

对每列计算：

指标	用途
非空率	判断可空性
唯一值比例	判断主键候选
最大/最小长度	设定字段长度
字符集特征	是否纯数字、是否含中文
格式样本	日期、金额、电话、编码
前 10 高频值	识别枚举与占位符

类型判定顺序：布尔 → 整数 → 小数 → 日期时间 → 枚举 → 字符串。

注意 00123 这类前导零数字应判为字符串。

第 3 步：异常识别

按 references/anomaly-catalog.md 检查：

空字符串与 NULL、N/A、-、无 混用。
数字含千分位、货币符号、全角字符。
日期多种格式并存。
同一语义多种写法（省/省份简称）。
隐藏字符：BOM、零宽空格、尾随空格。
金额精度不一致。

第 4 步：主键与关系

候选主键：非空率 100%、唯一值比例 100%。
组合主键：单列都不唯一，但组合唯一。
无主键时建议增加代理键，并保留业务唯一约束。
外键线索：*_id、*_code 且值域与另一表匹配。

第 5 步：输出结构

为每列给出：列名（规范化为小写下划线）、类型、可空、长度、默认值、注释、样例。

同时给出：

DDL。
清洗映射表（原值 → 标准值）。
待人工确认清单。

第 6 步：验证

用 scripts/profile_csv.py 生成画像，人工复核类型判定。抽样导入 1000 行，执行唯一约束与类型校验。

检查清单

[ ] 编码与分隔符已确认，无乱码。
[ ] 每行列数一致，坏行已定位。
[ ] 类型按优先级判定，前导零未被误判为数字。
[ ] 空值占位符已统一。
[ ] 日期、金额格式已统一。
[ ] 主键/组合主键已验证唯一。
[ ] 字段长度按最大值留有余量。
[ ] 枚举列已列出全部取值。
[ ] 个人数据列已标注并规划脱敏。
[ ] DDL 在目标库实际执行通过。

输出模板

## 数据概览
行数： 列数： 编码： 重复行：

## 字段画像
| 列 | 类型 | 非空率 | 唯一率 | 最大长度 | 枚举/样例 | 判定 |
| --- | --- | --- | --- | --- | --- | --- |

## 主键
...

## 清洗规则
| 列 | 问题 | 规则 | 影响行数 |
| --- | --- | --- | --- |

## DDL
```sql
...

待确认


## 反模式

- 用 `VARCHAR(255)` 通吃所有字段。
- 直接把带千分位的金额导入数值列。
- 用日期字符串原样入库。
- 忽略前导零，导致编号错位。
- 未检查重复就建唯一索引。

## 参考文件

- `references/type-inference.md`：类型判定规则与边界样本。
- `references/anomaly-catalog.md`：常见脏数据模式与处理方式。
- `scripts/profile_csv.py`：CSV 逐列画像脚本。