Apache Beam Schema Patterns 实战:基于 Schema 的等值连接(EquiJoin)
Apache Beam Schema Patterns 实战:基于 Schema 的等值连接(EquiJoin)
本文围绕 Apache Beam 官方文档中的 "Schema Patterns" 章节展开,讲解 Beam 的 Schema 类型系统以及基于
Jointransform 的等值连接(equijoins)模式:如何为PCollection定义 Schema、构造Row数据、在两个带 Schema 的集合之间以公共字段为键完成连接,并理解Row:[Row, Row]的嵌套输出结构与结果格式化。读完本文,你将能直接复用官方示例代码,在自己的 Beam 管道中完成多数据源按字段对齐合并的实战场景。
什么是 Schema:语言无关的类型系统
Apache Beam 的 Schema 为 PCollection 中的记录提供了一套独立于任何具体编程语言类型的类型系统。这意味着同一个 Schema 可以被多个 Java 类共享——例如一个 Protocol Buffer 生成的类和一个普通 POJO 类可能拥有完全相同的字段结构与类型,而 Beam 允许在这类类型之间无缝转换,无需手写映射代码。
Schema 还提供了一种跨不同编程语言 API(Java、Python、Go、Typescript、YAML)统一推理类型的方式:因为 Schema 描述的是抽象的字段名与字段类型,而不是某个语言的类定义。官方编程指南(programming-guide.md)中将结构化记录的共同特征归纳为:可被拆分为命名字段、字段类型限定在有限的原始类型集合内(int、long、string 等)、字段可标记为可选(nullable)或必填,并且记录往往支持嵌套结构(字段本身可以是带 Schema 的子 Row、数组或 Map)。
在 Java SDK 中,Schema 由 Schema.java 定义。从源码中的 TypeName 枚举(Schema.java#L522-L538)可以看到 Beam 支持的全部字段类型:
| 类型分类 | 取值 |
|---|---|
| 数值类型 | BYTE、INT16、INT32、INT64、DECIMAL、FLOAT、DOUBLE |
| 字符串 | STRING |
| 时间 | DATETIME |
| 布尔 | BOOLEAN |
| 二进制 | BYTES |
| 集合类型 | ARRAY、ITERABLE(后者可能无法完全放入内存) |
| Map | MAP |
| 嵌套行 | ROW(字段本身是带 Schema 的子行) |
| 逻辑类型 | LOGICAL_TYPE |
字段则通过 Schema.Field.of(name, fieldType) 创建(Schema.java#L1146-L1153),需要可空字段时使用 Schema.Field.nullable(name, fieldType)。
模式背景:为什么用 Join 而不是手动关联
在数据管道中,经常会出现"多个集合描述同一批相关事物"的情况:一个集合保存用户的姓名与邮箱,另一个集合保存姓名与电话号码,两者的结构都是已知的。此时最自然的做法是以姓名为公共键将两个集合连接起来,得到一个包含每个姓名全部信息(邮箱 + 电话)的集合。
Beam 的 Join transform(Join.java)正是为此设计的:它对**两个带 Schema 的 PCollection**执行等值连接(equijoin),连接条件只取决于字段子集的相等性,而不需要你手写 DoFn 做状态缓存或按键分组。官方文档建议:当你有多个结构已知、且描述相关信息的集合时,优先考虑使用 Join。
第一步:定义 Schema 并构造用户数据
官方示例(完整可运行版本位于 SnippetsTest.java#L159-L226,源码实现位于 Snippets.java#L956-L1021)首先为两个输入集合分别定义 Schema:
// 定义 Schemas
Schema emailSchema =
Schema.of(
Schema.Field.of("name", Schema.FieldType.STRING),
Schema.Field.of("email", Schema.FieldType.STRING));
Schema phoneSchema =
Schema.of(
Schema.Field.of("name", Schema.FieldType.STRING),
Schema.Field.of("phone", Schema.FieldType.STRING));
这里的关键点是:两个 Schema 共享名为 name 的公共字段(STRING 类型),它将作为后续连接的键。随后用 Row.withSchema(...).addValue(...).build() 构造带 Schema 的行数据:
// 创建用户数据集合
final List<Row> emailUsers =
Arrays.asList(
Row.withSchema(emailSchema).addValue("person1").addValue("person1@example.com").build(),
Row.withSchema(emailSchema).addValue("person2").addValue("person2@example.com").build(),
Row.withSchema(emailSchema).addValue("person3").addValue("person3@example.com").build(),
Row.withSchema(emailSchema).addValue("person4").addValue("person4@example.com").build(),
Row.withSchema(emailSchema).addValue("person6").addValue("person6@example.com").build());
final List<Row> phoneUsers =
Arrays.asList(
Row.withSchema(phoneSchema).addValue("person1").addValue("111-222-3333").build(),
Row.withSchema(phoneSchema).addValue("person2").addValue("222-333-4444").build(),
Row.withSchema(phoneSchema).addValue("person3").addValue("444-333-4444").build(),
Row.withSchema(phoneSchema).addValue("person4").addValue("555-333-4444").build(),
Row.withSchema(phoneSchema).addValue("person5").addValue("777-333-4444").build());
注意两个集合的数据刻意不完全对称:emailUsers 中有 person6 但没有 person5,phoneUsers 中有 person5 但没有 person6。这正是为了演示内连接(inner join)只保留两边都存在的键——最终结果中不会出现这两个人。
第二步:创建带 Schema 的 PCollection 并执行连接
接下来把数据变成 PCollection 并执行连接。关键 API 是 Create.of(...).withRowSchema(schema)(为 PCollection 显式附加 Schema,Beam 据此自动选择合适的 Coder 与编码方式,无需手动指定 Coder),以及 Join.innerJoin(rhs).using("name")(指定以 name 字段作为连接键,即"自然连接"):
// 创建/读取带 Schema 的 PCollections
PCollection<Row> emailList =
p.apply("CreateEmails", Create.of(emailUsers).withRowSchema(emailSchema));
PCollection<Row> phoneList =
p.apply("CreatePhones", Create.of(phoneUsers).withRowSchema(phoneSchema));
// 执行等值连接
PCollection<Row> resultRow =
emailList.apply("Apply Join", Join.<Row, Row>innerJoin(phoneList).using("name"));
// 预览结果
resultRow.apply(
"Preview Result",
MapElements.into(TypeDescriptors.strings())
.via(
x -> {
System.out.println(x);
return "";
}));
管道运行后控制台会打印如下输出(来自源码注释 Snippets.java#L985-L990):
Row:[Row:[person1, person1@example.com], Row:[person1, 111-222-3333]]
Row:[Row:[person2, person2@example.com], Row:[person2, 222-333-4444]]
Row:[Row:[person4, person4@example.com], Row:[person4, 555-333-4444]]
Row:[Row:[person3, person3@example.com], Row:[person3, 444-333-4444]]
可以看到只有 person1~person4 四个键匹配成功;person5(仅在右侧)与 person6(仅在左侧)都被内连接过滤掉。
理解 Join 的输出结构:Row:[Row, Row]
上述输出揭示了 Join 的核心行为:连接结果的每个元素是一个嵌套的 Row,其类型为 Row:[Row(emailSchema), Row(phoneSchema)]——即结果行的第一个字段是左侧(lhs)输入的一整行,第二个字段是右侧(rhs)输入的一整行。
这一设计在源码中有明确定义:Join 类声明了常量 LHS_TAG = "lhs" 与 RHS_TAG = "rhs"(Join.java#L58-L59),其类注释也说明"结果 PCollection<Row> 将分别包含名为 'lhs' 和 'rhs' 的两个字段,各自对应输入 PCollection 的 Schema"(Join.java#L29-L34)。单元测试 JoinTest.java#L94-L98 中同样断言了结果 Schema 为两个 addRowField(Join.LHS_TAG, ...) 与 addRowField(Join.RHS_TAG, ...) 的组合。
因此,输出 Row 的第 0 个位置是左侧行、第 1 个位置是右侧行,可以分别用 getRow(0) 与 getRow(1) 取出,再按字段名提取值。
第三步:格式化连接结果
有了嵌套结构,就可以将 Row:<a href="https://link.gitcode.com/i/c50c55f37fdb55574564f1f1fd1bce91" target="_blank">Row, Row] 扁平化为人可读的字符串。官方示例通过 MapElements 实现([Snippets.java#L993-L1017):
PCollection<String> result =
resultRow.apply(
"Format Output",
MapElements.into(TypeDescriptors.strings())
.via(
x -> {
String userInfo =
"Name: "
+ x.getRow(0).getValue("name")
+ " Email: "
+ x.getRow(0).getValue("email")
+ " Phone: "
+ x.getRow(1).getValue("phone");
System.out.println(userInfo);
return userInfo;
}));
输出示例(来自源码注释 Snippets.java#L1011-L1016):
Name: person4 Email: person4@example.com Phone: 555-333-4444
Name: person2 Email: person2@example.com Phone: 222-333-4444
Name: person3 Email: person3@example.com Phone: 444-333-4444
Name: person1 Email: person1@example.com Phone: 111-222-3333
这种"左侧行取公共字段与左侧独有字段、右侧行取右侧独有字段"的取值模式,就是 Schema Join 最典型的消费方式。
Join 家族全景:连接类型与字段匹配策略
Join 不止支持内连接。从源码入口方法可以看到完整的连接类型家族(Join.java#L131-L168):
| 静态工厂方法 | 语义 | 对应枚举(Join.java#L161-L168) |
|---|---|---|
Join.innerJoin(rhs) |
内连接,仅保留两侧键都匹配的行 | INNER |
Join.fullOuterJoin(rhs) |
全外连接,保留两侧全部键,缺失侧字段以 null 填充 | OUTER |
Join.leftOuterJoin(rhs) |
左外连接,保留左侧全部键 | LEFT_OUTER |
Join.rightOuterJoin(rhs) |
右外连接,保留右侧全部键 | RIGHT_OUTER |
Join.innerBroadcastJoin(rhs) |
内连接,右侧作为 side input 广播 | INNER_BROADCAST |
Join.leftOuterBroadcastJoin(rhs) |
左外连接,右侧广播 | LEFT_OUTER_BROADCAST |
外连接/广播变体在 JoinTest.java 中均有对应的单元测试覆盖(如 testOuterJoinDifferentKeys、testLeftOuterJoinSameKeys、testRightOuterJoinSameKeys、testInnerJoinSameKeys 等),可直接作为用法参考。
字段匹配策略有两种:
using(String... fieldNames)——自然连接:左右两侧使用同名字段作为连接键,要求该字段在两个 PCollection 中都存在(Join.java#L186-L192)。示例Join.innerJoin(pCollection2).using("user", "country")即同时按user和country两个字段做等值匹配(多个字段相当于联合键)。on(FieldsEqual...)——异构字段名:当右侧集合的连接字段与左侧名字不同时,可显式指定左右各自的字段,例如:
(示例出自 Join.java#L44-L49 的类注释。)PCollection<Row> joined = pCollection1.apply(Join.innerJoin(pCollection2) .on(FieldsEqual.left("user", "country").right("otherUser", "otherCountry")));
此外 using 与 FieldsEqual.left/right 还支持以字段 ID(Integer)或 FieldAccessDescriptor 来指定匹配字段,见 Join.java#L62-L128。
底层原理:Join 是如何执行的
从 Impl.expand 的实现(Join.java#L216-L272)可以看到,所有 Join 变体最终都基于 CoGroup transform 实现:
- 先将两侧输入打包为
PCollectionTuple:PCollectionTuple.of(LHS_TAG, lhs).and(RHS_TAG, rhs); - 解析连接谓词(
predicate.resolve(lhs.getSchema(), rhs.getSchema())),把字段名解析为FieldAccessDescriptor; - 对左右两侧分别以连接键做
CoGroup.By.fieldAccessDescriptor(...)分组,再执行crossProductJoin()生成笛卡尔积式的匹配结果; - 根据连接类型决定是否调用
withOptionalParticipation()(允许一侧不参与时以 null 填充)以及withSideInput()(把右侧作为 side input 广播)。
这解释了为什么该 transform 能以"只指定连接字段"的方式完成连接:分组、配对与空值填充全部由 CoGroup 机制承担,用户无需关心底层分组细节。
如何验证:配套单元测试
官方示例自带完整测试 testSchemaJoinPattern(SnippetsTest.java#L159-L226),其验证思路可以作为任何 Schema Join 管道的测试模板:
- 用
PAssert.that(actualFormattedResult).containsInAnyOrder(formattedResults)断言格式化输出与预期字符串集合一致; - 预期结果由
emailUsers与phoneUsers按索引逐对拼接生成,且只包含 person1~person4 四个匹配项,从测试层面再次印证了内连接对不对称数据(person5/person6)的过滤行为; - 最终
p.run()驱动整个管道执行。
小结
Apache Beam 的 Schema 机制让"类型"从具体语言类中抽象出来,而 Join transform 则为两个带 Schema 的 PCollection 提供了声明式的等值连接能力:用 using(...) 指定同名字段即可完成连接,输出为 Row:<a href="https://link.gitcode.com/i/16e017c710c32ef2a748075a9677248f" target="_blank">Row(lhs), Row(rhs)] 的嵌套结构,再通过 getRow(0)/getRow(1) 取值格式化。结合 fullOuterJoin、leftOuterJoin、rightOuterJoin 以及广播变体,这一模式可覆盖多数据源按键对齐合并的绝大多数场景。更多概念背景可继续阅读官方编程指南的 [What is a schema? 章节,完整示例代码可参考 Snippets.java 与 SnippetsTest.java。