Verwenden von „foreachBatch” zum Schreiben in beliebige Datensenken

Diese Seite zeigt, wie Sie foreachBatch mit strukturiertem Streaming verwenden, um die Ausgabe einer Streamingabfrage in Datenquellen zu schreiben, die nicht über eine vorhandene Stream-Senke verfügen.

Mit dem Codemuster streamingDF.writeStream.foreachBatch(...) können Sie Batchfunktionen auf die Ausgabedaten der einzelnen Mikrobatches der Streamingabfrage anwenden. Funktionen, die mit foreachBatch verwendet werden, akzeptieren zwei Parameter:

  • Ein DataFrame, der die Ausgabedaten eines Mikrobatches enthält.
  • Die eindeutige ID des Mikrobatches.

Sie müssen für Delta Lake-Zusammenführungsvorgänge bei strukturiertem Streaming foreachBatch verwenden. Weitere Informationen finden Sie unter Ausführen eines Upserts aus Streamingabfragen mithilfe von foreachBatch.

Anwenden zusätzlicher DataFrame-Vorgänge

Viele DataFrame- und Dataset-Vorgänge werden in Streaming-DataFrames nicht unterstützt, da Spark die Erstellung inkrementeller Pläne in diesen Fällen nicht unterstützt. Mit foreachBatch() können Sie einige dieser Vorgänge auf jede Mikrobatchausgabe anwenden. Sie können beispielsweise foreachBatch() und den SQL-Vorgang MERGE INTO verwenden, um die Ausgabe von Streaming-Aggregationen im Aktualisierungsmodus in eine Delta Lake-Tabelle zu schreiben. Weitere Details finden Sie in MERGE INTO.

Wichtig

  • foreachBatch() bietet nur eine At-least-once-Schreibgarantie. Sie können jedoch das der Funktion zur Verfügung gestellte batchId verwenden, um die Ausgabe zu deduplizieren und eine Exactly-Once-Garantie zu erhalten. In beiden Fällen müssen Sie selbst über die End-to-End-Semantik entscheiden.
  • foreachBatch() funktioniert nicht mit dem kontinuierlichen Verarbeitungsmodus , da er grundsätzlich auf der Mikro-Batch-Ausführung einer Streaming-Abfrage angewiesen ist. Wenn Sie Daten im kontinuierlichen Modus schreiben, verwenden Sie stattdessen foreach().
  • Bei der Verwendung von foreachBatch mit einem zustandsbehafteten Operator ist es wichtig, den Batch vollständig zu nutzen, bevor die Verarbeitung abgeschlossen ist. Weitere Informationen finden Sie unter Vollständige Nutzung aller Datenrahmen-Batches.

Behandle leere DataFrames

Für foreachBatch() kann ein leeres DataFrame zurückgegeben werden, und Ihr Code muss dieses Szenario bewältigen. Andernfalls schlägt Ihre Abfrage möglicherweise fehl.

Wenn Delta Lake beispielsweise die Streamingquelle ist, übergeben diese Szenarien möglicherweise ein leeres DataFrame an foreachBatch():

  • OPTIMIZE ohne Dateien zum Verarbeiten: Wenn eine OPTIMIZE Operation auf der Delta Lake-Quelltabelle ausgeführt wird, aber keine Dateien verarbeitet werden müssen, schreibt Structured Streaming einen Offset-Logeintrag, um die Tabellenversion zu erhöhen. Dies erzeugt einen leeren Mikrobatch auf der Spüle, obwohl keine Dateien gelesen werden.
  • Dateikürzung auf der Ebene des physischen Plans: Wenn Prädikats-Filterung oder Dateikürzung alle Datensätze auf der Ebene des physischen Plans entfernt, ist das Ergebnis ein leerer Commit für die Senke.

Der Benutzercode muss leere DataFrames verarbeiten, um einen ordnungsgemäßen Vorgang zu ermöglichen. Sehen Sie sich die folgenden Beispiele an:

Python

def process_batch(output_df, batch_id):
  # Process valid DataFrames only
  if not output_df.isEmpty():
    # business logic
    pass

streamingDF.writeStream.foreachBatch(process_batch).start()

Scala

  .foreachBatch(
          (outputDf: DataFrame, bid: Long) => {
             // Process valid DataFrames only
             if (!outputDf.isEmpty) {
                // business logic
             }
         }
  ).start()

Verhaltensänderungen für foreachBatch in Databricks Runtime 14.0

In Databricks Runtime 14.0 und höher bei der Berechnung, die mit dem Standardzugriffsmodus konfiguriert ist, gelten die folgenden Verhaltensänderungen:

  • print() Befehle schreiben die Ausgabe in die Treiberlogs.
  • Sie können nicht auf das Untermodul dbutils.widgets innerhalb der Funktion zugreifen.
  • Alle Dateien, Module oder Objekte, auf die in der Funktion verwiesen wird, müssen serialisierbar und in Spark verfügbar sein.

Wiederverwenden vorhandener Batchdatenquellen

Mit foreachBatch() können Sie vorhandene Batchdaten-Writer für Datensenken verwenden, die möglicherweise keine Unterstützung für strukturiertes Streaming bieten. Hier sind einige Beispiele:

Viele andere Batchdatenquellen können von foreachBatch() aus verwendet werden. Siehe Herstellen einer Verbindung mit Datenquellen und externen Diensten.

Schreiben an mehrere Speicherorte

Wenn Sie die Ausgabe einer Streamingabfrage an mehrere Speicherorte schreiben müssen, empfiehlt Databricks die Verwendung mehrerer Writer für strukturiertes Streaming, um eine optimale Parallelisierung und einen optimalen Durchsatz zu erzielen.

Die Verwendung foreachBatch zum Schreiben in mehrere Senken serialisiert die Ausführung von Streamingschreibvorgängen, was die Wartezeit für jeden Mikrobatch erhöhen kann.

Wenn Sie foreachBatch zum Schreiben in mehrere Delta-Lake-Tabellen verwenden, siehe foreachBatch für idempotente Tabellenschreibvorgänge verwenden.

Verbrauchen Sie jeden Batch-DataFrame vollständig

Wenn Sie zustandsbehaftete Operatoren (z. B. die Verwendung dropDuplicatesWithinWatermark) verwenden, muss jede Batch-Iteration den gesamten DataFrame verwenden oder die Abfrage neu starten. Wenn Sie den gesamten DataFrame nicht nutzen, schlägt die Streamingabfrage mit dem nächsten Batch fehl.

Dies kann in mehreren Fällen geschehen. Die folgenden Beispiele zeigen, wie Abfragen behoben werden, die ein DataFrame nicht ordnungsgemäß nutzen.

Eine Teilmenge des Batches gezielt verwenden

Wenn Sie sich nur um eine Teilmenge des Batches kümmern, könnten Sie Code wie den folgenden haben.

from pyspark.sql.functions import expr

stream = spark.readStream.format("rate").option("rowsPerSecond", "100").load()
# creates a stateful operator:
streamWithWatermark = stream.withWatermark("timestamp", "15 minutes").dropDuplicatesWithinWatermark()

def partial_func(batch_df, batch_id):
  batch_df.show(2)

q = streamWithWatermark.writeStream \
  .foreachBatch(partial_func) \
  .option("checkpointLocation", checkpoint_dir) \
  .trigger(processingTime='2 seconds') \
  .start()

In diesem Fall verarbeitet batch_df.show(2) nur die ersten beiden Elemente im Batch, was auch erwartet wird. Wenn jedoch mehr Elemente vorhanden sind, müssen sie genutzt werden. Der folgende Code verwendet den vollständigen DataFrame.

from pyspark.sql.functions import expr

stream = spark.readStream.format("rate").option("rowsPerSecond", "100").load()
streamWithWatermark = stream.withWatermark("timestamp", "15 minutes").dropDuplicatesWithinWatermark()

# function to do nothing with a row
def do_nothing(row):
  pass

def partial_func(batch_df, batch_id):
  batch_df.show(2)
  batch_df.foreach(do_nothing) # silently consume the rest of the batch

q = streamWithWatermark.writeStream \
  .foreachBatch(partial_func) \
  .option("checkpointLocation", checkpoint_dir) \
  .trigger(processingTime='2 seconds') \
  .start()

Hier ignoriert die do_nothing Funktion im Hintergrund den Rest des DataFrames.

Behandeln eines Fehlers in einem Batch

Bei der Fehlerbehandlung in foreachBatch, empfiehlt Databricks, die Streamingabfrage schnell scheitern zu lassen und stattdessen die Orchestrierungsebene wie Lakeflow Jobs oder Apache Airflow zu verwenden, um die Wiederholungslogik zu verwalten. Dies ist viel sicherer als das Erstellen komplexer Wiederholungsschleifen in Ihrem Code, bei denen Datenverlust auftreten kann.

Hier sind Richtlinien, die auf Ihrem Schreibziel basieren:

Ziel Beispiele Leitlinien
DataFrame-Vorgänge Delta Lake-Tabellen Sie müssen die txnAppId- und txnVersion-Schreiboptionen verwenden und txnVersion an batchId binden, um die Idempotenz zu gewährleisten und die Datenkorrektheit bei Wiederholungen zu schützen. Ausnahmen nicht lokal abfangen und wiederholen. Stattdessen empfiehlt Databricks, Fehler propagieren zu lassen, damit die Spark-Metriken korrekt bleiben, die Daten nicht dupliziert werden und der Orchestrator den vollständigen Batch sauber wiederholen kann.
Benutzerdefinierter Code und externe Ziele .collect(), OLTP-Datenbanken, Nachrichtenwarteschlangen, APIs Implementieren Sie Ihre eigene Idempotenz. Sie müssen davon ausgehen, dass jeder Vorgang batchübergreifend wiederholt werden kann und erneut ausgeführt wird. Wenn der batchId gleich bleibt, muss das Ergebnis Ihres Vorgangs gleich bleiben. Sie können rein vorübergehende Fehler wie kurze Verbindungstimeouts wiederholen, aber äußerst vorsichtig sein, um teil- oder duplizierte Schreibvorgänge zu vermeiden, wenn der Wiederholungsvorgang letztendlich fehlschlägt. Der sicherste Ansatz besteht darin, Fehler sich ausbreiten zu lassen und dem Orchestrator zu ermöglichen, den gesamten Batch erneut auszuführen.

Hier sind einige Beispiele für Ausnahmetypen und Empfehlungen für die Behandlung in foreachBatch:

Ausnahmetyp Beispiele Empfohlene Maßnahme
Vorübergehende Sinkfehler SQLTransientConnectionException, HTTP 429, Timeouts Erkennen: erneut versuchen oder an eine Warteschlange für unzustellbare Nachrichten senden. Für Delta Lake-Senken lassen Sie den Fehler stattdessen weitergegeben werden, wie die obige DataFrame-Operationszeile beschreibt.
Duplikat- oder Schlüsseleinschränkungsverletzungen, wenn die Senke idempotent ist SQLIntegrityConstraintViolationException Abfangen: protokollieren und unterdrücken
Benutzerdefinierte wiederholbare Fehler Eingebettete Socket-Ausnahmen, wiederholbare Datenbankfehler Abfangen: Erhöhe die Metriken und erlaube eine kontrollierte Fortsetzung
Logik- oder Schemafehler NullPointerException, AttributeError, Schema-Fehlanpassung Propagate: Spark die Abfrage fehlschlagen lassen
Nicht-wiederholbare Senkenfehler oder unentdeckte Logikfehler ValueError, PermissionError Propagate: Spark die Abfrage fehlschlagen lassen
Kritische Fehler OutOfMemoryError, beschädigter Zustand, Datenintegritätsverletzungen Propagate: Lass Spark die Abfrage fehlschlagen

Codebeispiele: Ausnahmebehandlung

In den folgenden Beispielen wird absichtlich ein Fehler in foreach ausgelöst, um verschiedene Ansätze zur Fehlerbehandlung zu zeigen.

from pyspark.sql.functions import expr

stream = spark.readStream.format("rate").option("rowsPerSecond", "100").load()
# creates a stateful operator:
streamWithWatermark = stream.withWatermark("timestamp", "15 minutes").dropDuplicatesWithinWatermark()

def foreach_func(row):
  # handle the row, but in this case, for the sample, will just raise an error:
  raise Exception('error')

def partial_func(batch_df, batch_id):
  try:
    batch_df.foreach(foreach_func)
  except Exception as e:
    print(e) # or whatever error handling you want to have


q = streamWithWatermark.writeStream \
  .foreachBatch(partial_func) \
  .option("checkpointLocation", checkpoint_dir) \
  .trigger(processingTime='2 seconds') \
  .start()

Der obige Code behandelt und unterdrückt den Fehler im Hintergrund und verwendet möglicherweise nicht den Rest des Batches. Es gibt zwei Optionen für die Behandlung dieser Situation.

Zuerst können Sie den Fehler erneut auslösen. Dadurch wird er an die Orchestrierungsebene übergeben, um den Batch erneut auszuführen. Dies kann den Fehler lösen, wenn es sich um ein vorübergehendes Problem handelt, oder es für Ihr Betriebsteam auslösen, um manuell zu beheben. Ändern Sie dazu den Code partial_func, damit er wie folgt aussieht:

def partial_func(batch_df, batch_id):
  try:
    batch_df.foreach(foreach_func)
  except Exception as e:
    print(e) # or whatever error handling you want to have
    raise e # re-raise the issue

Wenn Sie die Ausnahme abfangen und den Rest des Batches ignorieren möchten, können Sie den Code so ändern, dass die do_nothing Funktion verwendet wird, um den Rest des Batches im Hintergrund zu ignorieren.

from pyspark.sql.functions import expr

stream = spark.readStream.format("rate").option("rowsPerSecond", "100").load()
# creates a stateful operator:
streamWithWatermark = stream.withWatermark("timestamp", "15 minutes").dropDuplicatesWithinWatermark()

def foreach_func(row):
  # handle the row, but in this case, for the sample, will just raise an error:
  raise Exception('error')

# function to do nothing with a row
def do_nothing(row):
    pass

def partial_func(batch_df, batch_id):
  try:
    batch_df.foreach(foreach_func)
  except Exception as e:
    print(e) # or whatever error handling you want to have
    batch_df.foreach(do_nothing) # silently consume the remainder of the batch

q = streamWithWatermark.writeStream \
  .foreachBatch(partial_func) \
  .option("checkpointLocation", checkpoint_dir) \
  .trigger(processingTime='2 seconds') \
  .start()

Schreibe fehlgeschlagene Datensätze in eine Dead-Letter Queue

Standardmäßig schlagen Abfragen sofort fehl, wenn fehlerhafte Datensätze eingehen. Vermeiden Sie diese Unterbrechungen, indem Sie eine sekundäre Delta Lake-Tabelle als Dead-Letter-Queue (DLQ) konfigurieren.

Mit einer DLQ leitet das System fehlgeschlagene Datensätze an die sekundäre Tabelle weiter und verarbeitet gültige Daten ohne Unterbrechung. Mit der DLQ-Tabelle können Sie die fehlerhaften Datensätze später untersuchen und erneut verarbeiten.

Verwenden Sie diese Methode, wenn:

  • Ihr Datenstrom enthält unterschiedliche Daten, die möglicherweise gegen Schemaeinschränkungen oder Geschäftsregeln verstoßen.
  • Überwachungs- oder Complianceregeln erfordern, dass Sie alle Datensätze beibehalten.

Example

Im folgenden Beispiel wird foreachBatch verwendet, um jeden Micro-Batch in gültige und ungültige Datensätze aufzuteilen; anschließend wird jede Teilmenge in ihre eigene Delta-Lake-Tabelle geschrieben.

Note

Dieses ausführbare Beispiel erstellt Tabellen in einem dedizierten main.streaming_examples Schema, sodass es ausgeführt werden kann, ohne deine bestehenden Daten zu beeinflussen. Wenn du keine Berechtigung hast, Schemata im main Katalog zu erstellen, ändere den Katalog und das Schema an einen Ort, an dem du Tabellen erstellen kannst. Das Beispiel droppt und erstellt seine Tabellen jedes Mal neu, wenn es ausgeführt wird, also verwende ein Schema, das keine anderen Tabellen mit denselben Namen enthält.

Python

from pyspark.sql.functions import current_timestamp, lit
import uuid

source_table = "main.streaming_examples.raw_orders"
main_table = "main.streaming_examples.orders"
dlq_table = "main.streaming_examples.orders_dlq"

# A new checkpoint restarts batch IDs at 0, so it needs its own txnAppId.
# Otherwise Delta treats the batches as duplicates and skips them.
run_id = uuid.uuid4()
checkpoint_path = f"/tmp/checkpoint_dlq_{run_id}"
app_id = f"orders-streaming-job-{run_id}"

# Create a dedicated schema for the example tables
spark.sql("CREATE SCHEMA IF NOT EXISTS main.streaming_examples")

# Seed the source with a mix of valid and invalid orders
spark.sql(f"DROP TABLE IF EXISTS {main_table}")
spark.sql(f"DROP TABLE IF EXISTS {dlq_table}")
spark.sql(f"DROP TABLE IF EXISTS {source_table}")
spark.createDataFrame(
    [
        ("ord1", 100, "cust1"),  # valid
        ("ord2", -50, "cust2"),  # invalid: non-positive amount
        ("ord3", 200, None),     # invalid: missing customer_id
        ("ord4", 300, "cust4"),  # valid
    ],
    "order_id string, order_amount int, customer_id string",
).write.saveAsTable(source_table)

def process_orders(batch_df, batch_id):
    if batch_df.isEmpty():
        return

    valid_condition = "order_amount > 0 AND customer_id IS NOT NULL"

    # Write valid records to the main table with idempotency options
    batch_df.filter(valid_condition).write \
        .format("delta") \
        .mode("append") \
        .option("txnVersion", batch_id) \
        .option("txnAppId", app_id) \
        .saveAsTable(main_table)

    # Route invalid records to the dead-letter queue
    invalid_df = batch_df.filter(f"NOT ({valid_condition})")
    if not invalid_df.isEmpty():
        invalid_df \
            .withColumn("dlq_batch_id", lit(batch_id)) \
            .withColumn("dlq_ingest_time", current_timestamp()) \
            .write \
            .format("delta") \
            .mode("append") \
            .option("txnVersion", batch_id) \
            .option("txnAppId", app_id) \
            .saveAsTable(dlq_table)

q = spark.readStream \
    .format("delta") \
    .table(source_table) \
    .writeStream \
    .foreachBatch(process_orders) \
    .option("checkpointLocation", checkpoint_path) \
    .trigger(availableNow=True) \
    .start()

q.awaitTermination()

# Valid orders (ord1, ord4) land in the main table; invalid orders (ord2, ord3) route to the DLQ
display(spark.sql(f"SELECT * FROM {main_table} ORDER BY order_id"))
display(spark.sql(f"SELECT order_id, dlq_batch_id FROM {dlq_table} ORDER BY order_id"))

Scala

import org.apache.spark.sql.DataFrame
import org.apache.spark.sql.functions.{current_timestamp, lit}
import org.apache.spark.sql.streaming.Trigger
import spark.implicits._
import java.util.UUID

val sourceTable = "main.streaming_examples.raw_orders"
val mainTable = "main.streaming_examples.orders"
val dlqTable = "main.streaming_examples.orders_dlq"

// A new checkpoint restarts batch IDs at 0, so it needs its own txnAppId.
// Otherwise Delta treats the batches as duplicates and skips them.
val runId = UUID.randomUUID()
val checkpointPath = s"/tmp/checkpoint_dlq_$runId"
val appId = s"orders-streaming-job-$runId"

// Create a dedicated schema for the example tables
spark.sql("CREATE SCHEMA IF NOT EXISTS main.streaming_examples")

// Seed the source with a mix of valid and invalid orders
spark.sql(s"DROP TABLE IF EXISTS $mainTable")
spark.sql(s"DROP TABLE IF EXISTS $dlqTable")
spark.sql(s"DROP TABLE IF EXISTS $sourceTable")
Seq(
  ("ord1", 100, "cust1"),                    // valid
  ("ord2", -50, "cust2"),                    // invalid: non-positive amount
  ("ord3", 200, null.asInstanceOf[String]),  // invalid: missing customer_id
  ("ord4", 300, "cust4")                     // valid
).toDF("order_id", "order_amount", "customer_id").write.saveAsTable(sourceTable)

def processOrders(batchDf: DataFrame, batchId: Long): Unit = {
  if (batchDf.isEmpty) return

  val validCondition = "order_amount > 0 AND customer_id IS NOT NULL"

  // Write valid records to the main table with idempotency options
  batchDf.filter(validCondition).write
    .format("delta")
    .mode("append")
    .option("txnVersion", batchId)
    .option("txnAppId", appId)
    .saveAsTable(mainTable)

  // Route invalid records to the dead-letter queue
  val invalidDf = batchDf.filter(s"NOT ($validCondition)")
  if (!invalidDf.isEmpty) {
    invalidDf
      .withColumn("dlq_batch_id", lit(batchId))
      .withColumn("dlq_ingest_time", current_timestamp())
      .write
      .format("delta")
      .mode("append")
      .option("txnVersion", batchId)
      .option("txnAppId", appId)
      .saveAsTable(dlqTable)
  }
}

val q = spark.readStream
  .format("delta")
  .table(sourceTable)
  .writeStream
  .foreachBatch(processOrders _)
  .option("checkpointLocation", checkpointPath)
  .trigger(Trigger.AvailableNow())
  .start()

q.awaitTermination()

// Valid orders (ord1, ord4) land in the main table; invalid orders (ord2, ord3) route to the DLQ
spark.sql(s"SELECT * FROM $mainTable ORDER BY order_id").show()
spark.sql(s"SELECT order_id, dlq_batch_id FROM $dlqTable ORDER BY order_id").show()

Beide Schreibvorgänge verwenden txnVersion und txnAppId, um Idempotenz zu garantieren. Wenn Spark einen Batch mit derselben batchId erneut abspielt, überspringt Delta Lake den doppelten Schreibvorgang. Da jeder Durchlauf des Beispiels einen neuen Checkpoint startet, leitet txnAppId er sich ebenfalls aus derselben Lauf-ID ab. Ändere txnAppId in deinen eigenen Streams, sobald du einen neuen Checkpoint startest. Siehe Verwendung von foreachBatch für idempotente Tabellenschreibvorgänge.