Vega Nest Transform 详解:用字段分组把扁平数据转换为树形结构
Vega Nest Transform 详解:用字段分组把扁平数据转换为树形结构
导读
nest 是 Vega 中用于构建层次结构(树)数据的核心变换:它接收一张扁平的输入数据表,根据一个或多个字段的不同取值把数据对象逐层分组,最终生成可供 tree、treemap、pack、partition 等树布局变换直接消费的树节点对象。读完本文你将掌握 nest 的 keys 与 generate 两个参数的完整语义、输出数据结构(含内部节点与查找表)的细节,以及如何把它与其他层次布局变换串联成一个可运行的 Vega 规范。
一、什么是 nest 变换
在 Vega 中,很多布局变换(如 tree、treemap、pack、partition)都要求输入为层次结构数据,而日常业务数据往往是扁平的记录数组(例如每人一条职业、地区记录)。nest 变换的作用正是填补这道鸿沟:它不改变叶子数据的属性,而是依据字段取值把数据对象组织成一棵虚拟树,树上的每个节点通过 values 引用其子节点。
从源码元数据可以看出它的身份定位,见 packages/vega-hierarchy/src/Nest.js:
Nest.Definition = {
'type': 'Nest',
'metadata': {'treesource': true, 'changes': true},
'params': [
{ 'name': 'keys', 'type': 'field', 'array': true },
{ 'name': 'generate', 'type': 'boolean' }
]
};
其中 treesource: true 表示该变换是“树数据源”,即它会为输出数据流附加一个树根(root),供下游布局变换取用;changes: true 表示它会直接产出增删变更(rem/add),而不是完整重写数据流。这两个元数据是理解 nest 与 tree 等布局协同工作的关键。
二、变换参数
| 属性 | 类型 | 描述 |
|---|---|---|
| keys | Field[] | 用于把数据对象组织成树的字段数组。数据对象首先按数组中第一个字段的取值分组为兄弟节点;随后对每个组内继续按第二个字段分组,形成更深一层;依此类推。若未指定,所有数据对象将被视为一组兄弟节点。 |
| generate | Boolean | 布尔标志,默认 false。表示本变换生成的非叶子节点是否应被包含在输出数据流中。默认情况下输出流中只包含原始输入数据对象(叶子节点)。若包含非叶子节点,需要注意它们与输入对象的属性集合不同:生成的内部节点带有 key 属性,其值对应于 keys 参数提取出的分组值。 |
几点源码层面的补充:
keys在 Nest.js 中被声明为'type': 'field', 'array': true,即既支持字段名也支持表达式,且总是按数组处理;即便只传一个字段,也会被归一化为数组(源码中通过array(_.keys)处理)。generate只影响输出数据流的内容:叶子数据始终在流中,内部节点是否出现由该开关决定。- 若没有上游数据源,变换会直接报错(
error('Nest transform requires an upstream data source.'),见 Nest.js),因此 nest 必须挂在某个 data 或 collect 变换之后。
三、基础用法与逐层分组过程
最典型的配置如下:
{
"type": "nest",
"keys": ["job", "region"]
}
它的执行过程是:从根节点出发,先按 job 字段的每个不同取值生成一组兄弟节点;然后在每个 job 组内再按 region 字段的不同取值生成一层兄弟节点;最后,组内的所有原始数据对象作为叶子节点挂载。
例如给定如下输入数据:
[
{"id": "A", "job": "Doctor", "region": "East"},
{"id": "B", "job": "Doctor", "region": "East"},
{"id": "C", "job": "Lawyer", "region": "East"},
{"id": "D", "job": "Lawyer", "region": "East"},
{"id": "E", "job": "Doctor", "region": "West"},
{"id": "F", "job": "Doctor", "region": "West"},
{"id": "G", "job": "Lawyer", "region": "West"},
{"id": "H", "job": "Lawyer", "region": "West"}
]
得到的树结构为:
/- East - [A, B]
/- Doctor -
/ \- West - [E, F]
Root -
\ /- East - [C, D]
\- Lawyer -
\- West - [G, H]
这一分组逻辑在 Nest.js 中由内置的 nest() 工厂实现:apply 递归地按当前深度的 key 用哈希表 valuesByKey 收集同值对象,entries 再把哈希表转成 {key, values} 节点数组,从而得到逐层嵌套的结构。
四、generate 参数与输出数据流
默认情况下,nest 的输出流中只有原始输入对象(叶子节点),内部节点仅作为树结构存在,不会出现在下游的 marks 数据中。这对于只关心叶子(比如把每个叶子画成一个圆点)的场景是高效的。
当 generate 设为 true 时,生成的内部节点也会被追加进输出数据流。仍以上面的 8 条数据为例,输出流将变为:
[
// 原始输入节点
{"id": "A", "job": "Doctor", "region": "East"},
{"id": "B", "job": "Doctor", "region": "East"},
{"id": "C", "job": "Lawyer", "region": "East"},
{"id": "D", "job": "Lawyer", "region": "East"},
{"id": "E", "job": "Doctor", "region": "West"},
{"id": "F", "job": "Doctor", "region": "West"},
{"id": "G", "job": "Lawyer", "region": "West"},
{"id": "H", "job": "Lawyer", "region": "West"},
// 生成的内部节点
// 根节点的 key 为 undefined
// values 数组包含嵌套的子组对象
{"values": [ ... ] },
{"key": "Doctor", "values": [ ... ]},
{"key": "Lawyer", "values": [ ... ] },
{"key": "East", "values": [ ... ]},
{"key": "West", "values": [ ... ]},
{"key": "East", "values": [ ... ]},
{"key": "West", "values": [ ... ]}
]
需要注意的细节:
- 内部节点的属性与输入对象完全不同:它们只有
key(该层分组值)和values(嵌套的子组或叶子数组)两个属性;根节点没有key,key为undefined。 - 由于内部节点没有原始字段(如
id、job、region),在 marks 编码时若按原始字段取颜色、取文本,需要自行对内部节点做条件判断。 - 源码实现见 Nest.js:只有
node.children存在的非叶子节点才会被ingest并同时推入out.add与out.source。
五、输出树结构与查找表(lookup)
无论 generate 取值如何,nest 都会在输出数据流上挂载一个 root 属性(out.source.root = tree,见 Nest.js)。这个 root 是基于 d3-hierarchy 的 hierarchy() 构建的节点对象,具有标准的树节点形态:
data:当前节点对应的数据(根节点是{values: [...]}形式的包装对象,内部节点是{key, values},叶子是原始输入对象);children:子节点数组;depth/height:节点深度与子树高度;parent:父节点引用;lookup:由 lookup.js 构建的“tupleid → 树节点”映射表。
在 packages/vega-hierarchy/test/nest-test.js 的测试中可以看到单字段 job 分组后的期望结构:根节点 depth: 0、height: 2,其下是 Doctor、Lawyer 两个 depth: 1 的内部节点,再往下是 depth: 2 的叶子节点;同时 root.lookup 把每个输入对象的 tupleid(1、2…)映射到对应的叶子节点实例。该测试还验证了两点重要行为:
- 增量更新:当上游数据被移除时,旧树中对应的叶子节点会被收集进
out.rem(Nest.js),随后整棵树重建,新节点进入out.add,因此下游变换能精确感知增删; - 空数据:输入为空时输出流长度为 0,
root.children为undefined、root.lookup为空对象(见 nest-test.js),不会报错。
六、与树布局变换串联:一个完整示例
nest 本身只负责“造树”,布局工作要交给下游的 tree / treemap / pack / partition 等变换。仓库中的示例规范 docs/docs/transforms/nest.vg.json 展示了完整链路:
{
"name": "tree",
"values": [
{"id": "A", "job": "Doctor", "region": "East"},
{"id": "B", "job": "Doctor", "region": "East"},
{"id": "C", "job": "Lawyer", "region": "East"},
{"id": "D", "job": "Lawyer", "region": "East"},
{"id": "E", "job": "Doctor", "region": "West"},
{"id": "F", "job": "Doctor", "region": "West"},
{"id": "G", "job": "Lawyer", "region": "West"},
{"id": "H", "job": "Lawyer", "region": "West"}
],
"transform": [
{"type": "nest", "generate": {"signal": "generate"}, "keys": ["job", "region"]},
{"type": "tree", "method": "tidy", "size": [{"signal": "width"}, {"signal": "height"}]}
]
}
该示例的完整结构是:
nest先把扁平数据组织成树(keys: ["job", "region"]),generate通过一个复选框信号动态切换;tree变换(method: "tidy")基于 nest 产出的root计算每个节点的x、y布局坐标;- 另建一个
links数据集,对tree数据做treelinks+linkpath变换生成连接线路径; - 最后用 path mark 画连接线、symbol mark 画节点、text mark 标注 id。
这也解释了为什么 treelinks 变换可以直接消费 nest 的输出:因为 nest 的每个叶子都保留了原始对象的 tupleid,treelinks 依赖 parent / children 引用关系生成边,而查找表保证了叶子与原始数据的一一对应。
七、与其他层次数据变换的关系
在 packages/vega-hierarchy/index.js 中,nest 与 pack、partition、stratify、tree、treelinks、treemap 同属 vega-hierarchy 包:
- nest:从扁平数据 + 分组字段构建树(自顶向下分组,本文主角);
- stratify:从已含父子关系字段的扁平数据构建树(如
parent/key两列); - tree / treemap / pack / partition:消费 nest 或 stratify 产出的树根,完成具体布局计算。
因此,选择哪个“造树”变换取决于数据形态:数据里有显式的父子键用 stratify;数据只有分类字段、想按取值层级分组,就用 nest。
八、使用建议与注意事项
- keys 的顺序即树的层级顺序:第一个字段是最高层分组,最后一个字段是最深层分组;字段数量决定了树的深度(叶子深度 = keys 数量)。
- 叶子数据永远保留:
generate只控制内部节点是否进入输出流。若你的可视化只需要叶子(如散点式树图),保持默认false即可减少数据量。 - 内部节点与叶子属性不同:开启
generate后,标记编码时需注意内部节点只有key/values,没有原始字段。 - nest 必须接在有数据源的变换之后:直接对空源使用会抛出 “Nest transform requires an upstream data source.” 错误。
- 联动使用示例:可参考 docs/docs/transforms/nest.vg.json 的“nest → tree → treelinks/linkpath”完整管线,作为 tree 布局类图表的模板;官方交互式示例
nest也内置了generate复选框便于观察开关差异。 - 单元测试参考:packages/vega-hierarchy/test/nest-test.js 覆盖了分组结构、增量增删、空数据三种场景,是理解输出结构(尤其
root.lookup)最直接的代码证据。