简介DataCleaner中文官方文档面向使用C#进行数据分析与数据治理的开发者、数据工程师及业务分析人员系统梳理数据质量、数据画像、数据整理、数据存储、数据监控和主数据管理等基础概念并说明桌面版从安装客户端、连接数据库或文件、添加与连接job组件到执行、保存及输出结果的完整操作路径。压缩包内为1个docx文件大小约3.47MB以章节化文档组织便于按目录检索和离线查阅。内容还展开Transform、Improve等组件分析涉及JavaScript转换器、子分析job、分类/回归、过滤器、Union转换器及近义词查找等节点可帮助读者理解清洗规则设计与组件组合思路。已有367人学习下载适合需要系统了解DataCleaner功能框架与桌面操作路径的初、中级读者查阅。1. 从一份中文文档说起DataCleaner 到底能解决哪些脏数据硬问题第一次翻《DataCleaner 中文官方文档》是在一个客户主数据合并的收尾阶段业务方坚称客户表看着没问题结果按手机号归一化后去重记录少了三成。这份文档开篇没有急着讲按钮在哪而是先把数据质量、数据画像、数据整理、数据存储、数据监控、主数据管理六个概念摆出来顺序很工程——先定义什么叫脏再谈怎么洗。它适合三类人做数据治理选型的架构师、要给业务出质量报告的 analyst以及像我这样在 .NET 栈里却需要一个能跑批的清洗引擎的开发者。文档覆盖桌面端操作、Transform/Improve/Analyze/Write 四类组件、XML 配置、CLI 与 Hadoop/Spark 接口不是安装说明是一份能照着搭 job 的手册。2. 桌面端跑通第一个 job从装客户端到把结果落成 CSV这一章的目标很务实在一台干净机器上把 DataCleaner 桌面版装起来连上一个 CSV 和一个关系库拖四个组件连成一条线跑出结果并保存成可复用的 job 文件。中间会解释每个动作背后的约束因为后面所有组件分析都建立在这个最小闭环上。2.1 安装前的三个硬条件JDK、许可文件、堆内存文档写得很直白一台电脑、JDK 1.7 及以上、一个专业版许可文件。前两条容易满足第三条是新手第一个卡点——安装向导会让你选许可文件选不到就会停在某一步。我的习惯是先把许可文件放到用户主目录下的.datacleaner目录里再启动安装程序这样即使向导里跳过启动时也能读到。安装程序本身是一个可执行 jar多数系统双击即可。如果双击没反应别急着重装先开命令行# 进入安装包所在目录用完整文件名启动 cd /path/to/installer java -jar DataCleaner-[edition]-[version]-install.jar # 确认本机 JDK 版本低于 1.7 直接升级 java -version这段命令的逻辑很简单java -jar用当前JAVA_HOME指向的 JRE 去执行安装器-version用来确认版本号是否满足 1.7 下限。参数上唯一要替换的是中括号里的 edition 和 version照你下载的文件名填不要自己造。Windows 上没有管理员权限时安装目录别选C:\Program Files选一个用户可写的自定义目录后面改配置文件、放 JDBC 驱动都省事。堆内存是第二个容易翻车的点。桌面版默认堆不大分析几十万行以上的宽表时会在 Analyze 阶段抛内存溢出。安装目录里有两个.l4j文件分别对应图形界面和控制台启动里面有一行-Xmx参数# 编辑启动参数文件把默认堆调大示例给到 4G按机器内存量力而行 # DataCleaner.l4j.ini 内找到 -Xmx 行改为 -Xmx4g # 控制台版对应文件 # DataCleaner-console.l4j.ini -Xmx2g-Xmx是最大堆-Xms是初始堆桌面分析建议两者设成接近的值减少运行期扩容抖动。物理内存 8G 的机器别开 6G 堆留出给操作系统和数据库驱动的空间跑全量主键检查这类要建哈希表的组件堆至少给到数据去重后 key 体积的两倍这是我踩过一次 OOM 之后固定下来的估算方式。2.2 建数据存储CSV、Excel、关系库与复合数据存储文档把数据存储当成一个总称关系库、电子表格、XML 文件、业务系统都算。桌面端的连接向导可以逐个建也可以在配置文件里一次声明。我一般先在 UI 里建确认能预览前 100 行再把配置沉淀成 XML方便后面 CLI 调用。配置文件的结构大致是这样元素名以你本地发行包里的 XSD 为准思路是这几项!-- conf.xml 片段声明一个 CSV 数据存储 -- configuration datastore-catalog csv-datastore namecustomer_raw filename${DATA_DIR}/customer_raw.csv/filename encodingUTF-8/encoding separator,/separator quote-char/quote-char header-line-number1/header-line-number /csv-datastore /datastore-catalog /configurationname是后面 job 里引用这个数据存储的标识起名别用中文和空格filename支持${DATA_DIR}这类变量换环境只改变量不改文件encoding必须和源文件真实编码一致GBK 的文件写成 UTF-8中文列会整列变成乱码后面的字符集分布分析器会直接给你一片红header-line-number告诉解析器第几行是表头没有表头就写 0 并在列定义里手工命名。关系库的配置多几项JDBC URL、驱动类、用户名密码。复合数据存储是文档里容易被忽略的功能它把多个数据存储打包成一个逻辑源好处是同一个 job 里能同时分析来自 CSV 和数据库的两张表做参照完整性检查时特别有用——比如订单表在库里、客户表在 CSV 里不用先导库再跑。数据存储类型典型场景配置要点常见问题CSV导出文件、日志落盘编码、分隔符、引号字符分隔符与字段内容冲突Excel业务方手工维护的台账工作表名、表头行号合并单元格导致列错位关系库生产库只读副本JDBC URL、驱动类驱动未安装、网络 ACL复合数据存储跨源关联分析子存储引用名同名表冲突2.3 组件、连线与执行一个 job 的最小闭环job 是 DataCleaner 的工作流单位。桌面上新建 job 之后左侧组件面板按 Transform、Improve、Analyze、Write 分组把源组件拖进来再拖一个分析器最后拖一个写组件三者的输出端口用鼠标连起来顺序就是数据流向。一个能跑的最小闭环通常是源 → 完整性分析器看空值率→ 值分布看枚举值是否异常→ 创建 CSV 文件落盘。连线时注意端口类型源组件输出的是行数据分析器输出的是分析结果写组件要接在行数据链路上接错了执行时不会报错但结果表是空的这个坑我见新人踩过不止一次。执行按钮点下去之后桌面端会弹出执行面板列出每个组件的状态和耗时。判断是否真的跑成功不看进度条看三件事组件状态是否全绿、分析结果里有没有执行失败的行、输出文件的行数是否和源行数在一个量级。曾经有一次源文件读进来 0 行所有分析器都成功返回空结果日志里只有一行 warning不注意就会把空报告交给业务方。2.4 保存、模板与落盘别让跑通的 job 只活一次job 可以保存成文件下次直接打开。文档还给了示例模板新手拿来改比自己从零拖快得多。我的做法是把模板当脚手架先复制一份改数据存储引用保留组件结构和连线只替换列名和参数这样既继承了别人验证过的组件顺序又不会把模板里的示例路径带进生产。落盘这一步创建 CSV 文件组件要指定输出目录、文件名、编码和是否写表头。输出目录别指向安装目录权限和清理都麻烦编码统一 UTF-8避免下游用 pandas 或 C# 的StreamReader读进来还要猜编码。如果清洗结果要回写数据库用插入表格或更新表格前者适合追加到结果表后者需要指定主键列做匹配主键选错会把整表更新成同一行操作前先在临时表上演练一遍。3. 四类组件怎么选Transform 改值、Improve 对齐、Analyze 度量、Write 落地组件面板看起来杂其实按改不改数据分成两派Transform 和 Improve 会改变数据内容或结构Analyze 只读不写Write 负责落地。选错派的典型后果是——想统计空值率却拖了个 Not null 过滤器结果数据被过滤掉了报告里只剩非空记录数这不是分析是丢数据。下面按用途拆开讲。3.1 TransformJavaScript 转换器与三个过滤器的分工Transform 组里最灵活的是 JavaScript 转换器它让你对每一行的值写脚本。文档把它放在 3.1 节位置很靠前因为它能兜住标准组件覆盖不到的规则。常见写法是拿输入值做规范化返回新值返回 null 表示这一行在该列上不可用交给下游过滤器处理// 输入列绑定为 value输出为函数最后一个表达式的值 // 目标把手机号里的空格、横线、括号去掉并校验是否为 11 位 var s (value null) ? : String(value).replace(/[\s\-()]/g, ); if (/^1\d{10}$/.test(s)) { s; // 合法输出规范化后的号码 } else { null; // 不合法置空由下游 Not null 过滤器拦截 }逻辑说明第一行判空并做字符清洗正则[\s\-()]覆盖空格、横线、左右括号第二行用^1\d{10}$校验位数和首位合法时返回字符串非法时返回 null 而不是原值这样下游能明确区分清洗后仍不合法和本来就有值。参数上唯一需要按业务改的是正则如果你的号码段规则不同改这一处即可别在脚本里写死列名列绑定在组件配置里做。Equals 过滤器、Max rows 过滤器、Not null 过滤器三个是高频组合。Equals 适合白名单式筛选比如只保留订单状态为已支付的行Max rows 适合调试先取前 1000 行验证脚本逻辑再放开全量Not null 接在 JavaScript 转换器后面把上一步置空的行筛掉或单独输出到异常表。Union 转换器解决的是多源合并两个结构一致的数据流按列对齐拼接注意列顺序和类型要一致一边是字符串一边是数字合并后会整列变成字符串后面的数字分析器会报类型不匹配。调用子分析 job是把一段常用流程封装成子 job 复用改一处全链路生效Apply classifier和Apply regression属于机器学习预测类组件需要先有训练好的模型适合做打分而不是规则清洗没有模型文件时拖进来只会报配置错误。3.2 Improve近义词查找和表查询解决的是同一个人写成两种样子Improve 组只有两个组件但解决的是数据治理里最烦的问题标准化。近义词查找依赖同义词目录把北京北京市京映射到同一个标准值表查询则是拿一个对照表做映射比如行政区划代码表、产品分类表。同义词目录的来源有两种文本文件和数据存储。文本文件适合版本化管理一行一组同义词改完提交到代码库数据存储适合业务方维护运营在后台改job 下次跑自动生效。我一般选文本文件因为可 diff、可回滚业务方改数据存储里的同义词表经常不做审核某天把上海映射到上海市辖区这种粒度不一致的值整批地址标准化就偏了。表查询的关键参数是连接列和返回列。连接列用来匹配返回列用来替换或新增。注意大小写和前后空格数据库里的北京和 CSV 里的北京 在字符串比较时不一定相等稳妥做法是先过一遍字符串分析器看值分布确认没有隐藏空格再上表查询。3.3 Analyze15 个分析器的选型表与参数Analyze 是这份文档里篇幅最大的一块从布尔分析器到机器学习一共 15 个。新手容易全拖进来跑一遍结果报告几十页没人看。我的选型原则是先跑三个基础项定位问题再按问题类型补专项分析器。分析器回答什么问题关键参数适用阶段完整性分析器每列空值率多少是否区分空串与 null初次摸底值分布枚举值有哪些、占比多少Top N、是否含空值初次摸底字符串分析器长度分布、空白、大小写最小/最大长度阈值初次摸底模式工具值的模式是否统一最小覆盖率、样本上限格式治理主键检查候选键是否唯一列组合、是否允许 null合并去重前参照完整性外键是否都能对上主表/从表、连接列跨源合并前日期/时间分析器日期是否越界、格式是否一致最小/最大日期、格式串时间字段治理数字分析器数值范围、异常值最小值、最大值、是否允许负金额/数量字段字符集分布是否混入非预期字符字符集白名单编码问题排查布尔分析器是/否类字段的取值分布true/false 的取值映射标志位字段日期间隔分析器两个日期之间的间隔分布起止列、间隔单位时效性分析工作日分布业务是否集中发生在工作日节假日日历业务规则校验值匹配两列值的一致率左右列、是否忽略大小写双源对账参考数据匹配器值是否在标准字典内参考数据源、匹配模式标准值校验机器学习异常检测、聚类模型、特征列进阶场景参数上最容易被忽略的是采样。模式工具和机器学习类分析器默认可能只取一部分样本样本量太小会漏掉长尾模式太大又跑不动。我的经验值是表行数在十万级时全量跑百万级以上先用 Max rows 取 5% 到 10% 做探索确认模式稳定后再全量验证主键和参照完整性这两项必须全量的检查。主键检查有个细节它检查的是候选键组合是否唯一不是数据库约束。多列组合做主键时任何一列为 null 都会影响判断参数里要明确 null 算不算重复。合并两个客户源之前我固定先跑一遍手机号单列、手机号姓名双列两组主键检查看哪组的重复率更接近业务预期再决定去重键。3.4 WriteCSV、Excel、临时表、插入与更新的取舍写组件有五个创建 CSV、创建 Excel、创建临时表、插入表格、更新表格。选哪个取决于下游是谁。给业务方看Excel 最省事但要控制行数超过几万行打开会很慢给下游程序消费CSV 更稳编码统一 UTF-8、分隔符避开字段内容里出现的字符中间结果留给同一个 job 的后续步骤用临时表最快但它只在当前会话有效job 结束就没了要持久化到数据库插入适合追加更新适合按主键改。更新表格有个隐藏成本它需要对每一行做一次匹配数据量大时比插入慢一个数量级。批量更新的常见做法是先插入到临时表再用一条 SQL 做 merge而不是让组件逐行更新。这一步在文档里没有展开但实际项目里差别很大几十万行的表逐行更新能跑几十分钟。4. 配置文件与运行环境XML 结构、日志级别和 JDBC 驱动桌面端能跑通只是第一步要把它放进定时任务或塞进别人的系统绕不开三样东西配置文件、日志、数据库驱动。这一章讲清楚它们各自管什么以及改错了会表现成什么现象。4.1 配置文件里到底放了什么数据存储、参考数据、任务执行器文档第 10 章把配置文件拆成五块XML 模式、数据存储、参考数据、任务执行器和存储提供商。数据存储前面讲过这里补另外三块。参考数据是字典和同义词的载体Dictionaries和Synonyms两节分别讲字典和同义词目录。字典适合放标准值集合比如国家代码、行业分类同义词目录放等价表达。两者都可以来自文本文件或数据存储配置里指定路径和解析格式。改完参考数据要重启或重新加载桌面端有时候缓存不刷新表现是明明改了同义词跑出来还是旧值这是缓存问题不是配置问题。任务执行器管的是 job 怎么跑单机还是提交到集群、并发度多少、超时时间。存储提供商是扩展点自定义数据源类型时才会动。日常清洗改不到这两块但如果你要把 job 交给调度系统跑执行器配置决定了它是同步阻塞还是异步返回前者适合短 job后者适合几十分钟以上的批处理。4.2 分析 job 文件与 source sectionjob 文件本身也是 XML根下面分 source section 和组件定义。source section 声明这个 job 用哪些数据存储、哪些列作为输入。改 job 文件最常见的需求是换数据源路径比如从测试库切到生产库只改 source section 里的引用名组件部分不动。!-- job 文件结构示意source 段声明输入components 段声明处理链 -- job source dataset datastorecustomer_raw column namecustomer_id typeSTRING/ column namemobile typeSTRING/ column namecity typeSTRING/ /dataset /source components !-- 组件顺序即执行顺序与桌面端连线一致 -- /components /jobdatastore要和配置文件里的name对上拼错不会报找不到数据存储而是建出一个空源跑出来 0 行column的type决定下游分析器怎么解释这一列把数字列写成 STRING数字分析器会直接跳过。手工改 job 文件之前先备份XML 少一个闭合标签桌面端打开时提示信息往往指向不到真正的行号。4.3 日志默认配置、改级别与选择性输出日志配置文件决定你排错时能看到什么。文档给了默认日志配置、修改日志级别、选择性日志输出三节。默认级别通常是 INFO组件执行的关键节点会打出来但每个值的处理细节看不到。排查数据问题时把相关包的级别调到 DEBUG# 日志配置片段只把组件执行相关的包调到 DEBUG避免全量日志淹没磁盘 log4j.rootLoggerINFO, console log4j.logger.org.datacleaner.componentsDEBUG log4j.logger.org.datacleaner.jobINFO第一行设根级别和输出目标第二行只放开组件包的调试日志第三行保持 job 调度日志在 INFO。这样跑一个 job 产生的日志量可控出问题时又能看到每个组件收到的行数和列值样本。参数上要改的是包名按你实际报错信息里的类名往上找两级包即可。选择性日志输出适合定位单列问题在组件配置里指定只记录某一列的异常值日志文件会小很多。生产环境别长期开 DEBUG一个百万行的 job 能写出几个 G 的日志磁盘满了我遇到过两次。4.4 数据库驱动装在哪、怎么验证桌面版连数据库报找不到驱动类九成是 JDBC 驱动没装。文档 13.1 节讲在桌面中安装驱动常见做法是把驱动 jar 放进安装目录的驱动文件夹或用户目录下的.datacleaner子目录重启后在连接向导的驱动列表里能看到对应驱动类。# 以 MySQL 为例把驱动 jar 放到用户级驱动目录后重启客户端 mkdir -p ~/.datacleaner/jdbc-drivers cp mysql-connector-java-*.jar ~/.datacleaner/jdbc-drivers/ # 验证启动控制台版并列出可用驱动/数据存储 java -jar DataCleaner-console.jar -list-datastoresmkdir -p保证目录存在且不报错cp把驱动放进去重启是必须的驱动只在启动时扫描。验证命令里的-list-datastores用来确认配置的数据存储能被控制台识别具体参数名以-help输出为准。驱动版本要和数据库版本匹配用旧驱动连新库有时能连上但元数据读不全表现是表列表里少了几张表或者列类型全变成字符串。5. 避坑与排查五个把 job 卡住的真实原因这一章按现象 → 原因 → 解决写都是我或同事实际卡过的点。顺序按发生阶段排从安装到分布式执行。5.1 安装期双击没反应与 .js 脚本引擎现象双击安装 jar 没反应或者安装过程中弹出 There is no script engine for file extension .js。原因有两个一是.jar文件关联被改到了压缩软件双击变成打开压缩包二是.js文件关联到了某个编辑器Windows 内置脚本引擎被绕过。解决方式分别是命令行java -jar指定安装包全路径启动.js关联问题按文档给的系统帮助链接恢复默认关联或者临时把编辑器关联改回系统脚本宿主。这个问题不影响 DataCleaner 运行只影响安装向导里的脚本步骤急的时候可以直接跳过向导把许可文件手工复制到~/.datacleaner。5.2 运行期堆内存、驱动与类型推断现象一Analyze 阶段进度条走到一半卡住随后报内存溢出。原因是主键检查、值分布这类组件要在内存里建哈希表默认堆装不下宽表。解决办法是改.l4j文件里的-Xmx按数据去重后 key 体积的两倍估算改完重启客户端。现象二连库时报驱动类找不到或者连上了但读不到表。原因是驱动 jar 没放对目录或者驱动版本和数据库不匹配。解决办法是按 4.4 节的路径放驱动并重启版本对不上就换官方推荐版本。现象三数字列被当成字符串数字分析器直接跳过。原因是 source section 里的列类型写死成 STRING或者源文件该列混入了非数字字符千分位逗号、货币符号。解决办法是先跑字符串分析器和字符集分布确认混入了什么再决定是在 Transform 阶段清洗还是改列类型。别直接强转强转失败的行会变成 null空值率突然升高会让你误判源数据质量。5.3 分布式Hadoop 接口不是万能加速键现象把桌面端跑得动的 job 提交到 Spark 上报组件不支持或者结果和单机不一致。原因是 Hadoop/Spark 接口有明确的能力边界不是所有组件都能分布式执行依赖全量数据排序或单机内存结构的分析器在集群上要么退化要么直接不支持。解决办法是先查文档 15.5 节的接口限制清单把 job 拆成两段能在集群上跑的清洗和聚合放集群必须单机全量的主键检查、模式发现放回桌面或单独的小规模任务。我一般的流程是桌面端用 5% 样本把组件链和参数调稳再上集群跑全量两边结果做行数和关键指标对账差异超过阈值就回退查组件兼容性。5.4 配置期改了同义词不生效现象同义词目录文本改了重新跑 job 输出还是旧映射。原因是桌面端对参考数据有缓存job 运行期间不会重新读文件。解决办法是关掉 job 重新打开或者重启客户端用 CLI 跑的话每次都是新进程不存在这个缓存问题这也是我把定时任务全部走 CLI 的原因之一。5.5 落盘期输出文件行数对不上现象清洗后 CSV 行数比源少很多但组件状态全绿。原因通常是某个过滤器把行筛掉了却没单独记录或者 JavaScript 转换器返回 null 后被下游 Not null 过滤器拦截异常行没有落到独立输出。解决办法是给每个过滤器加一个拒绝行输出分支写到单独的 CSV跑完对比三个文件的行数源行数 通过行数 拒绝行数。这个等式对不上就是中间有组件悄悄改了行数。6. 让 C# 项目把 DataCleaner 当清洗引擎CLI 参数化与结果对账最后落到跨语言调用。官方文档没有 .NET 绑定桌面端是 Java 生态所以 C# 项目里最常见的做法是用Process调 CLI把 job 文件当契约输入输出都走文件或数据库。这条路不优雅但稳定且不用把 JVM 嵌进 .NET 进程。6.1 CLI参数化 job 与动态重写CLI 的核心能力是执行分析 job、列出数据存储和可用组件、参数化 job、动态重写配置元素。参数化是关键把输入路径、输出路径、日期分区做成占位符C# 侧每次调用传不同值不用改 job 文件。# 执行一个参数化 job传入输入输出路径参数名以 -help 输出为准 java -jar DataCleaner-console.jar \ -job jobs/clean_customer.xml \ -prop inputFile/data/in/customer_20240101.csv \ -prop outputFile/data/out/customer_clean_20240101.csv \ -prop runDate2024-01-01-job指定 job 文件-prop按 keyvalue 传占位符job 文件里用对应变量引用。第一行末尾的反斜杠是换行续写Windows 的 cmd 里换成^PowerShell 里用反引号。退出码要检查0 表示执行完成非 0 表示配置或运行错误具体错误看标准错误输出。6.2 C# 侧进程调用与退出码using System.Diagnostics; var psi new ProcessStartInfo { FileName java, Arguments -jar \C:\\\\dc\\\\DataCleaner-console.jar\ -job \jobs\\\\clean_customer.xml\ -prop inputFileD:\\\\data\\\\in\\\\customer.csv -prop outputFileD:\\\\data\\\\out\\\\customer_clean.csv, RedirectStandardOutput true, RedirectStandardError true, UseShellExecute false, CreateNoWindow true }; using var p Process.Start(psi)!; string stdout p.StandardOutput.ReadToEnd(); string stderr p.StandardError.ReadToEnd(); p.WaitForExit(); if (p.ExitCode ! 0) { // stderr 里通常有组件名和失败原因直接落盘便于排查 File.WriteAllText(dc_error.log, stderr); throw new InvalidOperationException($DataCleaner 退出码 {p.ExitCode}); }逻辑说明RedirectStandardOutput/Error把子进程输出接回来UseShellExecutefalse才能重定向CreateNoWindow避免弹黑框。WaitForExit之后读退出码非 0 就把 stderr 落盘。参数上要注意路径转义C# 字符串里的反斜杠要么双写要么用逐字字符串...路径里有空格必须加引号否则 java 会把空格当参数分隔。6.3 验证三个对账指标CLI 返回 0 只代表进程正常结束不代表数据对。我固定对三个指标输出行数与源行数的比例、关键列空值率、主键重复数。三个指标和基线偏差超过 5% 就回查 job 变更记录。指标计算方式基线来源偏差处理行数保留率输出行数 / 源行数上一次成功批次低于阈值查过滤器关键列空值率空值行数 / 总行数同列历史分布突增查转换脚本主键重复数分组计数大于 1 的组数应为 0非 0 查去重键那张对账表我放在 C# 调度程序里每批跑完自动算一遍结果写进批次日志。有次上游改了手机号字段的格式JavaScript 转换器的正则没跟上行数保留率从 92% 掉到 61%就是靠这张表在业务方发现之前拦下来的。从那以后我每次接新的清洗任务都先用 1000 行样本跑通 CLI 调用和对账再放开全量——这个习惯救过我很多次。希望帮到你。本文还有配套的精品资源点击获取
简介DataCleaner中文官方文档面向使用C#进行数据分析与数据治理的开发者、数据工程师及业务分析人员系统梳理数据质量、数据画像、数据整理、数据存储、数据监控和主数据管理等基础概念并说明桌面版从安装客户端、连接数据库或文件、添加与连接job组件到执行、保存及输出结果的完整操作路径。压缩包内为1个docx文件大小约3.47MB以章节化文档组织便于按目录检索和离线查阅。内容还展开Transform、Improve等组件分析涉及JavaScript转换器、子分析job、分类/回归、过滤器、Union转换器及近义词查找等节点可帮助读者理解清洗规则设计与组件组合思路。已有367人学习下载适合需要系统了解DataCleaner功能框架与桌面操作路径的初、中级读者查阅。1. 从一份中文文档说起DataCleaner 到底能解决哪些脏数据硬问题第一次翻《DataCleaner 中文官方文档》是在一个客户主数据合并的收尾阶段业务方坚称客户表看着没问题结果按手机号归一化后去重记录少了三成。这份文档开篇没有急着讲按钮在哪而是先把数据质量、数据画像、数据整理、数据存储、数据监控、主数据管理六个概念摆出来顺序很工程——先定义什么叫脏再谈怎么洗。它适合三类人做数据治理选型的架构师、要给业务出质量报告的 analyst以及像我这样在 .NET 栈里却需要一个能跑批的清洗引擎的开发者。文档覆盖桌面端操作、Transform/Improve/Analyze/Write 四类组件、XML 配置、CLI 与 Hadoop/Spark 接口不是安装说明是一份能照着搭 job 的手册。2. 桌面端跑通第一个 job从装客户端到把结果落成 CSV这一章的目标很务实在一台干净机器上把 DataCleaner 桌面版装起来连上一个 CSV 和一个关系库拖四个组件连成一条线跑出结果并保存成可复用的 job 文件。中间会解释每个动作背后的约束因为后面所有组件分析都建立在这个最小闭环上。2.1 安装前的三个硬条件JDK、许可文件、堆内存文档写得很直白一台电脑、JDK 1.7 及以上、一个专业版许可文件。前两条容易满足第三条是新手第一个卡点——安装向导会让你选许可文件选不到就会停在某一步。我的习惯是先把许可文件放到用户主目录下的.datacleaner目录里再启动安装程序这样即使向导里跳过启动时也能读到。安装程序本身是一个可执行 jar多数系统双击即可。如果双击没反应别急着重装先开命令行# 进入安装包所在目录用完整文件名启动 cd /path/to/installer java -jar DataCleaner-[edition]-[version]-install.jar # 确认本机 JDK 版本低于 1.7 直接升级 java -version这段命令的逻辑很简单java -jar用当前JAVA_HOME指向的 JRE 去执行安装器-version用来确认版本号是否满足 1.7 下限。参数上唯一要替换的是中括号里的 edition 和 version照你下载的文件名填不要自己造。Windows 上没有管理员权限时安装目录别选C:\Program Files选一个用户可写的自定义目录后面改配置文件、放 JDBC 驱动都省事。堆内存是第二个容易翻车的点。桌面版默认堆不大分析几十万行以上的宽表时会在 Analyze 阶段抛内存溢出。安装目录里有两个.l4j文件分别对应图形界面和控制台启动里面有一行-Xmx参数# 编辑启动参数文件把默认堆调大示例给到 4G按机器内存量力而行 # DataCleaner.l4j.ini 内找到 -Xmx 行改为 -Xmx4g # 控制台版对应文件 # DataCleaner-console.l4j.ini -Xmx2g-Xmx是最大堆-Xms是初始堆桌面分析建议两者设成接近的值减少运行期扩容抖动。物理内存 8G 的机器别开 6G 堆留出给操作系统和数据库驱动的空间跑全量主键检查这类要建哈希表的组件堆至少给到数据去重后 key 体积的两倍这是我踩过一次 OOM 之后固定下来的估算方式。2.2 建数据存储CSV、Excel、关系库与复合数据存储文档把数据存储当成一个总称关系库、电子表格、XML 文件、业务系统都算。桌面端的连接向导可以逐个建也可以在配置文件里一次声明。我一般先在 UI 里建确认能预览前 100 行再把配置沉淀成 XML方便后面 CLI 调用。配置文件的结构大致是这样元素名以你本地发行包里的 XSD 为准思路是这几项!-- conf.xml 片段声明一个 CSV 数据存储 -- configuration datastore-catalog csv-datastore namecustomer_raw filename${DATA_DIR}/customer_raw.csv/filename encodingUTF-8/encoding separator,/separator quote-char/quote-char header-line-number1/header-line-number /csv-datastore /datastore-catalog /configurationname是后面 job 里引用这个数据存储的标识起名别用中文和空格filename支持${DATA_DIR}这类变量换环境只改变量不改文件encoding必须和源文件真实编码一致GBK 的文件写成 UTF-8中文列会整列变成乱码后面的字符集分布分析器会直接给你一片红header-line-number告诉解析器第几行是表头没有表头就写 0 并在列定义里手工命名。关系库的配置多几项JDBC URL、驱动类、用户名密码。复合数据存储是文档里容易被忽略的功能它把多个数据存储打包成一个逻辑源好处是同一个 job 里能同时分析来自 CSV 和数据库的两张表做参照完整性检查时特别有用——比如订单表在库里、客户表在 CSV 里不用先导库再跑。数据存储类型典型场景配置要点常见问题CSV导出文件、日志落盘编码、分隔符、引号字符分隔符与字段内容冲突Excel业务方手工维护的台账工作表名、表头行号合并单元格导致列错位关系库生产库只读副本JDBC URL、驱动类驱动未安装、网络 ACL复合数据存储跨源关联分析子存储引用名同名表冲突2.3 组件、连线与执行一个 job 的最小闭环job 是 DataCleaner 的工作流单位。桌面上新建 job 之后左侧组件面板按 Transform、Improve、Analyze、Write 分组把源组件拖进来再拖一个分析器最后拖一个写组件三者的输出端口用鼠标连起来顺序就是数据流向。一个能跑的最小闭环通常是源 → 完整性分析器看空值率→ 值分布看枚举值是否异常→ 创建 CSV 文件落盘。连线时注意端口类型源组件输出的是行数据分析器输出的是分析结果写组件要接在行数据链路上接错了执行时不会报错但结果表是空的这个坑我见新人踩过不止一次。执行按钮点下去之后桌面端会弹出执行面板列出每个组件的状态和耗时。判断是否真的跑成功不看进度条看三件事组件状态是否全绿、分析结果里有没有执行失败的行、输出文件的行数是否和源行数在一个量级。曾经有一次源文件读进来 0 行所有分析器都成功返回空结果日志里只有一行 warning不注意就会把空报告交给业务方。2.4 保存、模板与落盘别让跑通的 job 只活一次job 可以保存成文件下次直接打开。文档还给了示例模板新手拿来改比自己从零拖快得多。我的做法是把模板当脚手架先复制一份改数据存储引用保留组件结构和连线只替换列名和参数这样既继承了别人验证过的组件顺序又不会把模板里的示例路径带进生产。落盘这一步创建 CSV 文件组件要指定输出目录、文件名、编码和是否写表头。输出目录别指向安装目录权限和清理都麻烦编码统一 UTF-8避免下游用 pandas 或 C# 的StreamReader读进来还要猜编码。如果清洗结果要回写数据库用插入表格或更新表格前者适合追加到结果表后者需要指定主键列做匹配主键选错会把整表更新成同一行操作前先在临时表上演练一遍。3. 四类组件怎么选Transform 改值、Improve 对齐、Analyze 度量、Write 落地组件面板看起来杂其实按改不改数据分成两派Transform 和 Improve 会改变数据内容或结构Analyze 只读不写Write 负责落地。选错派的典型后果是——想统计空值率却拖了个 Not null 过滤器结果数据被过滤掉了报告里只剩非空记录数这不是分析是丢数据。下面按用途拆开讲。3.1 TransformJavaScript 转换器与三个过滤器的分工Transform 组里最灵活的是 JavaScript 转换器它让你对每一行的值写脚本。文档把它放在 3.1 节位置很靠前因为它能兜住标准组件覆盖不到的规则。常见写法是拿输入值做规范化返回新值返回 null 表示这一行在该列上不可用交给下游过滤器处理// 输入列绑定为 value输出为函数最后一个表达式的值 // 目标把手机号里的空格、横线、括号去掉并校验是否为 11 位 var s (value null) ? : String(value).replace(/[\s\-()]/g, ); if (/^1\d{10}$/.test(s)) { s; // 合法输出规范化后的号码 } else { null; // 不合法置空由下游 Not null 过滤器拦截 }逻辑说明第一行判空并做字符清洗正则[\s\-()]覆盖空格、横线、左右括号第二行用^1\d{10}$校验位数和首位合法时返回字符串非法时返回 null 而不是原值这样下游能明确区分清洗后仍不合法和本来就有值。参数上唯一需要按业务改的是正则如果你的号码段规则不同改这一处即可别在脚本里写死列名列绑定在组件配置里做。Equals 过滤器、Max rows 过滤器、Not null 过滤器三个是高频组合。Equals 适合白名单式筛选比如只保留订单状态为已支付的行Max rows 适合调试先取前 1000 行验证脚本逻辑再放开全量Not null 接在 JavaScript 转换器后面把上一步置空的行筛掉或单独输出到异常表。Union 转换器解决的是多源合并两个结构一致的数据流按列对齐拼接注意列顺序和类型要一致一边是字符串一边是数字合并后会整列变成字符串后面的数字分析器会报类型不匹配。调用子分析 job是把一段常用流程封装成子 job 复用改一处全链路生效Apply classifier和Apply regression属于机器学习预测类组件需要先有训练好的模型适合做打分而不是规则清洗没有模型文件时拖进来只会报配置错误。3.2 Improve近义词查找和表查询解决的是同一个人写成两种样子Improve 组只有两个组件但解决的是数据治理里最烦的问题标准化。近义词查找依赖同义词目录把北京北京市京映射到同一个标准值表查询则是拿一个对照表做映射比如行政区划代码表、产品分类表。同义词目录的来源有两种文本文件和数据存储。文本文件适合版本化管理一行一组同义词改完提交到代码库数据存储适合业务方维护运营在后台改job 下次跑自动生效。我一般选文本文件因为可 diff、可回滚业务方改数据存储里的同义词表经常不做审核某天把上海映射到上海市辖区这种粒度不一致的值整批地址标准化就偏了。表查询的关键参数是连接列和返回列。连接列用来匹配返回列用来替换或新增。注意大小写和前后空格数据库里的北京和 CSV 里的北京 在字符串比较时不一定相等稳妥做法是先过一遍字符串分析器看值分布确认没有隐藏空格再上表查询。3.3 Analyze15 个分析器的选型表与参数Analyze 是这份文档里篇幅最大的一块从布尔分析器到机器学习一共 15 个。新手容易全拖进来跑一遍结果报告几十页没人看。我的选型原则是先跑三个基础项定位问题再按问题类型补专项分析器。分析器回答什么问题关键参数适用阶段完整性分析器每列空值率多少是否区分空串与 null初次摸底值分布枚举值有哪些、占比多少Top N、是否含空值初次摸底字符串分析器长度分布、空白、大小写最小/最大长度阈值初次摸底模式工具值的模式是否统一最小覆盖率、样本上限格式治理主键检查候选键是否唯一列组合、是否允许 null合并去重前参照完整性外键是否都能对上主表/从表、连接列跨源合并前日期/时间分析器日期是否越界、格式是否一致最小/最大日期、格式串时间字段治理数字分析器数值范围、异常值最小值、最大值、是否允许负金额/数量字段字符集分布是否混入非预期字符字符集白名单编码问题排查布尔分析器是/否类字段的取值分布true/false 的取值映射标志位字段日期间隔分析器两个日期之间的间隔分布起止列、间隔单位时效性分析工作日分布业务是否集中发生在工作日节假日日历业务规则校验值匹配两列值的一致率左右列、是否忽略大小写双源对账参考数据匹配器值是否在标准字典内参考数据源、匹配模式标准值校验机器学习异常检测、聚类模型、特征列进阶场景参数上最容易被忽略的是采样。模式工具和机器学习类分析器默认可能只取一部分样本样本量太小会漏掉长尾模式太大又跑不动。我的经验值是表行数在十万级时全量跑百万级以上先用 Max rows 取 5% 到 10% 做探索确认模式稳定后再全量验证主键和参照完整性这两项必须全量的检查。主键检查有个细节它检查的是候选键组合是否唯一不是数据库约束。多列组合做主键时任何一列为 null 都会影响判断参数里要明确 null 算不算重复。合并两个客户源之前我固定先跑一遍手机号单列、手机号姓名双列两组主键检查看哪组的重复率更接近业务预期再决定去重键。3.4 WriteCSV、Excel、临时表、插入与更新的取舍写组件有五个创建 CSV、创建 Excel、创建临时表、插入表格、更新表格。选哪个取决于下游是谁。给业务方看Excel 最省事但要控制行数超过几万行打开会很慢给下游程序消费CSV 更稳编码统一 UTF-8、分隔符避开字段内容里出现的字符中间结果留给同一个 job 的后续步骤用临时表最快但它只在当前会话有效job 结束就没了要持久化到数据库插入适合追加更新适合按主键改。更新表格有个隐藏成本它需要对每一行做一次匹配数据量大时比插入慢一个数量级。批量更新的常见做法是先插入到临时表再用一条 SQL 做 merge而不是让组件逐行更新。这一步在文档里没有展开但实际项目里差别很大几十万行的表逐行更新能跑几十分钟。4. 配置文件与运行环境XML 结构、日志级别和 JDBC 驱动桌面端能跑通只是第一步要把它放进定时任务或塞进别人的系统绕不开三样东西配置文件、日志、数据库驱动。这一章讲清楚它们各自管什么以及改错了会表现成什么现象。4.1 配置文件里到底放了什么数据存储、参考数据、任务执行器文档第 10 章把配置文件拆成五块XML 模式、数据存储、参考数据、任务执行器和存储提供商。数据存储前面讲过这里补另外三块。参考数据是字典和同义词的载体Dictionaries和Synonyms两节分别讲字典和同义词目录。字典适合放标准值集合比如国家代码、行业分类同义词目录放等价表达。两者都可以来自文本文件或数据存储配置里指定路径和解析格式。改完参考数据要重启或重新加载桌面端有时候缓存不刷新表现是明明改了同义词跑出来还是旧值这是缓存问题不是配置问题。任务执行器管的是 job 怎么跑单机还是提交到集群、并发度多少、超时时间。存储提供商是扩展点自定义数据源类型时才会动。日常清洗改不到这两块但如果你要把 job 交给调度系统跑执行器配置决定了它是同步阻塞还是异步返回前者适合短 job后者适合几十分钟以上的批处理。4.2 分析 job 文件与 source sectionjob 文件本身也是 XML根下面分 source section 和组件定义。source section 声明这个 job 用哪些数据存储、哪些列作为输入。改 job 文件最常见的需求是换数据源路径比如从测试库切到生产库只改 source section 里的引用名组件部分不动。!-- job 文件结构示意source 段声明输入components 段声明处理链 -- job source dataset datastorecustomer_raw column namecustomer_id typeSTRING/ column namemobile typeSTRING/ column namecity typeSTRING/ /dataset /source components !-- 组件顺序即执行顺序与桌面端连线一致 -- /components /jobdatastore要和配置文件里的name对上拼错不会报找不到数据存储而是建出一个空源跑出来 0 行column的type决定下游分析器怎么解释这一列把数字列写成 STRING数字分析器会直接跳过。手工改 job 文件之前先备份XML 少一个闭合标签桌面端打开时提示信息往往指向不到真正的行号。4.3 日志默认配置、改级别与选择性输出日志配置文件决定你排错时能看到什么。文档给了默认日志配置、修改日志级别、选择性日志输出三节。默认级别通常是 INFO组件执行的关键节点会打出来但每个值的处理细节看不到。排查数据问题时把相关包的级别调到 DEBUG# 日志配置片段只把组件执行相关的包调到 DEBUG避免全量日志淹没磁盘 log4j.rootLoggerINFO, console log4j.logger.org.datacleaner.componentsDEBUG log4j.logger.org.datacleaner.jobINFO第一行设根级别和输出目标第二行只放开组件包的调试日志第三行保持 job 调度日志在 INFO。这样跑一个 job 产生的日志量可控出问题时又能看到每个组件收到的行数和列值样本。参数上要改的是包名按你实际报错信息里的类名往上找两级包即可。选择性日志输出适合定位单列问题在组件配置里指定只记录某一列的异常值日志文件会小很多。生产环境别长期开 DEBUG一个百万行的 job 能写出几个 G 的日志磁盘满了我遇到过两次。4.4 数据库驱动装在哪、怎么验证桌面版连数据库报找不到驱动类九成是 JDBC 驱动没装。文档 13.1 节讲在桌面中安装驱动常见做法是把驱动 jar 放进安装目录的驱动文件夹或用户目录下的.datacleaner子目录重启后在连接向导的驱动列表里能看到对应驱动类。# 以 MySQL 为例把驱动 jar 放到用户级驱动目录后重启客户端 mkdir -p ~/.datacleaner/jdbc-drivers cp mysql-connector-java-*.jar ~/.datacleaner/jdbc-drivers/ # 验证启动控制台版并列出可用驱动/数据存储 java -jar DataCleaner-console.jar -list-datastoresmkdir -p保证目录存在且不报错cp把驱动放进去重启是必须的驱动只在启动时扫描。验证命令里的-list-datastores用来确认配置的数据存储能被控制台识别具体参数名以-help输出为准。驱动版本要和数据库版本匹配用旧驱动连新库有时能连上但元数据读不全表现是表列表里少了几张表或者列类型全变成字符串。5. 避坑与排查五个把 job 卡住的真实原因这一章按现象 → 原因 → 解决写都是我或同事实际卡过的点。顺序按发生阶段排从安装到分布式执行。5.1 安装期双击没反应与 .js 脚本引擎现象双击安装 jar 没反应或者安装过程中弹出 There is no script engine for file extension .js。原因有两个一是.jar文件关联被改到了压缩软件双击变成打开压缩包二是.js文件关联到了某个编辑器Windows 内置脚本引擎被绕过。解决方式分别是命令行java -jar指定安装包全路径启动.js关联问题按文档给的系统帮助链接恢复默认关联或者临时把编辑器关联改回系统脚本宿主。这个问题不影响 DataCleaner 运行只影响安装向导里的脚本步骤急的时候可以直接跳过向导把许可文件手工复制到~/.datacleaner。5.2 运行期堆内存、驱动与类型推断现象一Analyze 阶段进度条走到一半卡住随后报内存溢出。原因是主键检查、值分布这类组件要在内存里建哈希表默认堆装不下宽表。解决办法是改.l4j文件里的-Xmx按数据去重后 key 体积的两倍估算改完重启客户端。现象二连库时报驱动类找不到或者连上了但读不到表。原因是驱动 jar 没放对目录或者驱动版本和数据库不匹配。解决办法是按 4.4 节的路径放驱动并重启版本对不上就换官方推荐版本。现象三数字列被当成字符串数字分析器直接跳过。原因是 source section 里的列类型写死成 STRING或者源文件该列混入了非数字字符千分位逗号、货币符号。解决办法是先跑字符串分析器和字符集分布确认混入了什么再决定是在 Transform 阶段清洗还是改列类型。别直接强转强转失败的行会变成 null空值率突然升高会让你误判源数据质量。5.3 分布式Hadoop 接口不是万能加速键现象把桌面端跑得动的 job 提交到 Spark 上报组件不支持或者结果和单机不一致。原因是 Hadoop/Spark 接口有明确的能力边界不是所有组件都能分布式执行依赖全量数据排序或单机内存结构的分析器在集群上要么退化要么直接不支持。解决办法是先查文档 15.5 节的接口限制清单把 job 拆成两段能在集群上跑的清洗和聚合放集群必须单机全量的主键检查、模式发现放回桌面或单独的小规模任务。我一般的流程是桌面端用 5% 样本把组件链和参数调稳再上集群跑全量两边结果做行数和关键指标对账差异超过阈值就回退查组件兼容性。5.4 配置期改了同义词不生效现象同义词目录文本改了重新跑 job 输出还是旧映射。原因是桌面端对参考数据有缓存job 运行期间不会重新读文件。解决办法是关掉 job 重新打开或者重启客户端用 CLI 跑的话每次都是新进程不存在这个缓存问题这也是我把定时任务全部走 CLI 的原因之一。5.5 落盘期输出文件行数对不上现象清洗后 CSV 行数比源少很多但组件状态全绿。原因通常是某个过滤器把行筛掉了却没单独记录或者 JavaScript 转换器返回 null 后被下游 Not null 过滤器拦截异常行没有落到独立输出。解决办法是给每个过滤器加一个拒绝行输出分支写到单独的 CSV跑完对比三个文件的行数源行数 通过行数 拒绝行数。这个等式对不上就是中间有组件悄悄改了行数。6. 让 C# 项目把 DataCleaner 当清洗引擎CLI 参数化与结果对账最后落到跨语言调用。官方文档没有 .NET 绑定桌面端是 Java 生态所以 C# 项目里最常见的做法是用Process调 CLI把 job 文件当契约输入输出都走文件或数据库。这条路不优雅但稳定且不用把 JVM 嵌进 .NET 进程。6.1 CLI参数化 job 与动态重写CLI 的核心能力是执行分析 job、列出数据存储和可用组件、参数化 job、动态重写配置元素。参数化是关键把输入路径、输出路径、日期分区做成占位符C# 侧每次调用传不同值不用改 job 文件。# 执行一个参数化 job传入输入输出路径参数名以 -help 输出为准 java -jar DataCleaner-console.jar \ -job jobs/clean_customer.xml \ -prop inputFile/data/in/customer_20240101.csv \ -prop outputFile/data/out/customer_clean_20240101.csv \ -prop runDate2024-01-01-job指定 job 文件-prop按 keyvalue 传占位符job 文件里用对应变量引用。第一行末尾的反斜杠是换行续写Windows 的 cmd 里换成^PowerShell 里用反引号。退出码要检查0 表示执行完成非 0 表示配置或运行错误具体错误看标准错误输出。6.2 C# 侧进程调用与退出码using System.Diagnostics; var psi new ProcessStartInfo { FileName java, Arguments -jar \C:\\\\dc\\\\DataCleaner-console.jar\ -job \jobs\\\\clean_customer.xml\ -prop inputFileD:\\\\data\\\\in\\\\customer.csv -prop outputFileD:\\\\data\\\\out\\\\customer_clean.csv, RedirectStandardOutput true, RedirectStandardError true, UseShellExecute false, CreateNoWindow true }; using var p Process.Start(psi)!; string stdout p.StandardOutput.ReadToEnd(); string stderr p.StandardError.ReadToEnd(); p.WaitForExit(); if (p.ExitCode ! 0) { // stderr 里通常有组件名和失败原因直接落盘便于排查 File.WriteAllText(dc_error.log, stderr); throw new InvalidOperationException($DataCleaner 退出码 {p.ExitCode}); }逻辑说明RedirectStandardOutput/Error把子进程输出接回来UseShellExecutefalse才能重定向CreateNoWindow避免弹黑框。WaitForExit之后读退出码非 0 就把 stderr 落盘。参数上要注意路径转义C# 字符串里的反斜杠要么双写要么用逐字字符串...路径里有空格必须加引号否则 java 会把空格当参数分隔。6.3 验证三个对账指标CLI 返回 0 只代表进程正常结束不代表数据对。我固定对三个指标输出行数与源行数的比例、关键列空值率、主键重复数。三个指标和基线偏差超过 5% 就回查 job 变更记录。指标计算方式基线来源偏差处理行数保留率输出行数 / 源行数上一次成功批次低于阈值查过滤器关键列空值率空值行数 / 总行数同列历史分布突增查转换脚本主键重复数分组计数大于 1 的组数应为 0非 0 查去重键那张对账表我放在 C# 调度程序里每批跑完自动算一遍结果写进批次日志。有次上游改了手机号字段的格式JavaScript 转换器的正则没跟上行数保留率从 92% 掉到 61%就是靠这张表在业务方发现之前拦下来的。从那以后我每次接新的清洗任务都先用 1000 行样本跑通 CLI 调用和对账再放开全量——这个习惯救过我很多次。希望帮到你。本文还有配套的精品资源点击获取
