| name | byted-bytehouse-data-quality-inspector |
| description | ByteHouse 数据质量检查工具。当用户提供集群连接信息、数据库名和表名，需要检查排序键、主键和分区键所使用的列的空值、零值情况，是否存在异常分布，以及排序键、主键的重复情况时，使用此技能。 |
| version | 1.0.0 |
ByteHouse 数据质量检查工具
描述
本 Skill 用于对 ByteHouse 表的数据质量进行快速分析和检查。
当以下情况时使用此 Skill:
(1) 用户需要检查 ByteHouse 中某个表的数据质量
(2) 用户需要分析表的排序键、主键或分区键的空值、零值情况
(3) 用户想了解键列的数据分布情况
(4) 用户需要检查排序键和主键是否存在重复记录
前置条件
- Python 3.8+
clickhouse-connect 库
📁 文件说明
- SKILL.md - 本文件，技能主文档
- scripts/inspector.py - 数据质量检查主程序
- export_config.sh - 配置导出环境变量脚本（从~/.bytehouse_config.json读取）
配置说明
配置保存在 ~/.bytehouse_config.json ，如果该文件存在且非空，则直接使用文件中的配置。如果不存在，则让用户提供ByteHouse连接信息（ 把这个文档也发给用户，文档里面介绍了如何获取主机地址和密码：https://www.volcengine.com/docs/6517/1121919?lang=zh ）。用户提供信息后，保存到json文件，避免重复向用户请求连接信息。当用户切换ByteHouse集群时，一并修改该文件。
{
"BYTEHOUSE_HOST": "<ByteHouse-host>",
"BYTEHOUSE_PASSWORD": "<ByteHouse-password>"
}
BYTEHOUSE_HOST（主机地址）和BYTEHOUSE_PASSWORD（密码）必须由用户提供
执行 scripts/export_config.sh 把配置信息导入环境变量中
source scripts/export_config.sh
🎯 功能特性
-
自动识别键列
- 自动查询
system.columns 获取表的分区键、排序键和主键。
-
空值与零值检查
- 统计上述键列的 Null 值数量和占比。
- 针对数值类型统计 0 值的数量和占比；针对字符串类型统计空字符串的数量和占比。
-
异常分布分析
- 统计上述键列中出现频率最高的 Top 5 值及占比。
-
重复情况检查
- 分别针对主键组合、排序键组合，统计存在重复的唯一键组数以及涉及的总行数。
🚀 快速开始
source scripts/export_config.sh
python3 scripts/inspector.py --database <库名> --table <表名>
示例输出摘要:
=== 表 default.my_table 数据质量分析报告 ===
总行数: 1000000
分区键: date
排序键: user_id, event_time
主键: user_id
=============================================
1. 关键列空值、零值及分布情况分析:
---------------------------------------------
▶ 列 [user_id] (类型: String):
- 空值 (Null) 数量: 0 (占比: 0.00%)
- 空字符串 ('') 数量: 15 (占比: 0.00%)
- 数据分布 (Top 5):
* user_123: 500 行 (占比: 0.05%)
...
2. 键重复情况分析:
---------------------------------------------
▶ 主键 [user_id] 重复情况:
- 存在重复的唯一键组合数: 850
- 涉及的重复行数: 15000 (占比: 1.50%)
注意事项
- 对于超大表，统计去重和聚合可能会消耗一定的集群资源，请确保在合理的时间和资源范围内执行。
- 此工具只能检测出存在的重复或空值，但不能自动修复数据。
