生态工具中的数据类型保真¶
连接成功或行数一致,并不能证明 ETL 链路保留了完整数值。需要分别检查源值、连接器元数据、中间表示和目的端值。将高精度小数保存为文本可以保留数值,但不意味着中间引擎支持原生高精度小数运算。
定义数值验收规则¶
记录 MatrixOne 版本或提交、源系统版本、驱动和工具版本、SQL 模式、会话时区以及输入与目的表结构。说明链路使用默认类型推断还是显式映射,并分别验证读写方向。
加载前,为各字段确定验收规则:整数或小数精确值、二进制逐字节一致、时间值与精度,或明确的浮点容差。JSON、SET 成员和 CHAR 尾空格的归一化也需要说明。保留原始值及归一化后的表示,避免比较过程掩盖类型转换。
选择显式映射¶
SQL 值 |
中间表示 |
验收规则 |
|---|---|---|
精度超过 38 位的 DECIMAL |
支持声明精度的小数类型,或显式十进制文本列 |
保留符号、声明的小数位和每一位有效数字,不经过 float64。 |
BIGINT UNSIGNED |
uint64、足够宽的小数或精确整数文本 |
包含 |
BIT(64) |
uint64、明确字节序的二进制或精确十进制文本 |
检查高位及全 1 值,单独保留 NULL。 |
FLOAT 与 DOUBLE |
分别为 float32 与 float64 |
记录容差; FLOAT 的六位有效数字验收不等于位级一致。 |
BINARY、VARBINARY 与 BLOB |
二进制或明确解码的 HEX |
比较字节长度与内容,包含 |
负值或超过 24 小时的 TIME |
有符号整数微秒或精确 SQL 时间文本 |
保留符号及小数秒; 仅表示一天内时刻的对象无法覆盖完整时长范围。 |
DATE 与 DATETIME |
覆盖输入范围和精度的表示 |
检查年份边界及微秒,不假定 DataFrame 时间戳覆盖全部 SQL 日期。 |
TIMESTAMP |
时区约定明确的时间戳 |
记录源和目的会话时区及 UTC 转换; DATETIME 测试不能代替 TIMESTAMP 验证。 |
CHAR |
尾空格策略明确的文本 |
空格有业务含义时保留原始字节,SQL 比较语义可能不同于逐字节相等。 |
ENUM 与 SET |
明确的成员文本或约定表示 |
区分 NULL、空串和空集合,说明 SET 成员顺序和枚举域约束。 |
JSON |
JSON 文档或精确文档文本 |
区分 SQL NULL、JSON |
UUID |
原生 UUID 或校验后的 UUID 文本 |
CHAR(36) 测试不能代替 MatrixOne UUID 类型或驱动默认 UUID 推断验证。 |
Unicode 文本 |
归一化策略明确的 UTF-8 文本 |
包含非 ASCII 文本、emoji、引号、分隔符和换行。 |
SQL 类型行为见 DECIMAL、JSON、SET 和 UUID。实际限制取决于服务端版本以及链路中的每个中间引擎。
精确小数¶
支持 DECIMAL256 的服务端可使用精确文本输入,回读后不要转换为二进制浮点数:
SELECT CAST('9007199254740993.123456789012345678901234567890' AS DECIMAL(65,30)) AS exact_value;
结果应保留原值和 30 位小数。Python 适配器使用 decimal.Decimal 时,应在每个工作线程中设置足够的精度; 适用于普通金额的上下文可能会舍入 65 位数值。
无符号整数¶
SELECT CAST('18446744073709551615' AS UNSIGNED) AS unsigned_value;
结果应保持精确整数。构造 DataFrame 或复制表结构前,同时检查驱动返回值与反射类型。CAST 为文本的读取可以保留值,但不能证明默认元数据推断正确。
二进制¶
SELECT HEX(UNHEX('0000FF80')) AS binary_hex;
期望结果为 0000FF80。HEX 是显式传输编码,与目的端比较前需要还原为二进制。
SQL 时长¶
SELECT CAST('-37:00:00.000001' AS TIME(6)) AS negative_duration;
结果表示负 37 小时再减一微秒。使用整数微秒时,应计算完整的有符号时长,不只读取语言时长对象中的正秒数组件。
JSON null 与无效空文本¶
SELECT JSON_VALID('null') AS valid_json_null, JSON_VALID('') AS valid_empty_document;
期望标志分别为 1 和 0。JSON null 是有效文档,必须与 SQL NULL 分开保留。需要测试连接器 CSV/JSONLines 的空值标记,不假定空字段含义相同。
加载后检查数值¶
保存包含稳定主键和边界值的确定性源数据。
经实际工具 API 读取,记录类型、NULL 处理和显式转换。
经预定 sink 写入,使用新连接完整回读目的端。
比较主键集合、行的重复次数及所有字段。计算数量和哈希前,明确定序和带类型的编码。
在分批、并行分区、重试和模式变更后重复检查,保留失败输入和中间文件供排查。
还需要检查不合法输入:JSONLines 最后一条不完整记录、小数溢出、不合法枚举成员或越界 TIME 应产生明确结果。作业成功不能掩盖静默丢行。
区分组件与服务端问题¶
在类型范围重叠时,使用相同逻辑值执行最小 SQL 探针与 MySQL 对照。文件格式或 Arrow 转换问题尽可能在不连接数据库时复现。尝试适配前保留原始错误。
历史兼容性报告包括 Arrow/Parquet 映射、UInt64 元数据、空 ENUM/SET 文件加载和小数解析。应检查受影响版本和修复可用性,不将 issue 链接解释为所有当前版本都有该问题。