Apache Beam 实战指南:基于 Schema 的 Join 等值连接变换

原创2026-10-09 13:04:261,839 阅读

Apache Beam 实战指南:基于 Schema 的 Join 等值连接变换

本指南以 Apache Beam Tour of Beam 学习课程的 schema-based-transforms 模块 中 Join 单元 为核心,深入讲解如何基于 Schema 在两条 PCollection 之间执行等值连接(equi-join)。读完本文,你将掌握 Join.innerJoin(...).using(...) 与 FieldsEqual.left(...).right(...) 两种字段匹配方式、六种连接类型的选用,以及源码级实现原理和对应的测试验证方法,并能在自己的 Java Pipeline 中直接落地。

为什么需要基于 Schema 的 Join

在 Apache Beam 中,传统做数据关联的方式是先把元素转换成 KV<K, V>,再借助 CoGroupByKey 手工完成分组与配对(这也是 join-library 扩展 的实现思路)。这种方式需要开发者自行定义键的构造与编码,代码繁琐且容易出错。

基于 Schema 的 Join 变换(位于 sdks/java/core 的 schemas.transforms 包)则完全不同:只要两个输入 PCollection 具备明确的 Schema,你只需声明“按哪些字段连接”,剩下的键提取、比较与配对全部由变换内部完成。其核心能力如下:

  • 在两条具备 Schema 的 PCollection 之间执行等值连接;
  • 只需指定参与连接的字段名,无需手工构造 KV 和 Coder;
  • 结果统一为 PCollection<Row>,包含名为 lhs 和 rhs 的两个字段,分别承载左、右输入 PCollection 的完整 Schema(对应源码中 LHS_TAG 与 RHS_TAG 常量)。

从结果结构可以看到:连接后的每一行是一个“套着两层的 Row”,内层 lhs/rhs 保留了输入行的全部字段,非常适合后续继续用 Select、Filter 等 Schema 变换做字段裁剪与加工。

指定连接字段的两种方式

方式一:自然连接(Natural Join)——字段同名

当左、右两个 PCollection 的 Schema 中都存在同名字段时,直接用 using(...) 声明即可。例如下面的示例连接 user 与 country 两个字段,两边 PCollection 都恰好拥有这些字段名:

PCollection<Row> joined = input1.apply(Join.innerJoin(input2).using("user", "country"));

这里 using(String... fieldNames) 会同时把同样的字段名作用到左侧与右侧(见 using 方法实现),语义等价于 FieldsEqual.left("user", "country").right("user", "country")。

方式二:显式映射——两侧字段名不同

如果右侧 PCollection 中用于连接的字段与左侧名称不同,则改用 on(FieldsEqual...) 精确指定左右两侧各自的字段:

PCollection<Row> joined = input1.apply(Join.innerJoin(input2)
       .on(FieldsEqual.left("user", "country").right("otherUser", "otherCountry")));

FieldsEqual 是连接谓词(predicate)的构造器,在 源码 中可以看到它支持三种字段引用方式:

引用方式 示例 说明
按字段名 left("user", "country") 最常用,按 Schema 中的字段名称匹配
按字段序号 left(0, 2) 按字段在 Schema 中的下标定位
按 FieldAccessDescriptor left(descriptor) 底层描述符方式,支持嵌套字段访问等高级场景

FieldsEqual.left(...) 与 .right(...) 可以链式调用、顺序任意,最终通过 on(...) 注入变换(见 on 方法)。在 expand 阶段,谓词会基于左右两边的真实 Schema 完成解析(predicate.resolve(lhsSchema, rhsSchema)),因此字段序号、名称都会被解析成确定性的字段访问描述符。

支持的连接类型

Join 变换支持以下六种连接类型(与 description.md 中的列表一致):

连接类型 说明 保留行为
Full outer join(全外连接) 左右两侧都参与 无匹配时 lhs/rhs 侧留空
Left outer join(左外连接) 左侧全部保留 右侧无匹配时 rhs 为空
Right outer join(右外连接) 右侧全部保留 左侧无匹配时 lhs 为空
Inner join(内连接) 只保留两侧都匹配的行 无空侧
Left inner join(左内连接) 左侧强制参与、右侧按匹配 侧重左侧语义的内连接变体
Right inner join(右内连接) 右侧强制参与、左侧按匹配 侧重右侧语义的内连接变体

对应到 Java API,核心实现(Join.java)通过内部枚举 JoinType(INNER、OUTER、LEFT_OUTER、RIGHT_OUTER,外加 INNER_BROADCAST、LEFT_OUTER_BROADCAST 两种广播变体)来区分执行路径,并暴露了以下工厂方法:

Join.innerJoin(rhs)            // 内连接
Join.fullOuterJoin(rhs)        // 全外连接
Join.leftOuterJoin(rhs)        // 左外连接
Join.rightOuterJoin(rhs)       // 右外连接
Join.innerBroadcastJoin(rhs)   // 内连接 + 右侧广播为 SideInput
Join.leftOuterBroadcastJoin(rhs) // 左外连接 + 右侧广播为 SideInput

其中 *BroadcastJoin 变体把右侧 PCollection 转为 SideInput(见 expand 中对 withSideInput() 的调用),适合“大表关联小表”的场景,可避免全量 Shuffle。

动手实践:Tour of Beam 的 Join 练习

本单元的 Playground 示例位于 java-example/Task.java,是一个完整的可运行 Pipeline。练习目标是:读取游戏数据,把“用户信息”与“每局游戏得分”两条 PCollection 按 userId 内连接起来,观察每个用户在游戏中的统计结果。单元元数据(SDK 为 Java、难度 ADVANCED)记录在 unit-info.yaml。

第一步:定义带 Schema 的 POJO

示例用注解方式声明了两个 POJO。Game 记录一局游戏的得分明细:

@DefaultSchema(JavaFieldSchema.class)
public static class Game {
    public String userId;
    public Integer score;
    public String gameId;
    public String date;

    @SchemaCreate
    public Game(String userId, Integer score, String gameId, String date) {
        this.userId = userId;
        this.score = score;
        this.gameId = gameId;
        this.date = date;
    }
}

User 记录用户的 ID 与昵称:

@DefaultSchema(JavaFieldSchema.class)
public static class User {
    public String userId;
    public String userName;

    @SchemaCreate
    public User(String userId, String userName) {
        this.userId = userId;
        this.userName = userName;
    }
}

@DefaultSchema(JavaFieldSchema.class) 让 Beam 自动把 JavaBean 字段映射为 Schema 字段,@SchemaCreate 则指明用哪个构造函数从 Row 重建对象。

第二步:为 PCollection 绑定 Schema

示例同时以编程方式构建了 userSchema 与 gameSchema,并通过 setSchema(...) 把 POJO 集合与 Row 相互转换:

Schema userSchema = Schema.builder()
        .addStringField("userId")
        .addStringField("userName")
        .build();

Schema gameSchema = Schema.builder()
        .addStringField("userId")
        .addInt32Field("score")
        .addStringField("gameId")
        .addStringField("date")
        .build();

注意:连接键 userId 必须在两边的 Schema 中都存在(本例均为 String 类型),这是 using("userId") 能够生效的前提。

第三步:执行连接

两条数据流分别由 getUserPCollection(pipeline) 与 getGamePCollection(pipeline) 提供(两者都从 gs://apache-beam-samples/game/small/gaming_data.csv 读取,并做 Sample.fixedSizeGlobally(100) 抽样),随后一句代码完成内连接:

PCollection<Row> pCollection =
    userInfo.apply(Join.<User, Game>innerJoin(gameInfo).using("userId"));

pCollection.apply("User flatten row", ParDo.of(new LogOutput<>("Flattened")));

连接结果 pCollection 中每一行的结构为 Row{lhs: User 行, rhs: Game 行},通过 LogOutput 即可在日志中看到每个 userId 对应的用户昵称与全部得分记录。

第四步:一行切换连接类型

Playground 练习最有价值的一点是:切换连接类型只需改函数名。例如想统计所有用户(包括没有任何游戏记录的用户),把内连接换成全外连接即可:

.apply(Join.fullOuterJoin(gameInfo).using("userId"));

同理,leftOuterJoin、rightOuterJoin、innerJoin 均可按需替换,其余代码完全不用动——这正是 Schema 化 Join 变换“按字段声明、按类型切换”的设计红利。

源码剖析:Join 是如何实现的

在 Join.java 的 expand 方法 中可以看到,所有连接类型最终都收敛到同一个底层原语:CoGroup。核心调用链如下:

PCollectionTuple tuple = PCollectionTuple.of(LHS_TAG, lhs).and(RHS_TAG, rhs);
switch (joinType) {
  case INNER:
    return tuple.apply(
        CoGroup.join(LHS_TAG, CoGroup.By.fieldAccessDescriptor(resolvedPredicate.lhs))
            .join(RHS_TAG, CoGroup.By.fieldAccessDescriptor(resolvedPredicate.rhs))
            .crossProductJoin());
  ...
}

实现要点可以总结为三点:

  1. 统一入口 CoGroup + crossProductJoin:左右两个 PCollection 被打上 lhs/rhs 标签组成 PCollectionTuple,CoGroup.By.fieldAccessDescriptor(...) 负责按解析后的字段描述符分组,crossProductJoin() 对同一键下的左右元素做笛卡尔积配对。等值连接中“一对多、多对多”的展开语义由此天然获得。
  2. 可选参与(Optional Participation)控制外连接语义:外连接(OUTER、LEFT_OUTER、RIGHT_OUTER)会在对应一侧的 CoGroup.By 上追加 withOptionalParticipation(),使该侧在没有匹配键时也产出空侧;而内连接两侧都不加。例如右外连接只在左侧加 withOptionalParticipation()(见 RIGHT_OUTER 分支)。
  3. SideInput 实现广播连接:INNER_BROADCAST 与 LEFT_OUTER_BROADCAST 对右侧追加 withSideInput(),把右表作为 SideInput 供左侧逐元素查询,避免了大规模 Shuffle。

与 KV 版 Join 库的对比

仓库中另有一个面向 KV<K, V> 的 join-library Join,它直接基于 KeyedPCollectionTuple + CoGroupByKey 实现 innerJoin、leftOuterJoin、rightOuterJoin、fullOuterJoin。两者的关键差异在于:

  • KV 版要求输入已按键分组为 PCollection<KV<K, V>>,且外连接必须显式传入 null 占位值(如 leftOuterJoin(left, right, nullValue)),因为 KV 的 value 不允许真正为 null;
  • Schema 版以字段为键、以 Row 为容器,外连接产生的空侧由 lhs/rhs 子 Row 的空缺表达,无需手工指定占位值。

如果手头的数据已经是 KV 形态(例如上游来自 GroupByKey),KV 版是轻量选择;如果要关联的是结构化数据,Schema 版更直接。

测试验证:Join 的正确性如何保证

核心实现配有完善的单元测试 JoinTest.java。以 testInnerJoinSameKeys 为例(第 65-120 行):

  • 构造两张 Schema 相同(user、count、country)的数据表,分别含有重复键与互不匹配的键;
  • 同时调用 innerBroadcastJoin(...) 与 innerJoin(...),并用 assertEquals 断言两者输出 Schema 均为 lhs/rhs 两个 Row 字段;
  • 通过 JoinTestUtils.innerJoin(...) 计算期望结果,再用 PAssert.that(...).containsInAnyOrder(...) 验证实际输出与期望完全一致。

测试数据特意覆盖了“同一键多条记录”(多对多)与“仅一侧存在的键”(过滤掉),这从测试侧印证了连接变换对笛卡尔展开与外连接过滤行为的处理。

实战注意事项

  1. 字段类型必须兼容:using("userId") 要求两边 userId 字段类型一致(如都是 STRING),否则 Schema 解析阶段无法对齐字段;
  2. 结果行是嵌套结构:连接产物为 Row{lhs, rhs},后续通常需要配合 Select 提取需要的子字段,或直接以嵌套 Row 继续参与下游变换;
  3. 区分广播连接与常规连接:当右侧集合较小(如维度表、配置表)时,优先使用 innerBroadcastJoin / leftOuterBroadcastJoin 降低 Shuffle 开销;两侧都很大时使用常规连接;
  4. 流式场景需谨慎:Join 是基于窗口内数据的批式关联语义,用于流处理时需结合窗口与触发策略,确保参与连接的数据落在同一窗口内;
  5. 外连接的空侧处理:外连接未匹配到的行,其 lhs/rhs 子 Row 为空(null),消费时要注意判空,必要时用 CoGroup.By.fieldAccessDescriptor(...).withOptionalParticipation() 的语义来理解输出。

掌握以上内容后,你可以像游乐场练习那样,把任意两个具备 Schema 的 PCollection 通过一行 API 完成等值关联,并按需在六种连接类型之间自由切换。

登录后查看全文
beam