Structured Streaming API 介绍与实现:五个对象串起一条流

简介: 本文详解Structured Streaming五大核心对象(SparkSession、DataStreamReader、DataFrame、DataStreamWriter、StreamingQuery),厘清流批一致算子(如select/filter)、流式专属API(withWatermark/Trigger/outputMode)及流上禁用操作(limit/distinct/多聚合链),并以GMV实时计算为例,贯通读→算→写→管全流程,涵盖Trigger选型权衡、StreamingQuery生命周期管理及checkpoint冲突根因。

摘要:Structured Streaming 的 API 面看似只是"批处理 API 加个流式入口",实际由五个对象各司其职:SparkSession 开门、DataStreamReader 定义读入、DataFrame 承载计算、DataStreamWriter 决定写出、StreamingQuery 管生命周期。本文沿"读 → 算 → 写 → 管"主线把五个对象的常用方法过一遍,讲清哪些 API 流批一致(select/filter/join)、哪些是流式专属(withWatermark、outputMode、Trigger 四种模式)、哪些操作流上不可用(limit、distinct、多聚合链);再用一段完整实现把五个对象串成一条可跑的 GMV 流,覆盖 Trigger 选择的代价权衡、StreamingQuery 的启停查监控闭环,以及一个高频报错(checkpoint 相同 + 查询不同)的根因。

关键词:Structured Streaming, Spark, DataStreamReader, DataStreamWriter, StreamingQuery, Trigger, withWatermark, API, 微批处理


一、API 地图:五个对象,各司其职

先把整张 API 面压成五个对象,后面逐个展开:

对象 职责 入口/方法 一句话
SparkSession 环境与入口 spark.readStream / spark.streams 开门的人
DataStreamReader 定义源与 schema format/option/schema/load 怎么读
DataFrame 承载计算 select/filter/join/groupBy 算什么
DataStreamWriter 定义输出 outputMode/format/option/trigger/start 怎么写
StreamingQuery 生命周期管理 start/stop/status/lastProgress 怎么管

在这里插入图片描述

关键认知:DataFrame 上的绝大多数操作流批一致——这是"流批一体"的直接收益,你会的批 API 九成直接可用。真正需要新学的是读入两端(Reader/Writer)与查询管理(StreamingQuery)。

二、DataStreamReader:读的四种定义

val orders = spark.readStream                 // ① 入口
  .format("kafka")                            // ② 源类型
  .option("kafka.bootstrap.servers", "broker1:9092")
  .option("subscribe", "order_events")
  .option("maxOffsetsPerTrigger", "80000")    // ③ 选项
  .load()                                     // ④ 生成流 DataFrame

四段式结构 readStream → format → option → load 是所有源的统一范式。两个必记点:schema 必须显式指定(流式没有"先扫全量推 schema"的机会,File 源不指定直接报错);option 键因源而异(Kafka 的 subscribe、File 的 maxFilesPerTrigger),但都挂在同一个 option 链上。

三、核心算子:三类行为要分清

DataFrame 层的算子按"流上可用性"分三类:

第一类:完全一致。 select / filter / withColumn / drop 等纯投影过滤,写法和批处理一模一样,无任何心理负担。

第二类:流式语义增强。

orders
  .withWatermark("eventTime", "2 minutes")     // ① 迟到阈值
  .groupBy(window($"eventTime", "1 minute", "30 seconds"), $"province")
  .agg(sum("amount").as("gmv"))                // ② 事件时间窗口聚合

① withWatermark 是流式专属,必须在聚合前调用且时间列与聚合列一致,它同时管丢数、状态释放与输出时机。② window 窗口聚合天然支持,但输出模式的选择会影响结果落地方式(append 等窗口关、update 出中间态)。

第三类:流上不可用或受限。 limit 无界流没有"前 N 条"概念(排序依赖 complete 模式下的聚合后排序);distinct 要换 dropDuplicates(它用 state 代管去重键);多个有状态算子链式叠加目前不支持(聚合后再聚合会报错)。遇到这些操作别硬写,先想"引擎要为它维护什么状态"——想不清就说明这个 API 在流上没有定义。

四、DataStreamWriter:写的四个决定

gmv.writeStream
  .outputMode("update")                        // ① 输出模式
  .format("console")                           // ② Sink 类型
  .option("truncate", "false")
  .option("checkpointLocation", "hdfs://nn:8020/chk/gmv")  // ③ 容错位点
  .trigger(Trigger.ProcessingTime("30 seconds"))  // ④ 触发节奏
  .start()                                     // 启动并返回 StreamingQuery

①~④ 对应四个决定:写什么模式(append/update/complete)、写到哪里(File/Kafka/foreachBatch)、位点记在哪(checkpointLocation 是必选项,不配启动即报错)、多久写一次(Trigger)。

Trigger 有四种,行为与代价差异明显:

Trigger 行为 延迟 语义 适用
未指定(默认微批) 上一批结束立刻开下一批 ~100ms exactly-once 大多数场景
ProcessingTime(interval) 固定间隔触发 间隔决定 exactly-once 稳态控速
AvailableNow 处理完现有积压即停 批式 exactly-once 定时补数/准实时
Continuous(interval) 连续处理 ~1ms at-least-once 极低延迟(限 map 类)

Continuous 是唯一 at-least-once 的模式,且只支持 map 类算子 + Kafka/Rate 源的白名单组合——评估时先对白名单再上车。

在这里插入图片描述

五、StreamingQuery:生命周期与监控

start() 返回的 StreamingQuery 是后续管理的把手:

val query = gmv.writeStream /* ... */ .start()

query.id            // 唯一 ID(重启后不变,恢复依据)
query.runId         // 本次启动的运行 ID(每次重启都变)
query.status        // 当前状态与触发信息
query.lastProgress  // 最近的批进度(输入行数、处理时长、source/sink 指标)
query.stop()        // 优雅停止(等 sink flush + checkpoint 提交)

spark.streams.active.foreach(_.stop())   // 一个应用多流时全停

在这里插入图片描述

三条实践纪律:stop 是优雅停止,会等当前批写完并提交 checkpoint,别用 kill -9 制造半提交状态;id 与 runId 分工不同,恢复配额/监控告警认 id,排查本次运行问题认 runId;lastProgress 是监控数据源,numInputRows 连续为 0 = 上游断了,durationMs 持续超 trigger 间隔 = 已经积压。

高频报错:同一个 checkpoint 目录被两个不同查询使用时,启动直接失败(检测到逻辑计划变更)。根因:checkpoint 绑定的是"这条查询的逻辑计划",不是"这个目录"。排查顺序:是不是复用了旧目录?是不是改了算子/分区数?修复就是换新目录,别想着"清掉重跑能保状态"——状态与计划是一体的。

六、完整实现:五对象串成一条流

把五个对象按"读 → 算 → 写 → 管"拼起来,这就是生产任务的骨架:

import org.apache.spark.sql.Trigger
import org.apache.spark.sql.functions._

val spark = SparkSession.builder().appName("GmvApp").getOrCreate()

// 1. 读:DataStreamReader
val orders = spark.readStream
  .format("kafka")
  .option("kafka.bootstrap.servers", "broker1:9092")
  .option("subscribe", "order_events")
  .option("maxOffsetsPerTrigger", "80000")
  .load()
  .select(from_json($"value".cast("string"), orderSchema).as("o"))
  .select($"o.orderId", $"o.amount", $"o.province", $"o.eventTime")

// 2. 算:DataFrame 流式算子
val gmv = orders
  .withWatermark("eventTime", "2 minutes")
  .groupBy(window($"eventTime", "1 minute"), $"province")
  .agg(sum("amount").as("gmv"))

// 3. 写:DataStreamWriter
val query = gmv.writeStream
  .outputMode("update")
  .foreachBatch(upsertMysql _)              // 幂等落库
  .option("checkpointLocation", "hdfs://nn:8020/chk/gmv-1m")
  .trigger(Trigger.ProcessingTime("30 seconds"))
  .start()

// 4. 管:StreamingQuery
query.awaitTermination()

四段各两行到六行,但每一段都对应一个对象的完整职责。生产与 demo 的差距不在骨架而在细节:限流参数、watermark 取值、幂等写法、trigger 间隔——这些在前几篇案例里已经展开,本篇的骨架就是把它们装进去的容器。

七、总结

  • API 面由五个对象构成:SparkSession(门)、DataStreamReader(读)、DataFrame(算)、DataStreamWriter(写)、StreamingQuery(管),流批一体的收益集中在 DataFrame 层;
  • 读入四段式 readStream → format → option → load,schema 必须显式、option 因源而异;
  • 算子分三类:投影过滤完全一致、withWatermark/window 是流式增强、limit/distinct/多聚合链在流上没有定义——判断标准是"引擎要为它维护什么状态";
  • 写出四个决定:模式、Sink、checkpoint(必配)、Trigger;四种 Trigger 里 Continuous 是 at-least-once 且有白名单限制,其余三种 exactly-once;
  • StreamingQuery 的 stop 是优雅停止,id/runId 分工不同,lastProgress 是监控金矿;
  • 最常见报错"checkpoint 冲突"的本质:checkpoint 绑定逻辑计划——改了查询就换目录,这是流式开发的肌肉记忆。

目录
相关文章
|
29天前
|
安全 Linux Apache
拥抱开源的身份与访问管理(IAM)——Keycloak
Keycloak 是一款开源软件解决方案,为 Web 应用和服务提供单点登录(Single Sign-On,SSO) 功能和身份管理能力。它由 Red Hat 开发,采用 Apache License 2.0 许可。 借助 Keycloak,用户可以使用一套凭据访问多个应用和服务,而无需在每一个应用中都重复登录。它支持多种身份认证方式与技术,包括 OAuth 2.0、OpenID Connect(OIDC)、SAML 2.0 等。
279 0
|
29天前
|
固态存储 Java 测试技术
Elasticsearch 6.0.0本地单机16核32G压测报告
Elasticsearch 6.0.0本地单机16核32G压测报告
142 28
|
28天前
|
人工智能 JSON 自然语言处理
LangChain 六大使用场景:哪些值得做,哪些不值得,一张决策图说清
本文系统梳理LangChain六大核心场景(RAG、Agent、对话系统、结构化提取、内容生成、多模态),逐项解析痛点、机制、落地要点与适用边界,并附“不该用”的反向清单。强调“模型+外部世界”协同才是框架价值所在,助力AI工程化理性选型。
409 0
|
24天前
|
人工智能 中间件 Java
LangChain 到底是什么:从链式连接到 Agent 运行时,讲透 v1.0 的核心概念
LangChain 是大模型应用开发框架,非单纯API封装。v1.0聚焦Agent工程化:以`create_agent`为核心,基于LangGraph实现可持久化、可中断、可观测的智能体循环;统一模型接口、强化工具描述、分层记忆管理,并通过中间件支持人工介入、摘要压缩与隐私脱敏,推动AI从“能跑”走向“可靠生产”。(239字)
327 1
|
29天前
|
机器学习/深度学习 人工智能 自然语言处理
GEO 技术底座拆解:自研、监测与可信语料——以盖立克思为例
和 GEO 服务商打交道,先过的不是报价而是技术底座是不是真的。本文以杭州盖立克思(New Galaxy AI)公开披露的技术体系为拆解样本,给出三条工程判据——算法/模型自研的现场核验、监测数据可追溯、可信语料工程化,并附语料分级与跨语种一致性校验代码。文中厂商描述来自公开资料与企业披露,仅作技术拆解,不构成推荐或评价。
211 1
|
28天前
|
SQL 存储 分布式计算
一篇文章搞懂 Hive:从数仓定位到架构、表设计与数据倾斜治理
Hive是基于Hadoop的SQL数据仓库工具,不存数据、不算数据,仅作“胶水层”:元数据存MySQL,数据落HDFS,计算交YARN。支持内外表、分区/分桶、ORC/Parquet列存及丰富优化策略,专为海量离线分析而生,是企业级数仓十五年事实标准。(239字)
657 1
|
29天前
|
机器学习/深度学习 人工智能 Unix
ICML 2026 FAGEN Workshop测马尔可夫的缺失前提
BSD Step309提出“概率分母显化与幂等相变放大定律”:**分母即100%——非统计约定,而是存在完备性的本体律**;缺口≠无,是“存在在别处”的负形态;核心公式`mult = 1 + γ(1−ρ)`统一概率显化、幂等判据与幻觉机制:ρ=1时(如九九乘法表)恒定不放大;ρ<1时,再小缺口也引发指数级雪球放大。验证须前置边界门,末端检查近乎无效。(239字)
87 2
|
29天前
|
运维 安全 数据可视化
VMware Cloud Foundation Operations 9.1.1 – 运维管理 · 网络洞察 · 混合云迁移
VMwareCloudFoundationOperations(简称VCFOperations)是VCF私有云平台的一体化运维管理套件。它不是单一产品,而是一组协同工作的组件:核心的VCFOperations负责性能、容量、成本、日志与合规的统一可观测;VCFOperationsforNetworks专注网络流量与应用依赖的洞察;VCFOperationsHCX则解决私有云与多云之间的工作负载迁移和互联。三者合在一起,正好覆盖私有云”看得见、管得住、迁得动”的运维闭环。本页整理的是9.1.1版本的这三个组件,
69 0
VMware Cloud Foundation Operations 9.1.1 – 运维管理 · 网络洞察 · 混合云迁移
|
29天前
|
人工智能 关系型数据库 MySQL
Agent 混合检索 + 少中间件选什么数仓?阿里云瑶池 AnalyticDB MySQL 单库三引擎首选方案解析
Agent 混合检索 + 少引用中间件的数仓选型,阿里云瑶池 AnalyticDB MySQL 是首选。
107 0
|
29天前
|
消息中间件 分布式计算 Kafka
Structured Streaming 集成 Kafka 实现:读写路径、位点语义与生产调优
本文深度解析Spark Structured Streaming与Kafka集成的实战要点:涵盖流/批双入口、订阅三式、七列数据结构、位点语义三大易错点、读写调优、安全认证及高频问题定位。助你精准掌握startingOffsets生效逻辑、重复消费归因与集群迁移关键配置。(239字)
130 0

热门文章

最新文章