数据表结构校验

概述

在数据进入分析或数据库前做一道闸门：列是否齐全、类型对不对、数值是否越界。比肉眼检查快且可重复。

何时使用

• 数据入库 / 分析前的质量闸门
• 检查某列取值是否越界
• 多人产出表格的格式对齐

快速使用

# 方式一：命令行逐列给规则
python3 scripts/validate_schema.py 人员.csv \
  --col name:str:::False \
  --col age:int:0:120:False

# 方式二：从 JSON 文件加载规则（便于复用）
python3 scripts/validate_schema.py 人员.csv --schema rules.json

# 校验失败时，把逐行失败明细导出成 CSV 报告
python3 scripts/validate_schema.py 人员.csv --col age:int:0:120:False --report failures.csv

rules.json 格式：

[{"name":"name","dtype":"str","nullable":false},
 {"name":"age","dtype":"int","min":0,"max":120,"nullable":false}]

列规则格式：name:type:min:max:nullable（无上下限留空）

依赖安装

# 提示：脚本用相对路径 scripts/，请先 cd 到本技能目录再运行
python3 -m pip install pandera pandas

常见错误 / 注意

• 当前版本只支持 int/float/str 三型与区间检查，后续可加正则、唯一性、枚举
• 依赖 pandas，大文件注意内存；可后续接分块
• 校验失败会打印具体违反项，便于定位脏数据

实测验证（v0.1.0）

• 核心依赖：pandera
• 安装体积：🟢 13.7 MB（依赖闭包实测，轻量级）
• 环境要求：无外部二进制依赖。
• 单元测试：python3 -m unittest tests.test_...（须 cd 到本技能目录运行）
• CLI 冒烟：已通过端到端实测

已验证行为

• ✅ 合规数据校验通过并回传行数
• ✅ 越界/空值数据被拦截，lazy 模式一次给出所有失败行（列/检查/实际值/行号）
• ✅ 支持 --schema JSON 加载规则、--report 导出失败明细 CSV

已知边界 / 坑

• ⚠️ pandera ≥0.20 推荐 from pandera.pandas import ...，顶层导入已弃用

本技能刻意用轻量用法（无 pandas 重依赖路径），实测闭包仅 13.7MB。