Vega Flatten Transform 完全指南:将数组字段展开为数据对象

原创2026-09-22 21:12:521,833 阅读
文章标签:数据可视化

Vega Flatten Transform 完全指南:将数组字段展开为数据对象

导读

flatten 是 Vega 可视化语法中用于数据重塑的核心变换之一:它把数据对象中数组类型的字段拆解为多个独立的数据对象(每个数组元素对应一条输出记录),同时保留输入对象的其余字段。本指南以 flatten 官方文档 为主体,结合 Flatten.js 源码 与其 单元测试,系统讲解 flatten 的三个核心参数(fields、index、as)、单字段/多字段/带索引三类典型用法,以及它底层基于 dataflow 脉冲(pulse)的增量计算原理。读完本文,你将能熟练地在 Vega 数据定义中把嵌套数组结构展开为适合折线图、序列图等可视化场景的平坦数据流。

一、flatten 是什么

在 Vega 中,变换(transforms) 负责对数据流进行处理——过滤、计算新字段或派生出新的数据流。flatten(自 Vega 3.1 起引入)属于"派生新数据流"这一类:它将输入数据对象中数组值字段映射为一系列独立数据对象,每个数组元素对应一条输出记录,输出对象由"提取出的数组值"与"原输入对象的所有其余字段"共同构成。

典型场景:原始数据中某个字段携带多个值(例如一个时间段内的多个时间点、一条边连接的多条链路),而可视化需要把这些值分别绘制成独立的数据点。此时 flatten 恰好能把"一行多值"转换为"多行单值",从而对接折线图、散点图等逐点编码的标记。

需要注意:flatten 只作用于数组类型的字段。如果数据对象中嵌套的是"设计时字段已知"的子对象(而非数组),则应改用 fold 或 project 变换来处理。

二、变换参数

flatten 支持以下三个参数,其类型定义与 Flatten.Definition 中的声明完全一致:

属性 类型 必填 说明
fields Field[] 是 一个或多个包含待展开数组的数据字段。若指定多个字段,它们的数组值应具有平行结构,理想情况下长度相同;若平行数组长度不一致,将按最长数组展开,缺失位置补 null。
index String 否 输出字段名,用于存放数组值的零基索引。不指定则不添加索引字段。(自 Vega 5.8 起支持)
as String[] 否 展开后的数组值所使用的输出字段名。不指定时,沿用对应数组字段自身的字段名。

从源码定义可以看出三个参数的解析规则:fields 为 field 类型且 array: true、required: true;index 为字符串;as 为字符串数组。展开输出名由 fieldNames 决定——遍历 fields,若 as[i] 存在则使用别名,否则回退到访问器的原始字段名(accessorName(f))。

三、使用示例

3.1 单字段展开

最简单的用法:展开名为 foo 的数组字段。注意输出中除 foo 以外的所有字段都会在每条输出记录中被重复:

{"type": "flatten", "fields": ["foo"]}

输入数据:

[
  {"name": "alpha", "data": 123, "foo": [1, 2]},
  {"name": "beta",  "data": 456, "foo": [3, 4, 5]}
]

结果:

[
  {"name": "alpha", "data": 123, "foo": 1},
  {"name": "alpha", "data": 123, "foo": 2},
  {"name": "beta",  "data": 456, "foo": 3},
  {"name": "beta",  "data": 456, "foo": 4},
  {"name": "beta",  "data": 456, "foo": 5}
]

可以看到:foo 数组被"摊平",原记录中的 name、data 字段完整保留并逐条重复,共输出 2 + 3 = 5 条记录。

3.2 添加索引字段

通过 index 参数可以追踪每条输出记录源自原数组的哪个位置:

{"type": "flatten", "fields": ["foo"], "index": "idx"}

该配置会为每条输出记录添加一个字段,记录其来源数组的索引位置:

[
  {"name": "alpha", "data": 123, "foo": [1, 2]},
  {"name": "beta",  "data": 456, "foo": [3, 4, 5]}
]

结果:

[
  {"name": "alpha", "data": 123, "foo": 1, "idx": 0},
  {"name": "alpha", "data": 123, "foo": 2, "idx": 1},
  {"name": "beta",  "data": 456, "foo": 3, "idx": 0},
  {"name": "beta",  "data": 456, "foo": 4, "idx": 1},
  {"name": "beta",  "data": 456, "foo": 5, "idx": 2}
]

索引是零基的:alpha 的两个元素索引为 0、1,beta 的三个元素索引为 0、1、2。索引字段常用于保留数组内的相对顺序信息,例如绘制时间序列时需要知道元素在原始数组中的先后次序。

3.3 多字段平行展开

同时展开 foo 和 bar 两个数组字段:

{"type": "flatten", "fields": ["foo", "bar"]}

给定输入数据:

[
  {"key": "alpha", "foo": [1, 2],    "bar": ["A", "B"]},
  {"key": "beta",  "foo": [3, 4, 5], "bar": ["C", "D"]}
]

输出为:

[
  {"key": "alpha", "foo": 1, "bar": "A"},
  {"key": "alpha", "foo": 2, "bar": "B"},
  {"key": "beta",  "foo": 3, "bar": "C"},
  {"key": "beta",  "foo": 4, "bar": "D"},
  {"key": "beta",  "foo": 5, "bar": null}
]

注意 beta 的记录:foo 有 3 个元素而 bar 只有 2 个,此时按**最长数组(foo)**展开,bar 的第 3 个位置缺失,补为 null。这正是文档所述"平行结构、长度可不一致、最长者为准、缺失补 null"的完整体现。

3.4 使用 as 重命名输出字段

当需要为展开后的值指定不同的输出字段名时,使用 as 参数:

{"type": "flatten", "fields": ["foo", "bar"], "as": ["x", "y"]}

上述配置会把 foo 的展开值写入 x、bar 的展开值写入 y,而非默认的 foo、bar 字段名。as 数组与 fields 数组一一对应,未指定的位置仍然回退使用原字段名(见 fieldNames)。

四、源码级原理:flatten 是如何工作的

Flatten.js 是这一变换的完整实现,整体逻辑非常紧凑,核心在 transform(_, pulse) 方法中:

transform(_, pulse) {
  const out = pulse.fork(pulse.NO_SOURCE),
        fields = _.fields,
        as = fieldNames(fields, _.as || []),
        index = _.index || null,
        m = as.length;

  // remove any previous results
  out.rem = this.value;

  // generate flattened tuples
  pulse.visit(pulse.SOURCE, t => {
    const arrays = fields.map(f => f(t)),
          maxlen = arrays.reduce((l, a) => Math.max(l, a.length), 0);
    let i = 0, j, d, v;

    for (; i<maxlen; ++i) {
      d = derive(t);
      for (j=0; j<m; ++j) {
        d[as[j]] = (v = arrays[j][i]) == null ? null : v;
      }
      if (index) {
        d[index] = i;
      }
      out.add.push(d);
    }
  });

  this.value = out.source = out.add;
  if (index) out.modifies(index);
  return out.modifies(as);
}

这段实现揭示了几个关键设计:

  1. 派生新数据流:输出通过 pulse.fork(pulse.NO_SOURCE) 创建,不从上游直接透传数据;上一次的计算结果整体放入 out.rem(removed),新展开的记录放入 out.add(added)。这意味着每次运行该算子,输出集合都会被"整体重建",这正是 metadata: {'generates': true} 的语义——该变换会生成新的数据对象。
  2. 最长数组优先:maxlen 取所有平行数组长度的最大值,因此多字段长度不一致时以最长数组为准,这与文档参数表中的说明一致。
  3. null 填充:循环内部 (v = arrays[j][i]) == null ? null : v 保证越界位置(数组较短时)写入 null,而 undefined 也会被归一化为 null。
  4. 字段派生:每条输出记录通过 derive(t) 从输入记录派生(复制非展开字段),再写入展开值和可选索引字段。
  5. 字段追踪:返回 out.modifies(as)(若指定了 index 还会 out.modifies(index)),向数据流下游声明哪些字段被修改,便于下游算子做增量优化。

五、增量更新与响应式行为

flatten 不仅支持一次性展开,还天然适配 Vega dataflow 的增量更新机制。单元测试 从三个维度验证了这一点:

  • 插入(adds):测试一在 Dataflow 中串联 Collect → Flatten → Collect,插入 {k: 'a', v: [1,2]} 与 {k: 'b', v: [3,4,5]} 后,输出恰好 5 条记录,且 fl.pulse.fields['v'] 被标记为 true——下游可以感知 v 字段的产生。
  • 修改(mods):将 data[0].v 从 [1,2] 改为 [1,9] 后重新运行,输出保持 5 条,但 v 的值相应变为 1、9——说明源数组内容变化后,展开结果会随之重建。
  • 删除(rems):移除 data[0] 后输出收缩为 3 条,全部来自 b。

平行数组场景(测试二)验证了 fields: [a, b] 按索引对齐展开;索引场景(测试三)验证了 index: 'foo' 在每个输入对象内部从 0 重新编号,且 fl.pulse.fields['foo'] 同样被标记。这为在 Vega 中构建响应式可视化(数据动态变化时图表自动重算)提供了保证。

六、真实使用案例

flatten 在 Vega 官方示例中有直接应用。以 serpentine-timeline.vg.json(蛇形时间线示例)为例,其中多处使用 flatten 把嵌套的数组字段展开为绘图所需的平坦记录:

{"type": "flatten", "fields": ["domain"]}
{"type": "flatten", "fields": ["id"]}

在该示例中,数据被组织为嵌套层级结构,通过 flatten 提取出每个节点的时间域(domain)与 id 序列,为后续的坐标映射(scale)和标记编码提供逐条记录。这印证了 flatten 在真实图表中的典型位置:位于数据定义(data)的 transform 数组内,先于 scale、mark 等下游元素执行。

如需在自己的 Vega 规格中使用,只需在数据定义的 transform 数组中声明:

{
  "data": [
    {
      "name": "table",
      "transform": [
        { "type": "flatten", "fields": ["values"], "index": "idx" }
      ]
    }
  ]
}

七、注意事项与选型建议

  1. 仅限数组字段:flatten 只对 array 类型的字段生效;若字段不是数组,其取值在展开时会因索引访问得到 undefined 并被归一化为 null。
  2. 平行数组需语义对齐:多字段展开时,各数组应保持平行结构(第 i 个元素彼此对应)。长度不一致虽然不会报错(按最长数组、缺失补 null),但可能导致数据语义错位,应仔细核对。
  3. 与 fold / project 的区别:当数据对象包含的是嵌套子对象而非数组,且字段在设计期已知时,应使用 fold(把多个字段折叠为 key/value 对)或 project(按字段子集派生新对象);flatten 只负责"数组→多行"这一种展开语义。
  4. 性能视角:由于输出集合每次整体重建(先 rem 再 add),flatten 适合数据规模适中的场景;超大数据量时应评估展开后的记录数是否符合渲染需要。

总结

flatten 是 Vega 数据重塑工具箱中最直接的工具之一:fields 指定要展开的数组字段,index 保留零基位置信息,as 控制输出字段名;多字段平行展开时以最长数组为准、缺失补 null。其底层实现(Flatten.js)通过 dataflow 脉冲整体重建输出并标记修改字段,配合 flatten-test.js 验证的增量更新行为,使其在静态与动态数据场景下都能稳定工作。当你需要把"一行多值"的数据结构转换为逐点可绘制的平坦数据流时,flatten 就是最直接的答案。

登录后查看全文
vega