G2

概述

join 的功能是用于将两份数据连接在一起，类似于 SQL 中的 JOIN 操作。该功能通常用于合并两个数据源中基于共同字段的数据，可以按指定条件将两个数据源中的记录结合起来，形成一个新的数据集。这个功能对于在可视化中展示多个数据源之间的关联信息非常有用。该操作在数据预处理阶段完成，生成的新字段可直接用于图形绘制、字段映射、标注等操作。

配置项

属性	描述	类型	默认值	必选
`join`	需要连接的数据源	`object[]`	-	是
`on`	两个数据源连接的字段	`[string \| ((d: any) => string), string \| ((d: any) => string)]`	-	是
`select`	从被连接的数据源中选择要显示的字段	`string[]`	`[]`	否
`as`	为 `select` 出来的字段重命名	`string[]`	不做重命名	否
`unknown`	如果没有匹配到连接的数据，指定一个默认值	`any`	NaN	否

属性详细说明

join：指定需要连接的第二份数据源，可以是一个对象数组，表示所有的连接数据。
on：定义连接条件，传入一个包含两个字段的数组，或者是可以返回字段名的函数数组。用于在两个数据源中根据这些字段进行匹配。
select：指定从被连接的数据源中选择哪些字段。默认为空数组，表示连接后的数据源包含所有字段。
as：为 select 选择的字段指定别名。如果不指定，则默认为字段原名。
unknown：当两个数据源中没有匹配的数据时，使用此值作为默认值。

📌 join 在复杂场景下能显著增强数据组织能力，是组合和清洗数据不可或缺的工具。

使用场景

数据合并：合并多源数据，补全缺失字段。将两个具有相关字段的数据源合并成一个数据源，进行进一步分析或可视化。
数据对齐：根据共同的字段对两个数据集进行对齐，生成可视化所需的结构。
条件选择：将代码（如用户 ID、产品 ID）映射为描述信息。从被连接的数据源中选择指定的字段进行展示，同时避免冗余数据。

示例

基础用法

on 字段说明

on: ['id', 'code'] // 或使用函数方式 on: [(d) => d.id, (d) => d.code]

将两个数据源按字段连接，并从外部数据中提取字段合并：

const data = [
  { a: 1, b: 2, c: 3 },
  { a: 4, b: 5, c: 6 },
];

const joinData = [
  { c: 1, d: 2, e: 3 },
  { c: 4, d: 5, e: 6 },
];

chart.options({
  data: {
    type: 'inline',
    value: data,
    transform: [
      {
        type: 'join',
        join: joinData,
        on: ['a', 'c'],
        select: ['d', 'e'],
      },
    ],
  },
});

转换结果为：

[
  { a: 1, b: 2, c: 3, d: 2, e: 3 },
  { a: 4, b: 5, c: 6, d: 5, e: 6 },
];

字段重命名

使用 as 为 select 出来的字段重命名：

chart.options({
  data: {
    type: 'inline',
    value: data,
    transform: [
      {
        type: 'join',
        join: joinData,
        on: ['a', 'c'],
        select: ['d', 'e'],
        as: ['dd', 'ee'],
      },
    ],
  },
});

转换结果为：

[
  { a: 1, b: 2, c: 3, dd: 2, ee: 3 },
  { a: 4, b: 5, c: 6, dd: 5, ee: 6 },
];

设置默认值 unknown

当两个数据源中没有匹配的数据时，使用 unknown 指定一个默认值：

const data = [{ id: 1 }, { id: 2 }];
const joinData = [{ code: 1, label: 'A' }];

chart.options({
  data: {
    type: 'inline',
    value: data,
    transform: [
      {
        type: 'join',
        join: joinData,
        on: ['id', 'code'],
        select: ['label'],
        unknown: '未知',
      },
    ],
  },
});

转换结果为：

[
  { id: 1, label: 'A' },
  { id: 2, label: '未知' },
];

tips

join 是一种左连接（left join），意味着主数据一定保留。
select 不指定时默认不提取字段，只用于判断连接关系。
推荐提前对 join 数据做去重处理，避免多对一连接时的歧义。
支持动态函数提取连接字段，适配复杂结构。