Apache Beam 实战指南:基于 Schema 的 Join 等值连接变换
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());
...
}
实现要点可以总结为三点:
- 统一入口 CoGroup + crossProductJoin:左右两个
PCollection被打上lhs/rhs标签组成PCollectionTuple,CoGroup.By.fieldAccessDescriptor(...)负责按解析后的字段描述符分组,crossProductJoin()对同一键下的左右元素做笛卡尔积配对。等值连接中“一对多、多对多”的展开语义由此天然获得。 - 可选参与(Optional Participation)控制外连接语义:外连接(
OUTER、LEFT_OUTER、RIGHT_OUTER)会在对应一侧的CoGroup.By上追加withOptionalParticipation(),使该侧在没有匹配键时也产出空侧;而内连接两侧都不加。例如右外连接只在左侧加withOptionalParticipation()(见 RIGHT_OUTER 分支)。 - 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(...)验证实际输出与期望完全一致。
测试数据特意覆盖了“同一键多条记录”(多对多)与“仅一侧存在的键”(过滤掉),这从测试侧印证了连接变换对笛卡尔展开与外连接过滤行为的处理。
实战注意事项
- 字段类型必须兼容:
using("userId")要求两边userId字段类型一致(如都是STRING),否则 Schema 解析阶段无法对齐字段; - 结果行是嵌套结构:连接产物为
Row{lhs, rhs},后续通常需要配合Select提取需要的子字段,或直接以嵌套 Row 继续参与下游变换; - 区分广播连接与常规连接:当右侧集合较小(如维度表、配置表)时,优先使用
innerBroadcastJoin/leftOuterBroadcastJoin降低 Shuffle 开销;两侧都很大时使用常规连接; - 流式场景需谨慎:
Join是基于窗口内数据的批式关联语义,用于流处理时需结合窗口与触发策略,确保参与连接的数据落在同一窗口内; - 外连接的空侧处理:外连接未匹配到的行,其
lhs/rhs子 Row 为空(null),消费时要注意判空,必要时用CoGroup.By.fieldAccessDescriptor(...).withOptionalParticipation()的语义来理解输出。
掌握以上内容后,你可以像游乐场练习那样,把任意两个具备 Schema 的 PCollection 通过一行 API 完成等值关联,并按需在六种连接类型之间自由切换。