使用 transformWithState 进行异步处理

Python transformWithState 支持基于 asyncio的异步处理。 通过在分组键上并发运行状态操作和用户逻辑,并对进程间通信进行批处理,异步处理只需少量代码改动即可获得高于同步处理的吞吐量。 这种吞吐量提升不需要任何第三方异步库。 高级用户可以通过异步编程模式和异步库进一步优化应用。

异步处理同时支持微批处理和实时模式查询。 对于单个分组键,异步处理保持行顺序。 不同的分组键会同时运行。

要使用异步处理,应实现 AsyncStatefulProcessor,而不是同步的 StatefulProcessor。 该 AsyncStatefulProcessor API 与同步 StatefulProcessor API 基本一致,因此大多数应用只需少量修改即可使用异步 API。 请参阅实现 AsyncStatefulProcessor。

关于同步 transformWithState API 和核心概念,请参见“使用 transformWithState 构建自定义有状态应用程序”。

Requirements

异步处理有以下要求:

  • 可在 Databricks Runtime 19 及以上版本中使用,或在环境版本 6 及以上的无服务器计算平台上使用。
  • 仅适用于 Python 基于行的 transformWithState API。 不支持对transformWithState或 Scala transformWithStateInPandas API 进行异步处理。
  • 在 Lakeflow 管道中,配置管道以使用 PREVIEW 通道。 这一要求适用于经典和无服务器流水线计算。 当前通道不支持异步处理。 请参见管道配置和Lakeflow 管道运行时通道中的channel。

实现一个 AsyncStatefulProcessor

要将同步 StatefulProcessor 转换为 AsyncStatefulProcessor,需进行以下修改:

  • 用 async def 关键字定义 API 方法(init、close、handleInputRows、handleExpiredTimer 和 handleInitialState)。
  • 使用 await 读取和更新状态和计时器值,或使用 Python 的 asyncio 库运行它们。 这适用于状态操作,如 valueState.get() 和 定时器操作,如 registerTimer。 创建状态对象(如 handle.getValueState)仍是同步的。

异步处理需要考虑以下因素:

  • 如果你的应用程序将数据存储在成员变量或外部系统中,Databricks 建议你重写逻辑以确保并发执行的安全。 由于 handleInputRows 和 handleExpiredTimer 可以在分组键间同时运行,交错运行不得破坏共享数据。 大多数应用程序已经满足这一要求。
  • Databricks 建议不要从状态操作中捕捉或抑制错误。 Apache Spark 会帮你处理这些错误。 如果状态操作失败,Apache Spark 会使任务失败并重试它。
    • 在 AsyncStatefulProcessor 中,状态操作错误会由系统代为处理,且不会暴露给你的代码。
    • 在同步 StatefulProcessor 中,状态操作错误会在代码中引发,但抑制它们可能会损害数据正确性。

示例:统计每个分组键的行数

以下示例定义了一个 AsyncCountProcessor,它统计每个分组键的行数。 value_schema 变量定义存储运行计数的 ValueState 的架构。 与同步的 StatefulProcessor 相比,不同之处在于每个方法上的 async def 关键字,以及状态读取和更新操作上的 await。 在init中对getValueState的调用仍保持同步。 按照以下代码定义处理器:

from pyspark.sql import Row
from pyspark.sql.streaming import AsyncStatefulProcessor, AsyncStatefulProcessorHandle
from pyspark.sql.types import StructType, StructField, LongType

value_schema = StructType([StructField("count", LongType(), True)])

class AsyncCountProcessor(AsyncStatefulProcessor):
  async def init(self, handle: AsyncStatefulProcessorHandle) -> None:
    self.count = handle.getValueState("count", value_schema)

  async def handleInputRows(self, key, rows, timerValues):
    total = (await self.count.get() or (0,))[0]
    for _ in rows:
      total += 1
    await self.count.update((total,))
    yield Row(action=key[0], count=total)

  async def close(self) -> None:
    pass

用异步处理器运行查询

要用异步处理器运行查询,将你的 AsyncStatefulProcessor 传递给 transformWithState。 查询使用与同步路径相同的语法。 异步和同步 API 共享相同的状态格式,因此你可以在 AsyncStatefulProcessor 和同步 StatefulProcessor 之间切换现有查询,同时重用相同的检查点。

示例:events 示例数据集中的事件计数

以下示例针对 events 示例数据集运行 AsyncCountProcessor。 每条记录都有一个 time 字段(纪元秒),以及一个值为 Open 或 Close 的 action 字段。 查询按 action 分组,并统计每种操作类型的事件数。 更多样本数据集请参见 样本数据集。

变量 input_schema 定义了源记录的架构,output_schema 变量定义了处理器发出的行的架构。 要将示例数据集作为流读取,请定义两个架构,然后按以下代码启动查询:

from pyspark.sql.types import StructType, StructField, StringType, LongType

input_schema = StructType([
  StructField("time", LongType(), True),
  StructField("action", StringType(), True),
])

output_schema = StructType([
  StructField("action", StringType(), True),
  StructField("count", LongType(), True),
])

events = (
  spark.readStream.schema(input_schema)
    .option("maxFilesPerTrigger", 10)
    .json("/databricks-datasets/structured-streaming/events")
)

q = (
  events.groupBy("action")
    .transformWithState(
      statefulProcessor=AsyncCountProcessor(),
      outputStructType=output_schema,
      outputMode="Update",
      timeMode="None",
    )
    .writeStream.format("memory")
    .queryName("async_counts")
    .trigger(availableNow=True)
    .start()
)

q.awaitTermination()

查询完成后,请查看每种动作类型的运行计数,如下代码所示:

display(spark.sql("SELECT action, MAX(count) AS count FROM async_counts GROUP BY action ORDER BY action"))

异步状态与定时器操作

在 AsyncStatefulProcessor 中,读取或写入值的状态变量和计时器操作是异步的。 大多数这些操作返回一个结果,你用 await来检索。 返回集合的操作则返回一个异步迭代器,你用 async for来处理。 关于 async/await 以及 Python 中异步迭代器的介绍,请参见 Python asyncio 文档。

下表列出了返回单个结果的操作,你可以用 await 获取该结果:

Class 使用 await 的操作
AsyncValueState exists、get、update、clear
AsyncMapState exists、getValue、containsKey、updateValue、removeKey、clear
AsyncListState exists、put、appendValue、appendList、clear
AsyncStatefulProcessorHandle registerTimer、deleteTimer

下表列出了返回异步迭代器的操作,你可以使用 async for 检索:

Class 使用 async for 的操作
AsyncMapState iterator、keys、values
AsyncListState get
AsyncStatefulProcessorHandle listTimers

示例: async for

例如,要读取 AsyncListState 中的值,可以像以下代码那样使用 async for 进行迭代:

total = 0
async for value in self.items.get():
  total += value[0]

创建状态对象和删除状态变量的方法保持同步: getValueState、 getMapState、 getListState和 deleteIfExists。

关于每种状态类型的描述,请参见 自定义状态类型。

用异步编程模式进行优化

异步处理在逻辑等待外部操作(如网络请求)时非常有用。 不要依次等待每个请求,而是使用asyncio并发运行这些请求,从而减少空闲时间。

示例:运行并发请求 asyncio.gather

以下示例使用 asyncio.gather 并发所有每行HTTP请求并等待它们完成,然后将最大得分存储在状态中。 按照以下代码定义处理器:

import asyncio
import aiohttp
from pyspark.sql import Row
from pyspark.sql.streaming import AsyncStatefulProcessor

class HttpScoreRowGatherProcessor(AsyncStatefulProcessor):
  async def init(self, handle):
    self._score_state = handle.getValueState("last_score", "score double")
    self._session = aiohttp.ClientSession()

  async def _fetch_score(self, row) -> float:
    async with self._session.get(
      f"https://api.example.com/score/{row.event_id}"
    ) as resp:
      return (await resp.json())["score"]

  async def handleInputRows(self, key, rows, timerValues):
    user_id = key[0]
    scores = await asyncio.gather(*[self._fetch_score(row) for row in rows])

    max_score = max(scores)
    await self._score_state.update((max_score,))
    yield Row(user_id=user_id, score=max_score)

  async def close(self):
    await self._session.close()