使用 ForEachBatch 将管道中的数据写入任意数据接收器

ForEachBatch 接收器将流作为一系列微批进行处理。 可以使用类似于 Apache Spark 结构化流式处理foreachBatch的自定义逻辑在Python中处理每个批处理。 借助 Lakeflow 管道 ForEachBatch 接收器,您可以转换、合并或将流式处理数据写入到一个或多个不原生支持流式写入的目标。

ForEachBatch 汇聚点提供以下功能:

  • 针对每个微批的自定义逻辑:ForEachBatch 是一个灵活的流式接收器。 可以使用Python代码应用任意操作(例如合并到外部表、写入多个目标或执行 upserts)。
  • 完全刷新支持:管道按流管理检查点,因此在执行管道完全刷新时,检查点会自动重置。 使用 ForEachBatch 接收器时,你需要负责在发生这种情况时管理下游数据重置。
  • Unity 目录支持:ForEachBatch 接收器支持所有 Unity 目录功能,例如读取或写入 Unity 目录卷或表。
  • 有限的内部管理:管道不会跟踪从 ForEachBatch 接收器写入的数据,因此无法清理这些数据。 你负责任何下游数据管理。
  • 事件日志条目:管道事件日志记录每个 ForEachBatch 接收器的创建和使用。 如果Python函数不可序列化,则会在事件日志中看到一个警告条目,其中包含其他建议。

注释

  • ForEachBatch 接收器专为流式查询设计,例如 append_flow。 它不适用于仅限批处理的管道或 AutoCDC 语义。
  • 此页上介绍的 ForEachBatch 接收器适用于管道。 Apache Spark 结构化流式处理也支持 foreachBatch。 有关结构化流式处理 foreachBatch 的信息,请参阅使用 foreachBatch 写入任意数据接收器。

何时使用 ForEachBatch 滤器

当管道需要无法通过内置接收器格式(如 delta 或 kafka)提供的功能时,请使用 ForEachBatch 接收器。 典型用例包括:

  • 合并或更新插入到 Delta Lake 表:为每个微批运行自定义合并逻辑(例如,处理更新的记录)。
  • 写入多个或不支持的目标:将每个批的输出写入到多个表或不支持流式写入的外部存储系统(如某些 JDBC 接收器)。
  • 应用自定义逻辑或转换:直接操作Python中的数据(例如,使用专用库或高级转换)。

有关内置接收器或使用Python创建自定义接收器的信息,请参阅 Lakeflow 管道中的接收器。

有关 @dp.foreach_batch_sink() Python API 参考,请参阅 foreach_batch_sink。

完全刷新

由于 ForEachBatch 使用流式处理查询,因此管道会跟踪每个流的检查点目录。 完全刷新时:

  • 检查点目录已重置。
  • 你的接收器函数 (foreach_batch_sink UDF) 会看到一个从 0 开始的全新 batch_id 周期。
  • 目标系统中的数据不会被管道自动清理(因为管道不知道你的数据写入位置)。 如果需要全新开始场景,你必须手动删除或截断 ForEachBatch 接收器填充的外部表或位置。

使用 Unity 目录功能

Spark 结构化流 foreach_batch_sink 中所有现有的 Unity Catalog 功能仍然可用。

这包括写入托管或外部 Unity Catalog 表。 你可以像在任何 Apache Spark 结构化流式处理作业中一样,将微批写入到 Unity Catalog 托管或外部表。

事件日志条目

创建 ForEachBatch 汇集器时,会将 SinkDefinition 事件与 "format": "foreachBatch" 一同添加到管道的事件日志中。

这使您能够跟踪 ForEachBatch 接收器的使用情况,并查看有关您接收器的警告。

与 Databricks Connect 配合使用

如果提供的函数 不可序列化 (Databricks Connect 的重要要求),则事件日志包含一个 WARN 条目,建议在需要 Databricks Connect 支持的情况下简化或重构代码。

例如,如果你使用 dbutils 在 ForEachBatch UDF 中获取参数,可以改为在使用该参数之前获取它:

# Instead of accessing parameters within the UDF...
def foreach_batch(df, batchId):
  value = dbutils.widgets.get ("X") + str (i)

# ...get the parameters first, and use them within the UDF:
argX = dbutils.widgets.get ("X")

def foreach_batch(df, batchId):
  value = argX + str (i)

最佳做法

  1. 保持 ForEachBatch 函数简洁:避免多线程、大量库依赖或在内存中进行大型数据操作。 复杂或有状态逻辑可能导致序列化错误或性能瓶颈。
  2. 监视检查点文件夹:对于流式处理查询,管道按流而不是按接收器管理检查点。 如果管道中有多个流,则每个流都有自己的检查点目录。
  3. 验证外部依赖项:如果依赖于外部系统或库,请检查它们是否已安装在所有群集节点上或容器中。
  4. 请注意 Databricks Connect:如果您的环境将来可能会迁移到 Databricks Connect,请检查您的代码是否可序列化,并且不依赖于 dbutils UDF 中的 foreach_batch_sink。

局限性

  • ForEachBatch无清理机制:由于您的自定义Python代码可能在任何位置写入数据,管道无法进行清理或跟踪。 您必须自行管理写入目标的数据或制定相关的保留策略。
  • 微批处理中的指标:管道收集流式指标,但某些情况下使用 ForEachBatch 可能会导致指标不完整或异常。 这是由于 ForEachBatch 的底层灵活性,使得系统难以跟踪数据流和行。
  • 支持在没有多次读取的情况下写入多个目标:某些客户可能使用 ForEachBatch 从源中读取一次,然后写入多个目标。 若要实现此目的,您必须在ForEachBatch函数中包含df.persist或df.cache。 使用这些选项,Azure Databricks尝试只读取一次数据。 如果没有这些选项,查询将生成多个读取。 以下代码示例中不包括此内容。
  • 与 Databricks Connect 一起使用:如果管道在 Databricks Connect 上运行, foreachBatch 则用户定义的函数(UDF)必须可序列化且无法使用 dbutils。 如果管道检测到不可序列化的 UDF,会引发警告,但不会使管道失败。
  • 不可序列化的逻辑:引用本地对象、类或不可调用的资源的代码可能会中断 Databricks Connect 上下文。 使用纯Python模块并确认如果 Databricks Connect 是必需的,则不使用引用(例如,dbutils)。

例子

基本语法示例

from pyspark import pipelines as dp

# Create a ForEachBatch sink
@dp.foreach_batch_sink(name = "my_foreachbatch_sink")
def feb_sink(df, batch_id):
  # Custom logic here. You can perform merges,
  # write to multiple destinations, etc.
  return

# Create source data for example:
@dp.table()
def example_source_data():
  return spark.range(5)

# Add sink to an append flow:
@dp.append_flow(
    target="my_foreachbatch_sink",
)
def my_flow():
  return spark.readStream.format("delta").table("example_source_data")

使用示例数据创建简单管道

此示例使用 NYC 出租车示例。 它假定工作区管理员已启用 Databricks 公共数据集目录。 对于接收器,将 my_catalog.my_schema 更改为你有权访问的目录和架构。

from pyspark import pipelines as dp
from pyspark.sql.functions import current_timestamp

# Create foreachBatch sink
@dp.foreach_batch_sink(name = "my_foreach_sink")
def my_foreach_sink(df, batch_id):
    # Custom logic here. You can perform merges,
    # write to multiple destinations, etc.
    # For this example, we are adding a timestamp column.
    enriched = df.withColumn("processed_timestamp", current_timestamp())
    # Write to a Delta location
    enriched.write \
      .format("delta") \
      .mode("append") \
      .saveAsTable("my_catalog.my_schema.trips_sink_delta")
    # Return is optional here, but generally not used for the sink
    return

# Create an append flow that reads sample data,
# and sends it to the ForEachBatch sink
@dp.append_flow(
    target="my_foreach_sink",
)
def taxi_source():
  df = spark.readStream.table("samples.nyctaxi.trips")
  return df

写入多个目标

此示例写入多个目标。 它演示了使用 txnVersion 和 txnAppId 使对 Delta Lake 表的写入成为幂等操作。 有关详细信息,请参阅使用 foreachBatch 进行幂等表写入。

假设我们要写入两个表table_a和table_b,并且假设在一个批处理中,写入table_a成功,而写入table_b失败。 当重新运行批时,(txnVersion、txnAppId)对将允许 Delta 忽略对 table_a 的重复写入,而仅将该批写入 table_b。

from pyspark import pipelines as dp

app_id = "my-app-name" # different applications that write to the same table should have unique txnAppId

# Create the ForEachBatch sink
@dp.foreach_batch_sink(name="user_events_feb")
def user_events_handler(df, batch_id):
    # Optionally do transformations, logging, or merging logic
    # ...

    # Write to a Delta table
    df.write \
     .format("delta") \
     .mode("append") \
     .option("txnVersion", batch_id) \
     .option("txnAppId", app_id) \
     .saveAsTable("my_catalog.my_schema.example_table_1")

    # Also write to a JSON file location
    df.write \
      .format("json") \
      .mode("append") \
      .option("txnVersion", batch_id) \
      .option("txnAppId", app_id) \
      .save("/tmp/json_target")
    return

# Create source data for example
@dp.table()
def example_source():
  return spark.range(5)


# Create the append flow, and target the ForEachBatch sink
@dp.append_flow(target="user_events_feb", name="user_events_flow")
def read_user_events():
    return spark.readStream.format("delta").table("example_source")

使用 spark.sql()

可以在 ForEachBatch 接收器中使用 spark.sql() ,如以下示例所示。

from pyspark import pipelines as dp
from pyspark.sql import Row

@dp.foreach_batch_sink(name = "example_sink")
def feb_sink(df, batch_id):
  df.createOrReplaceTempView("df_view")
  df.sparkSession.sql("MERGE INTO target_table AS tgt " +
            "USING df_view AS src ON tgt.id = src.id " +
            "WHEN MATCHED THEN UPDATE SET tgt.id = src.id * 10 " +
            "WHEN NOT MATCHED THEN INSERT (id) VALUES (id)"
          )
  return

# Create target delta table
spark.range(5).write.format("delta").mode("overwrite").saveAsTable("target_table")

# Create source table
@dp.table()
def src_table():
  return spark.range(5)

@dp.append_flow(
    target="example_sink",
)
def example_flow():
  return spark.readStream.format("delta").table("src_table")

与外部 Delta Lake 表合并

from pyspark import pipelines as dp
from pyspark.sql.functions import col
from delta.tables import DeltaTable

@dp.foreach_batch_sink(name = "external_merge_feb")
def foreachBatchFunc(df, batchId):
  out = DeltaTable.forName(df.sparkSession, "target_table")
  out.alias("target") \
    .merge(df.alias("source"), "source.value = target.value") \
    .whenMatchedUpdateAll() \
    .whenNotMatchedInsertAll() \
    .execute()

@dp.append_flow(
    target="external_merge_feb",
    name="merge_flow"
)
def read_data():
    return (
        spark.readStream.format("delta")
        .load("/tmp/source_delta_table")
        .filter(col("value").isNotNull())
    )

常见问题 (FAQ)

我可以在 ForEachBatch 接收器中使用 dbutils 吗?

如果打算在非 Databricks Connect 环境中运行管道, dbutils 则可以正常工作。 但是,如果你使用 Databricks Connect,dbutils 在你的 foreachBatch 函数中不可访问。 如果管道检测到 dbutils 的使用,可能会引发警告,以帮助你避免中断。

我可以对单个 ForEachBatch 接收器使用多个流吗?

是的。 你可以定义多个流(使用 @dp.append_flow),它们都指向同一个接收器名称,但它们各自维护自己的检查点。

管道会处理我的目标的数据保留或清理吗?

否。 由于 ForEachBatch 接收器可以写入任何任意位置或系统,因此管道无法自动管理或删除该目标中的数据。 必须在自定义代码或外部进程中处理这些操作。

如何排查 ForEachBatch 函数中的序列化错误或失败?

查看群集驱动程序日志或管道事件日志。 对于 Spark Connect 相关的序列化问题,请检查函数是否仅依赖于可序列化Python对象,并且不引用不允许的对象(如打开的文件句柄或 dbutils)。