Apache Beam SQL 完全指南:用标准 SQL 查询有界与无界 PCollection
Apache Beam SQL 完全指南:用标准 SQL 查询有界与无界 PCollection
Apache Beam SQL 是 Beam 内置的 SQL DSL,允许 Java 与 Python 用户直接以 SQL 语句查询有界(bounded)与无界(unbounded)的 PCollection,并把查询自动翻译成一个可嵌入管道任意位置的 PTransform。本文以 Beam 仓库中的 overview 文档 为主线,结合仓库源码逐层讲解方言切换、SqlTransform/Row 两大核心概念、交互式 Shell、窗口与触发扩展以及 UDF/UDAF 等能力,读完即可在真实管道中落地 SQL 查询。
Beam SQL 是什么
Beam SQL 让开发者在统一批处理/流处理编程模型中,用熟悉的标准 SQL 来描述数据处理逻辑。它的核心机制非常简洁:
- 一条 SQL 查询会被翻译成一个
PTransform,即 Beam 管道中一段被封装的处理逻辑; - 你可以自由地在同一管道中混用 SQL
PTransform与普通PTransform(如ParDo、GroupByKey、各类 I/O),不需要为 SQL 单独设计架构; - 查询作用的对象是
PCollection<Row>:一个PCollection<Row>在 SQL 世界里扮演"一张表"的角色。
从源码看,SqlTransform.java 直接继承自 PTransform<PInput, PCollection<Row>>,并定义了常量 PCOLLECTION_NAME = "PCOLLECTION"——这就是查询中引用单输入集合时的默认表名。其 expand() 方法(L136-L173)会完成"输入集合注册为表 → 加载表提供者(TableProvider)→ 解析 DDL → 调用查询规划器(QueryPlanner)解析 SQL → 输出结果 PCollection<Row>"的完整链路,最终由 BeamSqlRelUtils.toPCollection 生成可运行的 Beam 执行计划。
两大核心概念:SqlTransform 与 Row
在管道中使用 Beam SQL,只需要掌握两个概念:
SqlTransform:SQL 查询的入口
SqlTransform 是把 SQL 查询字符串变成 PTransform 的唯一 API。静态方法 SqlTransform.query(queryString) 接收 SQL 字符串并返回一个可应用的 PTransform,支持:
- 应用到单个
PCollection:查询中通过表名PCOLLECTION引用该集合; - 应用到
PCollectionTuple(多输入集合):Tuple 中每个PCollection的TupleTagid 即为查询中的表名,可直接对多张"表"执行 JOIN、UNION 等操作。
从源码看,SqlTransform.java 中 query() 通过 Builder 模式构建实例,同时提供了丰富的方法链,使查询具备很强的扩展能力:
| 方法 | 作用 |
|---|---|
withTableProvider(name, provider) / withDefaultTableProvider(...) |
注册外部表提供者(TableProvider),并可选设为默认 schema |
withQueryPlannerClass(clazz) |
按查询粒度覆盖全局查询规划器(见下文方言一节) |
withNamedParameters(Map) / withPositionalParameters(List) |
绑定 SQL 查询参数(对应 QueryParameters 的 NAMED/POSITIONAL 两种模式,见 QueryPlanner.java) |
withDdlString(ddl) |
附带 CREATE EXTERNAL TABLE 等 DDL 语句,实现纯 SQL 的读写管道 |
withAutoLoading(boolean) |
控制是否自动加载 TableProvider 与用户自定义函数 |
registerUdf(name, clazz) / registerUdf(name, SerializableFunction) |
注册标量 UDF |
registerUdaf(name, CombineFn) |
注册聚合 UDAF |
withErrorsTransformer(transformer) |
把查询过程中的错误行导向指定的错误处理 PTransform |
Row:SQL 操作的元素类型
Row 是 Beam SQL 处理的基本元素类型。SQL 只能作用于已注册 schema 的 PCollection<T>,或本身就是 PCollection<Row> 的集合。有关为类型 T 注册 schema 的细节,可参考 Beam 编程指南中的 schema 相关说明(见 Walkthrough 文档)。
如果项目中没有现成的类型 T,可以通过三种方式获得 PCollection<Row>:
- 从内存数据构造(典型用于单元测试),注意必须显式指定
Row的 Coder,例如通过Create.of(..):
// 定义记录 schema
Schema appSchema =
Schema
.builder()
.addInt32Field("appId")
.addStringField("description")
.addDateTimeField("rowtime")
.build();
// 构造一条具体记录
Row row =
Row
.withSchema(appSchema)
.addValues(1, "Some cool app", new Date())
.build();
// 创建只含该行的源 PCollection
PCollection<Row> testApps =
PBegin
.in(p)
.apply(Create
.of(row)
.withCoder(RowCoder.of(appSchema)));
- 从其他类型的
PCollection<T>转换:通过ParDo把普通记录转换为Row格式,并调用.setRowSchema(appSchema)声明输出 schema:
// 示例 POJO 类
class AppPojo {
Integer appId;
String description;
Date timestamp;
}
// 通过某种方式取得 POJO 集合
PCollection<AppPojo> pojos = ...
// 在 DoFn 中把 POJO 转为 Row
PCollection<Row> apps = pojos
.apply(
ParDo.of(new DoFn<AppPojo, Row>() {
@ProcessElement
public void processElement(ProcessContext c) {
AppPojo pojo = c.element();
Row appRow =
Row
.withSchema(appSchema)
.addValues(pojo.appId, pojo.description, pojo.timestamp)
.build();
c.output(appRow);
}
})).setRowSchema(appSchema);
- 作为另一个
SqlTransform的输出,详情见下一节。
支持的两大 SQL 方言:Calcite 与 ZetaSQL
Beam SQL 内置两套方言,两者共享同一套扩展机制(窗口、复杂类型处理等):
- Beam Calcite SQL:基于 Apache Calcite 的变体,是大数据处理领域非常普及的方言,也是 Beam SQL 的默认方言;
- Beam ZetaSQL:更贴近 BigQuery 的 SQL 框架,因此特别适合需要读写 BigQuery 表的管道。
从源码看,BeamSqlPipelineOptions.java 中 plannerName 的默认值即为 org.apache.beam.sdk.extensions.sql.impl.CalciteQueryPlanner,印证了 Calcite 是默认规划器的事实。两套方言分别由 CalciteQueryPlanner.java 与 ZetaSQLQueryPlanner.java 实现,二者都实现 QueryPlanner.java 中定义的 QueryPlanner 接口——该接口把 SQL 语句解析为 BeamRelNode 关系树(convertToBeamRel),或仅解析为语法树 SqlNode(parse)。
切换方言
把规划器的完整包名传给 PipelineOptions 接口中的 setPlannerName 方法即可切换。切换到 ZetaSQL 的写法如下:
PipelineOptions options = ...;
options
.as(BeamSqlPipelineOptions.class)
.setPlannerName("org.apache.beam.sdk.extensions.sql.zetasql.ZetaSQLQueryPlanner");
注意:使用 ZetaSQLQueryPlanner 除了需要 beam-sdks-java-extensions-sql 包之外,还必须额外添加 beam-sdks-java-extensions-sql-zetasql 依赖(使用 CalciteQueryPlanner 则只需要前者)。
BeamSqlPipelineOptions 还提供了另外两个相关配置(源码):
zetaSqlDefaultTimezone:ZetaSQL 分析器使用的默认时区,默认UTC,仅对 ZetaSQL 生效;verifyRowValues:是否开启行值额外校验(调试用),默认false。
此外,方言也可以在单条查询粒度覆盖:调用 SqlTransform.query(sql).withQueryPlannerClass(ZetaSQLQueryPlanner.class)(实现于 SqlTransform.java),即可绕过全局配置为该查询指定规划器。
Calcite 方言能力矩阵
Beam Calcite SQL 对 Apache Calcite 操作符与函数的支持情况(完整表格见 calcite/overview.md)如下:
| 操作符/函数 | Beam SQL 支持状态 |
|---|---|
| 操作符优先级(Operator precedence) | 支持 |
| 比较操作符 | 支持,见 scalar functions |
| 逻辑操作符 | 支持 |
| 算术操作符与函数 | 支持 |
| 字符串操作符与函数 | 支持 |
| 二进制字符串操作符与函数 | 不支持 |
| 日期/时间函数 | 支持 |
| 系统函数 | 不支持 |
| 条件函数与操作符 | 支持 |
| 类型转换(Type conversion) | 支持 |
| 值构造器(Value constructors) | 仅支持 array |
| 集合函数、Period 谓词、JDBC 函数转义 | 不支持 |
| 聚合函数 | 支持(见 aggregate-functions.md) |
| 窗口函数(Window functions) | 不支持 |
| 分组函数(Grouping functions) | 不支持 |
| 分组窗口函数(Grouped window functions) | 支持,见 windowing-and-triggering.md |
| 分组辅助函数(Grouped auxiliary) | 支持(SESSION_END 除外) |
| 空间、几何、JSON 函数 | 不支持 |
| 用户自定义函数 | 支持(不支持命名/可选参数调用),见 user-defined-functions.md |
| MATCH_RECOGNIZE | 不支持 |
| DDL 扩展 | 支持 CREATE EXTERNAL TABLE |
ZetaSQL 方言能力
Beam ZetaSQL 支持的内置函数清单维护在 SupportedZetaSqlBuiltinFunctions.java 中(源码中注释掉的条目即尚未支持的能力)。ZetaSQL 方言相关的查询语法、函数调用规则、词法结构、类型转换与各类函数参考,见 zetasql 目录 下的系列文档。
数据类型
Beam SQL 除标准 SQL 标量类型外,还支持数组、Map 与嵌套 Row 等扩展类型。在 Java 中,SQL 类型会映射到容量足够大的 Java 类型(映射表见 calcite/data-types.md):
| SQL 类型 | 说明 | Java 类 |
|---|---|---|
| TINYINT | 1 字节有符号整数(-128~127) | java.lang.Byte |
| SMALLINT | 2 字节有符号整数(-32768~32767) | java.lang.Short |
| INTEGER | 4 字节有符号整数(-2147483648~2147483647) | java.lang.Integer |
| BIGINT | 8 字节有符号整数 | java.lang.Long |
| FLOAT / DOUBLE | 4 字节 / 8 字节浮点 | java.lang.Float / java.lang.Double |
| DECIMAL | 任意精度十进制 | java.math.BigDecimal |
| VARCHAR | 任意长度字符串 | java.lang.String |
| TIMESTAMP | 毫秒精度时间戳 | org.joda.ReadableInstant |
| ARRAY<type> | 有序值列表 | java.util.List |
| MAP<type, type> | 有限无序映射 | java.util.Map |
| ROW<fields> | 嵌套行 | org.apache.beam.sdk.values.Row |
在 Java 管道中使用 SqlTransform
单表查询:PCOLLECTION
对单个 PCollection 应用查询时,集合以表名 PCOLLECTION 出现在 FROM 子句中:
PCollection<Row> filteredNames = testApps.apply(
SqlTransform.query(
"SELECT appId, description, rowtime "
+ "FROM PCOLLECTION "
+ "WHERE appId=1"));
多表 JOIN:PCollectionTuple
把多个 PCollection 组装成 PCollectionTuple,每个集合的 TupleTag id 即查询中的表名。表名绑定在该 PCollectionTuple 上,只在针对它发起的查询中有效。例如对两张表做聚合 JOIN:
// 定义 reviews 的 schema
Schema reviewSchema =
Schema
.builder()
.addInt32Field("appId")
.addInt32Field("reviewerId")
.addFloatField("rating")
.addDateTimeField("rowtime")
.build();
// 取得符合该 schema 的 reviews 集合
PCollection<Row> reviewsRows = ...
// 组装 PCollectionTuple,TupleTag id 将作为 SQL 中的表名
PCollectionTuple namesAndFoods = PCollectionTuple
.of(new TupleTag<>("Apps"), appsRows) // appsRows 来自上一节示例
.and(new TupleTag<>("Reviews"), reviewsRows);
// 按 app 统计评论数与平均评分
PCollection<Row> output = namesAndFoods.apply(
SqlTransform.query(
"SELECT Apps.appId, COUNT(Reviews.rating), AVG(Reviews.rating) "
+ "FROM Apps INNER JOIN Reviews ON Apps.appId = Reviews.appId "
+ "GROUP BY Apps.appId"));
关于 PCollectionTuple 的边界规则,SqlTransform.java 的注释明确给出了三条约束:
- 查询只用到上游 Tuple 中部分表是合法的;
- 若查询引用了不存在的表,校验阶段会抛出
IllegalStateException; - 上游 Tuple 中的表名仅在当前查询调用范围内有效。
完整可运行示例
仓库中的 BeamSqlExample.java 演示了以上两种 API 的完整用法:先用 Create.of(...).withRowSchema(type) 构造内存表,执行 select c1, c2, c3 from PCOLLECTION where c1 > 1;再把第一步的结果包进 PCollectionTuple,执行 select c2, sum(c3) from CASE1_RESULT group by c2。其注释给出了直接运行方式:
./gradlew :sdks:java:extensions:sql:runBasicExample
该命令使用 Direct Runner 在本地执行,预期输出 PCOLLECTION: [3, row, 3.0]、PCOLLECTION: [2, row, 2.0] 以及 CASE1_RESULT: [row, 5.0]。
Python 中的 Beam SQL(跨语言调用)
Beam SQL 同样对 Python 用户可用,其入口是 sql.py 中的 SqlTransform 类。它基于 Beam 的跨语言(cross-language)扩展机制实现:内部是一个 ExternalTransform,URN 为 beam:external:java:sql:v1,通过 Java 端的 expansion service(:sdks:java:extensions:sql:expansion-service:shadowJar)把查询展开为 Java 的 SqlTransform。
Python 端用法要点(sql.py 文档字符串):
- 输入
PCollection必须带 schema,两种方式:- 注册
typing.NamedTuple类型并使用RowCoder,例如coders.registry.register_coder(Purchase, coders.RowCoder)后with_output_types(Purchase); - 直接产出
beam.Row实例(字段类型需能被 Beam 推断)。
- 注册
- 输出同样是带 schema 的
PCollection,查询产生的列可以作为属性访问:
purchases | SqlTransform("""
SELECT item_name, COUNT(*) AS `count`
FROM PCOLLECTION GROUP BY item_name""")
| beam.Map(lambda row: "We've sold %d %ss!" % (row.count,
row.item_name))
- 构造函数签名
SqlTransform(query, dialect=None, expansion_service=None):dialect传'zetasql'可切换为 ZetaSQL 方言。 - 更多可运行示例见 sql_taxi.py 与 wordcount_xlang_sql.py。
交互式 Beam SQL Shell
从 2.6.0 版本起,Beam SQL 提供了交互式 Shell:无需写 Java 代码,直接用 SQL 语句定义管道。默认使用 DirectRunner 在本地执行查询。完整说明见 Shell 文档。
快速启动
克隆 Beam 仓库后,在仓库根目录执行:
./gradlew -p sdks/java/extensions/sql/shell -Pbeam.sql.shell.bundled=':runners:flink:1.13,:sdks:java:io:kafka' installDist
./sdks/java/extensions/sql/shell/build/install/shell/bin/shell
首次执行 Gradle 命令时若项目尚未构建,需要几分钟构建全部依赖。启动后即可输入查询:
Welcome to Beam SQL 2.6.0-SNAPSHOT (based on sqlline version 1.4.0)
0: BeamSQL>
Shell 会把查询转换为 Beam 管道、用 DirectRunner 执行,并在管道结束后以表格返回结果:
0: BeamSQL> SELECT 'foo' AS NAME, 'bar' AS TYPE, 'num' AS NUMBER;
+------+------+--------+
| NAME | TYPE | NUMBER |
+------+------+--------+
| foo | bar | num |
+------+------+--------+
1 row selected (0.826 seconds)
声明表:CREATE EXTERNAL TABLE
读写数据前,必须先声明一张虚拟表。例如把当前目录下的本地 CSV 文件 test-file.csv 注册为表:
0: BeamSQL> CREATE EXTERNAL TABLE csv_file (field1 VARCHAR, field2 INTEGER) TYPE text LOCATION 'test-file.csv';
No rows affected (0.042 seconds)
CREATE EXTERNAL TABLE 只是把数据源/数据目的地描述给 Beam SQL,不会创建持久化的物理表。语法细节与支持的 TYPE 见 CREATE EXTERNAL TABLE 参考文档。
读写数据
读取已声明的 CSV 表:
0: BeamSQL> SELECT field1 AS field FROM csv_file;
+--------+
| field |
+--------+
| baz |
| foo |
| bar |
| bar |
| foo |
+--------+
写入则使用 INSERT INTO … SELECT ...:
0: BeamSQL> INSERT INTO csv_file SELECT 'foo', 'bar';
读写行为取决于表类型,例如:
text类型基于TextIO实现,写入可能产生多个编号文件;pubsub类型是无界源,读取该表时管道永远不会结束。
开发期处理无界源
排查无界源数据时,必须在 SELECT 末尾加 LIMIT x 限制输出条数,否则管道不会结束:
0: BeamSQL> SELECT field1 FROM unbounded_source LIMIT 10 ;
上述带 LIMIT 的查询属于快速本地查询,适合边调研数据边迭代设计;当逻辑确认后,去掉 LIMIT x 即可把语句提交为长期运行的任务(若其中某个表是无界源,管道理论上会一直运行)。
指定 Runner
默认使用 DirectRunner。要换其他 Runner,需要两步:
- 把 Runner 打进 Shell:向 Gradle 调用的
-Pbeam.sql.shell.bundled参数追加对应项目 id(可逗号分隔多个 Runner 或附加组件,例如更多 I/O):
./gradlew -p sdks/java/extensions/sql/shell -Pbeam.sql.shell.bundled=':runners:flink:1.13,:sdks:java:io:kafka' installDist
- 在 Shell 中用
SET命令指定 Runner:
0: BeamSQL> SET runner='FlinkRunner';
此后 Beam 会把所有 INSERT 语句作为管道提交给指定 Runner;此时 Shell 不再展示查询结果,需要通过对应 Runner 的 UI(如 Flink UI 或命令行)管理已提交的任务。
配置 PipelineOptions
用 SET 命令配置 Runner 所需的 PipelineOptions:
0: BeamSQL> SET projectId='gcpProjectId';
0: BeamSQL> SET tempLocation='/tmp/tempDir';
SET/RESET 语句的语法与常见用法(SET project = my_gcp_project``、SET runner = DataflowRunner 等)见 SET 与 RESET 参考:SET option = value 设置选项,RESET option 恢复默认值,无值的 flag 选项在命令行上对应 true。
打包独立发行版
也可以用 distZip / distTar 任务构建独立的 Shell 包:
./gradlew -p sdks/java/extensions/sql/shell -Pbeam.sql.shell.bundled=':runners:flink:1.13,:sdks:java:io:kafka' distZip
ls ./sdks/java/extensions/sql/shell/build/distributions/
beam-sdks-java-extensions-sql-shell-2.6.0-SNAPSHOT.tar beam-sdks-java-extensions-sql-shell-2.6.0-SNAPSHOT.zip
Beam SQL 扩展能力
Beam SQL 提供一系列利用统一批/流模型、处理复杂数据类型的扩展,且对所有方言(Calcite 与 ZetaSQL)通用。
窗口与触发
窗口语义有两种使用途径:在传入 SqlTransform 之前在输入 PCollection 上配置窗口;或在查询中使用窗口扩展(会覆盖输入集合的窗口设置)。触发(triggering)只能在输入 PCollection 上设置,SQL 没有对应扩展。
窗口函数写在 GROUP BY 子句中,此时要求有 TIMESTAMP 字段作为行的事件时间。支持的窗口函数(示例见 windowing-and-triggering.md):
TUMBLE:固定窗口。1 小时固定窗口:
SELECT f_int, COUNT(*)
FROM PCOLLECTION
GROUP BY
f_int,
TUMBLE(f_timestamp, INTERVAL '1' HOUR)
HOP:滑动窗口。每 30 分钟滑动一次、时长 1 小时:
SELECT f_int, COUNT(*)
FROM PCOLLECTION
GROUP BY
f_int,
HOP(f_timestamp, INTERVAL '30' MINUTE, INTERVAL '1' HOUR)
SESSION:会话窗口。间隔 5 分钟的会话窗口:
SELECT f_int, COUNT(*)
FROM PCOLLECTION
GROUP BY
f_int,
SESSION(f_timestamp, INTERVAL '5' MINUTE)
注意:查询中未指定窗口函数时,输入 PCollection 的窗口策略保持不变;指定了窗口函数时,PCollection 的窗口会被更新,但触发器保持不变。
跨系统虚拟表:CREATE EXTERNAL TABLE
CREATE EXTERNAL TABLE 语法如下(完整语法见 create-external-table.md):
CREATE EXTERNAL TABLE [ IF NOT EXISTS ] tableName (tableElement [, tableElement ]*)
TYPE type
[LOCATION location]
[TBLPROPERTIES tblProperties]
simpleType: TINYINT | SMALLINT | INTEGER | BIGINT | FLOAT | DOUBLE | DECIMAL | BOOLEAN | DATE | TIME | TIMESTAMP | CHAR | VARCHAR
fieldType: simpleType | MAP<simpleType, fieldType> | ARRAY<fieldType> | ROW<tableElement [, tableElement ]*>
tableElement: columnName fieldType [ NOT NULL ]
要点:
IF NOT EXISTS:可选,表已注册时忽略该语句而不报错;tableName/columnName:大小写敏感;表名不必与底层存储系统中的名字一致;type:虚拟表背后的 I/O transform,可取bigquery、bigtable、pubsub、kafka、text(以及文档中的pubsublite、mongodb);location:I/O 专属的底层表位置,按各 I/O 的格式要求填写;tblProperties:I/O 专属的额外配置,格式为带引号的 key-value JSON 对象。
BigQuery 示例(method 可选 DIRECT_READ(BigQuery Storage API)或 EXPORT(导出到 GCS 的 Avro 文件再读),Beam 2.21+ 默认 DIRECT_READ;EXPORT 模式需要设置 project 与 tempLocation 管道选项;读取支持投影与谓词下推;写模式在写入首条记录时自动建表,Map 类型不受支持,类型映射见原文档):
CREATE EXTERNAL TABLE users (id INTEGER, username VARCHAR)
TYPE bigquery
LOCATION 'testing-integration:apache.users'
Kafka 示例(KafkaIO 在 Beam SQL 中仍标记为实验性;bootstrap_servers、topics、format(csv/avro/json/proto/thrift,扁平模式默认 csv、嵌套模式默认 json)均为可选 TBLPROPERTIES,CSV 仅支持简单类型):
CREATE EXTERNAL TABLE [ IF NOT EXISTS ] tableName (tableElement [, tableElement ]*)
TYPE kafka
LOCATION 'my.company.url.com:2181/topic1'
TBLPROPERTIES '{
"bootstrap_servers": ["localhost:9092", "PLAINTEXT://192.168.1.200:2181"],
"topics": ["topic2", "topic3"],
"format": "json"
}'
Text 示例(TextIO 在 Beam SQL 中为实验性,读写模式不访问同一底层数据;TBLPROPERTIES.format 可取 default/rfc4180/excel/tdf/mysql,控制字段分隔符、引号字符、记录分隔符、是否忽略空行等):
CREATE EXTERNAL TABLE orders (id INTEGER, price INTEGER)
TYPE text
LOCATION '/home/admin/orders'
此外还支持 Pub/Sub(嵌套模式含 event_timestamp、attributes、payload 元数据列,支持 timestampAttributeKey、deadLetterQueue、format 属性)、Pub/Sub Lite、Cloud Bigtable(嵌套 family 语法与扁平 schema + columnsMapping 两种写法)与 MongoDB。**通用负载处理(Generic Payload Handling)**允许把字节数组 payload 解析进表 schema,format 支持 avro(自动生成 Avro schema)、json(按 UTF-8 JSON 解析)、proto(需 protoClass)、thrift(需 thriftClass 与 thriftProtocolFactoryClass);通用 DLQ 处理则以 "<dlqParamName>": "[DLQ_KIND]:[DLQ_ID]" 格式把解析失败的消息投递到 BigQuery 表、Pub/Sub Topic 或 Pub/Sub Lite Topic。
用户自定义函数(UDF / UDAF)
当内置函数不满足需求时,可以在 Java 中编写标量函数(UDF)与聚合函数(UDAF),在 SQL 查询中调用(示例见 user-defined-functions.md):
// UDF:实现 BeamSqlUdf,提供静态 eval 方法
public static class CubicInteger implements BeamSqlUdf {
public static Integer eval(Integer input){
return input * input * input;
}
}
// UDF:实现 SerializableFunction
public static class CubicIntegerFn implements SerializableFunction<Integer, Integer> {
@Override
public Integer apply(Integer input) {
return input * input * input;
}
}
String sql =
"SELECT f_int, cubic1(f_int), cubic2(f_int)"
+ "FROM PCOLLECTION "
+ "WHERE f_int = 2";
PCollection<Row> result =
input.apply(
"udfExample",
SqlTransform
.query(sql)
.registerUdf("cubic1", CubicInteger.class)
.registerUdf("cubic2", new CubicIntegerFn()));
UDAF 则接受一个 CombineFn(例如求平方和的 SquareSum),通过 .registerUdaf("squaresum", new SquareSum()) 注册后即可在 GROUP BY 查询中使用。注册底层实现在 SqlTransform.java,UDF 与 UDAF 定义分别被包装为 UdfDefinition / UdafDefinition 并随 transform 序列化。
JOIN 支持矩阵
Beam SQL 支持的 JOIN 类型(详见 joins.md):
- 支持:
INNER、LEFT OUTER、RIGHT OUTER,且仅支持等值连接(equijoin); - 不支持:
CROSS JOIN(无ON子句的全笛卡尔积)与FULL OUTER JOIN。
按输入的有界性分为三种场景:
- 有界 JOIN 有界:使用标准 JOIN 实现,两边输入都有限,不涉及窗口与触发;
- 无界 JOIN 无界:按窗口逐个执行连接。要求两个输入窗口兼容(否则抛
IllegalArgumentException),且每个输入的触发只允许每窗口触发一次——当前仅支持DefaultTrigger且不允许迟到数据,否则抛UnsupportedOperationException。与GroupByKey类似,JOIN 会用Trigger.continuationTrigger()更新触发,其余窗口策略不变; - 无界 JOIN 有界:有界输入被实现为侧输入(side-input),窗口/触发继承自上游。
总结与进一步阅读
Beam SQL 把"写 SQL"与"构建 Beam 管道"统一起来:SqlTransform 把查询变成可组合的 PTransform,Row/schema 是表与集合之间的桥梁,Calcite 与 ZetaSQL 两套方言覆盖通用大数据与 BigQuery 场景,Shell 与跨语言机制则让 Java 之外的开发者也能零门槛使用。配合窗口扩展、CREATE EXTERNAL TABLE、UDF/UDAF 与 JOIN 能力,足以支撑从本地原型到生产级批/流混合管道的开发。
想继续深入,可依次阅读仓库内的以下文档与源码:
- 实战演练:Walkthrough、可运行样例 BeamSqlExample.java
- 交互式 Shell:Shell 文档
- 方言参考:Beam Calcite SQL 概览、Beam ZetaSQL 概览
- 扩展参考:CREATE EXTERNAL TABLE、窗口与触发、UDF/UDAF、JOIN、SET/RESET
- 核心实现:SqlTransform.java、BeamSqlPipelineOptions.java、QueryPlanner.java、Python 端 sql.py