JSON埋点表迁移Apache Doris VARIANT列实战指南
先说结论:这次迁移本身没花多少时间,真正花时间的是后面一个接一个的报错。如果你正准备把线上的 JSON 埋点表迁到 Apache Doris 的 VARIANT 列,我的建议是先别急着把 DDL 写完,把本文这几个坑看完再动手。
事情的起因很简单。我们有一张线上埋点表,从上线第一天起就把客户端上报的 JSON 原文塞进一个 STRING 字段,靠上游应用层做 JSON 解析后再灌入明细表。这套方案撑了两三年,数据量上来之后问题越来越明显:JSON 字符串本身就是银弹,存是能存,但查询侧每次要调 GET_JSON_STRING 去解析,过滤条件下推不了,存储成本还常年比同量级的结构化表高出 30% 以上。加上埋点字段是运营和算法团队动态加进来的,一个月能改两三次 Schema,用普通列模型根本追不上迭代速度。
换到 Doris 2.1 之后的 VARIANT 类型,正是冲着这两点来的。VARIANT 内部按 JSON 的动态结构做稀疏列存,不需要预先定义子字段,写进去之后还能把内层字段物化成可下推的列参与过滤。听起来很完美,实际迁移时踩到的坑比想象中多得多。这篇文章按我的真实排错顺序来写,把从建表、导入、Schema 变更到查询优化的完整过程捋一遍,重点放在那些报错信息背后到底发生了什么。
1. 为什么要把 JSON 埋点表搬进 VARIANT 列
1.1 旧方案里 JSON 埋点表的三重尴尬
先描述一下我们原本的表结构,方便后面说清楚迁移动机。埋点表简化后大致是这样的:
event_body 存的是完整的上报 JSON,可能长这样:
看起来没啥问题,实际用起来全是问题。
第一重尴尬是查询性能。要统计某个 props.button_id 的点击量,旧写法只能这样:
这相当于每一行都做一次完整 JSON 解析,扫全表的时候 CPU 开销非常大。数据量到了千万级还能忍,到亿级之后一个简单查询动辄几十秒,分析侧同事直接投诉。即使 Doris 对 GET_JSON_STRING 有优化,它本质还是运行时解析,没法像原生列那样做索引和 min/max 过滤。
第二重尴尬是 Schema 变更。业务方每加一个字段,都要走一遍 ALTER TABLE 加列流程。埋点组三天两头提需求,DBA 疲于奔命。更麻烦的是历史数据没有这个字段,查询的时候还得写 COALESCE 兜底,SQL 越写越长。
第三重尴尬是存储成本。JSON 文本里的字段名重复出现,比如一百个 "user" 键就存一百次字符串。相比列式存储的高压缩比,纯 STRING 存 JSON 的存储浪费在高基数字段上尤其明显。
1.2 VARIANT 能做什么,做不到什么
VARIANT 的基本定位是:在列式存储里塞一个动态的文档结构,子字段可以随写入自动扩展,同时尽量把子字段物化到独立列空间,让查询能够直接命中。
这套机制对我们这种“高度动态但绝大多数场景还是按几个固定字段过滤”的埋点表非常合适。预先只定义几个必要字段,其余全部交给 VARIANT,业务侧加字段不再需要 DDL,查询侧用点号就能取内层属性,过滤条件下推成为可能。
但要泼一盆冷水:VARIANT 不是万能的,至少有三件事它做不好。
一是超深嵌套的 JSON。如果埋点里有个十层深的递归结构,VARIANT 虽然能存,但每次路径提取的开销都不低,性能会退化到接近原始 JSON 解析。二是超高基数长字符串:VARIANT 对字符串类型的支持依赖默认长度上限,超长文本会触发截断策略,后面我会专门讲这个坑。三是强事务场景:VARIANT 列更多是面向分析读写,不适合做成频繁单行更新的业务主表。
搞清楚这些边界之后,我们再回头设计迁移方案。核心原则是:能下沉到普通列的就用普通列,没法稳定预定义 Schema 的才交给 VARIANT。比如 user.id 这种每个埋点几乎都有的字段,直接建成 BIGINT 列,props 这个最常变的部分放进 VARIANT。
2. 迁移前的表结构和 Schema 设计:先想清楚再建表
2.1 用 VARIANT 还是 JSONB:先搞清楚这两者的边界
Doris 里和 JSON 相关的类型容易混,至少有三个:JSON、JSONB、VARIANT。实际迁移前必须分清它们。
JSON 类型偏向传统 JSON 语义,内部按 JSON 格式存放,适合需要严格 JSON 行为的场景,但查询和写入的通用性不如另外两个。JSONB 是二进制 JSON,适合需要频繁读取和转换、但结构相对稳定的数据。VARIANT 则更激进,它把 JSON 当列式结构处理,写入时自动做类型推断,把子字段拆成真正的列,而不是保留一个整体二进制块。
对埋点这种“结构频繁变化,但每次只需要过滤其中几个固定子字段”的场景,必须选 VARIANT。JSONB 保留了完整的文档语义,却没法把内层字段真正下推到列存层,过滤性能提升有限。VARIANT 就能做到。当然,代价是写入解析开销比 JSONB 略高,因为引擎需要做一次类型推断和列物化。
2.2 建表语句:我的第一版 DDL 和踩坑起点
我的第一版 DDL 是这样的:
看起来干净利落,实际用起来在导入环节就摔了跟头。先说两个没踩到的地雷,给各位提个醒。
第一,VARIANT 不能用作表的关键列。也就是说,你不能把它放在 DUPLICATE KEY、UNIQUE KEY 或 AGGREGATE KEY 里。这其实是合理限制:VARIANT 的子字段是动态变化的,没法稳定参与 Key 去重或排序。万一有人不小心把 VARIANT 放进 Key,建表阶段就会直接报错。
第二,分桶字段最好选稳定的普通列。event_id 是天然的分布键,但如果你打算用 VARIANT 内层字段做分桶,目前并不支持,在建表阶段就限定死了。
第一次导入用的是 Stream Load,命令大概是:
问题来了。jsonpaths 里写了三个字段,但实际 JSON 顶层只有 event_id 和 event_time,event_body 并不是一个顶层字段名,而是整个剩余对象的别名。这里 Doris 的解析行为和很多人预期的有差异:如果 jsonpaths 和 columns 同时声明,引擎会严格按照 jsonpaths 去抓对应路径,而不是“把剩下所有 JSON 塞进 VARIANT”。
这直接导致了第一类报错。后面我会专门展开排错链路,这里先强调一个设计原则:给 VARIANT 喂数据时,要么用其对应的 $.event_body 路径,要么干脆不走 jsonpaths 动态映射,让引擎直接把整行 JSON 作为 VARIANT 写入。
我最终采用的方案是在 columns 里显式映射:
同时去掉 jsonpaths,导入的 JSON 里顶层字段如果是 event_body,则直接流入 VARIANT 列。这样最直观,也最好排查。
3. 核心排错:从 Stream Load 报错到数据错乱的完整链路
3.1 第一处卡点:jsonpaths 和 VARIANT 字段的路径冲突
先说最典型的报错。导入时返回类似:
第一次看到这个报错时我也愣了一下。检查一遍,event_body 明明就在 jsonpaths 里,怎么就不让访问了?
排查链路是这样走的。第一步,先去掉 jsonpaths,只保留 format=json 和 columns 映射,导入成功。这说明数据本身没问题。第二步,保留 jsonpaths,把 event_body 的路径改成 $.props 这类深路径,结果成功导入。所以问题只出在“用 jsonpaths 指向顶层字段 + VARIANT 列”的组合上。
根因在于 Doris 的 Stream Load 解析流程中,jsonpaths 一旦指定,引擎会按路径逐一定位字段,再按 columns 顺序填充。VARIANT 列在生成时接收到的并不是“整个 JSON 文档”,而是 jsonpaths 定位到的那一小段值。当 $.event_body 被解析为顶层成员时,与引擎内部的 JSON 解析短路逻辑发生了冲突,导致无法正确构造 VARIANT 对象。
我的处理方式是:VARIANT 列不放进 jsonpaths,只在 columns 里声明,同时保证导入 JSON 的顶层确实包含了对应字段名。这样既拿到动态结构,又绕开了路径冲突。对于深路径的内层字段,如果你确实想单独抽出来做普通列,可以保留 jsonpaths,但 VARIANT 列必须避免出现在 jsonpaths 中。
3.2 第二处卡点:failed to parse json 的真实原因——类型推断分歧
绕开第一处之后,导入开始报类型解析类的错误。具体格式是:
这类报错信息很模糊,只说“unexpected token”,具体什么 token、为什么 unexpected 完全没讲。只能从数据侧下手。
我导了一批线上真实埋点日志。排查过程中发现,数据里有大量这样的 JSON:
注意 duration_ms 这个字段,一部分日志里它是数字:
另一部分日志里它是空字符串:
VARIANT 写入时会做动态类型推断。字段第一次出现是数字,引擎把它推断成整数类型;后面来了一行空字符串,类型推断器在数字列里遇到字符串值,直接丢出 unexpected token。这就是报错的本质:不是 JSON 格式不合法,而是动态 Schema 内部类型冲突。
处理办法有两个思路。第一个是源头治理,要求业务侧统一字段类型,空值用 null 而不是空字符串。第二个是导入侧兜底:对这类字段做预处理,把空字符串统一替换成 null,或者把数字和字符串统一 CAST 成字符串。由于我们线上数据已经混了几亿行,源头治理一时半会儿改不动,最终在 Flink 清洗层加了一步:对 duration_ms 这类已知易变字段做统一 CAST 为 DOUBLE,空字符串全部转 0。这里的教训是:给 VARIANT 建动态 Schema 之前,最好先跑一次数据探查,把字段类型分布摸清楚,别盲信“纯动态、零维护”。
3.3 第三处卡点:大小写敏感性导致的动态 Schema 分裂
这一处没有显式报错,但事后看数据上发现字段查询结果对不上。现象是:某几个查询用 event_body.props.BUTTON_ID 取不到值,但同一行 JSON 里明明有 BUTTON_ID 字段。直接用 SELECT 查原 JSON 时数据显示正常。
通过 DESC event_log_var; 查看动态 Schema 时,发现同时存在 props.button_id 和 props.BUTTON_ID 两个子字段。根源在于:上游团队某个版本误把字段名从小写改成了大写,而 VARIANT 的动态 Schema 是按字段名精确匹配的,大小写不同会被视为两个不同字段,各自物化成独立列。
这类问题的隐蔽性极强,因为它不是写失败,而是数据写成功了,但查询侧按小写/大写访问时各自只能命中一部分列,导致统计结果偏小。我用一个对比查询定位了问题:
运行后发现两个 count 都存在且都不等于 total。此时已经可以断定 Schema 分裂。修复方案是统一字段命名规范,并在 Flink 清洗层对 JSON 里的 key 做一次 toLowerCase 归一化。Doris 侧不提供对 VARIANT 字段名的大小写折叠,所以只能在写入前动手脚。
3.4 第四处卡点:超长字段触发解析和存储瓶颈
这是最棘手的一处。某一类日志的 props 下面带了一个完整 SDK 配置快照,单行 JSON 大小超过 8MB。Stream Load 导入时直接报:
一开始以为是 Stream Load 单行限制,调大了 max_body_bytes 没用。继续排查发现,问题出在 VARIANT 的字符串字段长度限制上。VARIANT 在实现上对字符串子字段有默认的最大长度,超过这个限制会拒绝解析或截断。
这个限制可以通过 BE 侧的配置项调整。我们当时的处理是两步走:
- 先在 FE 侧修改 session 变量,把 VARIANT 字符串上限提到 1MB;
- 再把确实超长的数据在清洗层拆分为多个 JSON 对象,避免单字段过大。
改完配置后再导入,超长字段能正常写入了。但这个方案有代价:字符串上限越大,VARIANT 内部为之预留的空间越大,列存压缩率和扫描性能都会受影响。我的建议是不要把上限当成万能钥匙,能拆字段就拆字段。经过这一轮调整,我们的线上导入终于稳定了。但迁移到这一步还只是“能写进去”,查询侧的优化和验证才是另外一场硬仗。
4. 迁移后的查询与验证:VARIANT 不是存进去就完事
4.1 点号提取、数组访问和 CAST 的坑
VARIANT 查询最直接的语法是用点号连续取路径:
刚开始查旧数据时感觉还行,但很快就遇到了第一个小坑:当路径中间的某个节点是数组时,点号语法直接失效。 比如有一个埋点结构是这样的:
想查 item_id,直觉会写成 event_body.list.item_id。实际不行,VARIANT 的路径语法不支持对数组自动展平,必须显式用下标,或者配合 JSON_EXTRACT 来做。我的写法改成了:
注意,如果你只需要取某个固定下标:
这个写法是支持的。但如果下标是动态的,比如取 list[某个参数],点号路径就不好处理了,建议直接回到 JSON_EXTRACT 函数。
另一个容易忽略的是 VARIANT 内层数值的默认类型。JSON 里的整数在 VARIANT 中默认按最窄的整数类型存,如果一开始是 INT,后续写进了 BIGINT 范围的值,动态类型会自动提升。问题在于查询时如果不做 CAST,引擎按提升后的类型返回结果,可能与你 WHERE 条件里的参数类型不匹配。
例如:
如果 VARIANT 里 user.id 被推断为 BIGINT,而常量 10086 被推断为 INT,这场比较在部分版本下会触发隐式转换,性能损耗不小。更稳妥的写法是显式 CAST:
4.2 空值语义和 IS NULL 判断的坑
这是查询侧最隐蔽的坑。VARIANT 里的 null 和 SQL 层面的 NULL 不完全是一回事。JSON 里显式写 "key": null,在 VARIANT 类型推断后会被当作 SQL NULL 处理吗?实际测试发现取决于具体字段的类型推断结果。
如果整个子字段从未出现过非空值,那它确实可以被视为 NULL。但如果这个字段在同一列的其他行里是数字 0,那 JSON 里的 null 在查询时可能不会走 SQL 的 IS NULL 判断。我一度用 WHERE event_body.user.id IS NULL 来过滤缺省数据,结果统计结果明显偏少。
排查之后发现问题出在类型推断:user.id 在这个分区里被认为是 DOUBLE,JSON 里的 null 被解释成了 DOUBLE 的缺失值,而 SQL 的 IS NULL 只能命中那些真正没有写入过该路径的行。最终调整策略,判断缺省用 JSON_CONTAINS_PATH:
这样更可靠,但注意扫描成本比单纯的点号判断要高。对于高频过滤字段,我的建议是在清洗层显式补齐为 0 或空串,不要让 null 语义在生产查询中到处裸奔。
4.3 性能验证:从 40 秒到 3 秒的实测对比
迁移不是写完 DDL 就结束,查询性能必须做前后对比。我们挑了一个最典型的埋点统计需求:“统计某天所有点击事件中 button_id 为 tab_reco 的数量,并按 user.level 分组”。
旧表跑一次:
在全量扫描 2 亿行的前提下,这个查询跑了 40 秒左右。VARIANT 表重写:
跑完是 3 秒出头。这个提升主要来自两点:一是过滤条件被下推到 VARIANT 物化列上,不需要全表逐行解析 JSON;二是在 GROUP BY 时直接用了列存里的整数类型,省去了运行时字符串转换。夸张吗?确实是这个量级。但如果你的查询每次都要点号提取超深路径、又每个值都需要临时解析,那性能可能不会比旧方案好太多。
5. 回填与增量链路:从老表到新表的平滑过渡
5.1 历史数据的回填策略
新表建好、导入链路打通后,接下来要处理几亿行历史数据。常用方案有三种,我说下各自在我这个场景里的实际取舍。
第一种是 INSERT INTO SELECT,直接从旧表把 STRING 字段 CAST 成 VARIANT。这个方案最简单,但注意 CAST 的细节:必须是合法 JSON 字符串,不能是普通文本,否则运行时报错。我们旧表里存在不少脏数据(截断的半截 JSON),所以回填之前先做了一次预处理扫描,把非法 JSON 全部过滤掉。
第二种是 BACKUP/RESTORE 跨库迁移。如果你只是想把表整体搬过去,这个更省事,但没法做数据类型转换,基本用不上。
第三种是离线批量导出再 Stream Load 导入。我们在数据量较大时采用这种方式,因为可以精确控制并发和错误容忍度,中间断了还能续传。
回填过程有一个值得注意的细节:回填时的 VARIANT 类型推断会影响后续所有增量数据的物化方式。 比如历史数据里某个字段全是字符串,但增量数据后来变成了数字,VARIANT 会尝试做兼容性升级。如果升级失败,就会像第 3.2 节那样报 failed to parse json。所以回填前最好对高频字段做一个类型探查,能用统一类型就统一。
我们当时的做法是写了一个简单的探查 SQL:
把所有高频过滤字段都过一遍,把类型分布摸清楚,再决定清洗策略。回填本身我建议分批跑,比如按天分区逐批插入,每批完成后用行数校验:
5.2 增量链路双写与校验
历史数据回填完成后,增量链路需要无缝切换。我们评估了两种写法。
如果是 Routine Load 直接消费 Kafka,最自然的做法是新建一个订阅任务指向 VARIANT 表,在 jsonpaths 和 columns 上避开 VARIANT 路径,其余字段正常映射。这里要注意:切换 Routine Load 前先在测试环境用最近几小时的 Kafka 消息做回放验证,确认没有第 3.2 节的类型冲突报错。
如果是代码层写入,我的建议是做一段时间的双写:同时写旧表和新表,两边的数据用离线任务每天对账。
对账方案可以这样写:
然后用旧表侧同样口径的查询做全量比对。比对字段不用太多,选每个业务最关心的三个维度加一个计数即可。双写持续三到五个工作日,确认没有系统性偏差后,再切到单写新表。
5.3 一个容易被忽略的清理事项
切换完成后,旧表不要急着删。我们留了 7 天窗口期,用来应对突发的数据订正请求。同时,由于 VARIANT 表的动态 Schema 会随着新字段写入不断扩展,建议对高频变动的埋点字段做一次命名规范审查,把混用 camelCase 和 snake_case 的写法彻底统一。这一步不解决的话,过两个月你会在动态 Schema 里看到一堆长得差不多的字段名,查询的人根本分不清谁是谁。
6. 这次排错沉淀下来的几条经验
最后说几条我用真金白银换来的经验,不一定系统,但对做这类迁移的人应该有用。
第一条,VARIANT 不是“零 Schema 维护”。 它确实省去了频繁 ALTER TABLE 的麻烦,但动态类型推断、字段大小写、null 语义、字符串长度上限这些隐形成本都存在。迁移之前,先花一天时间做数据探查,比上线后熬夜排查报错划算得多。
第二条,导入链路的 jsonpaths 和 columns 要分开理解。 VARIANT 列不要强行塞进 jsonpaths,尤其是路径指向顶层字段时,触发解析冲突的概率很高。把 VARIANT 留给 columns 声明,让引擎自己根据 JSON 顶层键构造。
第三条,动态 Schema 的“动态”体现在扩展上,但类型一旦推断成型,就很难自动回退。 前几个月全是一致的数据类型,不代表后面不会混入脏值。清洗层加一道类型归一化,能挡掉绝大多数 failed to parse json 报错。
第四条,性能优化要分层看。 不是所有查询都适合点号路径,点号取超深路径未必比 JSON_EXTRACT 快。高频过滤字段最好在清洗层显式转成普通列,VARIANT 只兜底那些低频、易变、结构不稳定的字段。想要最优查询性能,就别把鸡蛋全部放进 VARIANT 一个篮子里。
这次迁移从设计到稳定运行,前后花了两周多,单排错环节就占了一半时间。回头再看,如果把数据探查和字段命名规范放在第一步,至少能省下三到四天的排查时间。以后再有类似的表要迁,我会严格按照这套流程来:先探查类型分布,再设计普通列与 VARIANT 列的比例,然后小流量验证导入链路,最后才做全量回填和增量切换。