---
title: "join"
description: "按关联字段连接另一组数据，将选定字段合并到当前记录中。"
language: "zh"
canonical: "https://g2.antv.antgroup.com/zh/manual/core/data/join/"
version: "5.4.8"
---

[资料索引](/llms.txt)

## 概述

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

## 配置项

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

### 属性详细说明

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

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

## 使用场景

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

## 示例

### 基础用法

#### on 字段说明

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

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

```ts
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'],
      },
    ],
  },
});
```

- 转换结果为：

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

#### 字段重命名

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

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

- 转换结果为：

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

#### 设置默认值 unknown

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

```ts
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: '未知',
      },
    ],
  },
});
```

- 转换结果为：

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

#### tips

- join 是一种 左连接（left join），意味着主数据一定保留。

- select 不指定时默认不提取字段，只用于判断连接关系。

- 推荐提前对 join 数据做去重处理，避免多对一连接时的歧义。

- 支持动态函数提取连接字段，适配复杂结构。