Распространённые структурированные потоковые паттерны

Spark Structured Streaming поддерживает несколько способов маршрутизации одного логического потока к нескольким целям, корреляции потоков и наблюдения за прогрессом запросов. В этой статье показаны распространённые шаблоны для Microsoft Fabric, включая разветвление с foreachBatch, независимые потоковые запросы, соединения между потоками, отказоустойчивые таблицы Delta и StreamingQueryListener.

Примеры предполагают, что events — это потоковый DataFrame со столбцами order_id, amount и event_time.

Important

start() и toTable() асинхронно запускают потоковый запрос и возвращают дескриптор StreamingQuery. Активный запрос не мешает триггерному блокноту или определению задания Spark перейти в терминальное состояние. Вызывайте query.awaitTermination() для каждого запроса, завершения которого должна дождаться запущенная задача. Для нескольких постоянно выполняющихся запросов spark.streams.awaitAnyTermination() блокируется до тех пор, пока один из запросов не завершится, чтобы задача могла обработать это завершение.

Выберите шаблон разветвления

Выбирайте схему, исходя из требований к изоляции, задержке и долговечности каждого пункта назначения.

Рисунок Используйте, если Компромиссы
Один запрос с foreachBatch Целевые системы используют модули пакетной записи и должны совместно обрабатывать один и тот же микропакет. Целевые объекты используют общий жизненный цикл запроса, а их операции записи не выполняются атомарно как единое целое.
Независимые потоковые запросы Пунктам назначения нужны отдельные трансформации, контрольные точки или поведение при перезапуске. Каждый запрос самостоятельно читает и обрабатывает исходный код.
Однократно загружайте данные в таблицу Delta уровня Bronze Нисходящим потокам требуется надёжное повторное воспроизведение, отдельные расписания или отдельные домены отказа. Дополнительная запись в Delta увеличивает объём хранилища и задержку.

Не используйте одну и ту же контрольную точку между разветвлёнными запросами. Каждому запросу для стриминга нужна выделенная точка контроля.

Запись в несколько приемников с помощью foreachBatch

foreachBatch передаёт каждый микропакетный DataFrame и его batch ID в функцию. Используйте эту функцию для применения средств пакетной записи DataFrame, операций MERGE или записи в несколько мест назначения.

foreachBatch по умолчанию обеспечивает обработку как минимум один раз. Следующий пример кэширует микропакет, чтобы Spark не пересчитывал его для каждого приемника. Идентификаторы транзакций Delta делают каждую операцию записи в таблицу идемпотентной, когда Spark повторно обрабатывает тот же пакет.

def append_idempotently(batch_df, table_name, transaction_id, batch_id):
    (
        batch_df.write
        .format("delta")
        .mode("append")
        .option("txnAppId", transaction_id)
        .option("txnVersion", batch_id)
        .saveAsTable(table_name)
    )


def write_to_sinks(batch_df, batch_id):
    cached_batch = batch_df.persist()
    try:
        append_idempotently(
            cached_batch,
            "bronze_orders",
            "orders-fanout-bronze",
            batch_id,
        )
        append_idempotently(
            cached_batch.filter("amount >= 1000"),
            "high_value_orders",
            "orders-fanout-high-value",
            batch_id,
        )
    finally:
        cached_batch.unpersist()


query = (
    events.writeStream
    .queryName("orders-fanout")
    .outputMode("append")
    .option("checkpointLocation", "Files/checkpoints/orders-fanout")
    .foreachBatch(write_to_sinks)
    .start()
)

query.awaitTermination()

Держите каждый идентификатор транзакции стабильным, пока повторно используете контрольную точку. Если вы запускаете запрос с новой контрольной точкой и идентификаторы его пакетов начинаются заново, используйте новые идентификаторы транзакций, чтобы Delta не считала новые пакеты транзакциями, которые она уже зафиксировала.

Записи внутри foreachBatch — это не одна транзакция между всеми пунктами назначения. Если поздняя запись не удаётся, Спарк повторяет партию. Сделайте каждый конечный пункт идемпотентным, чтобы успешно выполненные ранее операции записи можно было безопасно повторить. Для целевых систем, не использующих Delta, используйте стабильный ключ события, операцию вставки или обновления (upsert) либо идентификатор транзакции, специфичный для целевой системы.

foreachBatch использует модель микропакетного исполнения. Не используйте его в режиме реального времени.

Запускайте независимые потоковые запросы

Запускайте отдельный запрос, когда каждому назначению нужна своя контрольная точка, триггер, выходной режим или обработка сбоев. Запросы могут использовать одинаковое определение потокового DataFrame, но Spark выполняет каждый запрос независимо.

bronze_query = (
    events.writeStream
    .queryName("orders-bronze")
    .format("delta")
    .outputMode("append")
    .option("checkpointLocation", "Files/checkpoints/orders-bronze")
    .toTable("bronze_orders")
)

high_value_query = (
    events.filter("amount >= 1000")
    .writeStream
    .queryName("orders-high-value")
    .format("delta")
    .outputMode("append")
    .option("checkpointLocation", "Files/checkpoints/orders-high-value")
    .toTable("high_value_orders")
)

spark.streams.awaitAnyTermination()

Используйте независимые запросы для небольшого числа получателей, когда приемлемо повторное чтение исходного кода и повторные преобразования. Отслеживайте и перезапускайте каждый запрос отдельно.

awaitAnyTermination() возвращается, когда любой запрос останавливается. Проверьте статус запроса и исключение, затем остановите или перезапустите оставшийся запрос вместо того, чтобы позволить ему выполняться без надзора. Для нескольких ограниченных запросов типа available-now сначала запустите все запросы, затем вызовите awaitTermination() для каждого дескриптора запроса, чтобы задание ожидало завершения всех запросов.

Для более крупных топологий с большим числом ответвлений однократно загружайте исходные данные в бронзовую таблицу Delta. Начните следующие потоки из этой таблицы с отдельными контрольными точками. Эта схема обеспечивает каждому потребителю надёжную возможность повторного воспроизведения и не позволяет медленному пункту назначения блокировать приём данных. Стандартные операции потокового чтения Delta предполагают коммиты только с добавлением данных; используйте ленту изменений данных (Change Data Feed), если потребляющие потоки должны получать обновления или удаления.

Соедините два потока с ограниченным состоянием

Соединение двух потоков данных сопоставляет события, которые поступают независимо друг от друга, например заказ и его оплату. Оба входа могут продолжать получать поздние данные, поэтому добавьте водяные знаки и условие временного диапазона, чтобы дать Spark точку, в которой он может убрать состояние несоответствия.

В следующем примере предполагается, что orders содержит order_id и order_time, а payments содержит order_id, payment_id и payment_time.

from pyspark.sql import functions as F

watermarked_orders = (
    orders
    .withWatermark("order_time", "10 minutes")
    .alias("orders")
)

watermarked_payments = (
    payments
    .withWatermark("payment_time", "10 minutes")
    .alias("payments")
)

matched_orders = (
    watermarked_orders.join(
        watermarked_payments,
        F.expr("""
            orders.order_id = payments.order_id
            AND payments.payment_time >= orders.order_time
            AND payments.payment_time
                <= orders.order_time + INTERVAL 30 MINUTES
        """),
        "inner",
    )
    .select(
        F.col("orders.order_id").alias("order_id"),
        F.col("orders.order_time"),
        F.col("payments.payment_id"),
        F.col("payments.payment_time"),
    )
)

query = (
    matched_orders.writeStream
    .format("delta")
    .outputMode("append")
    .option("checkpointLocation", "Files/checkpoints/matched-orders")
    .toTable("matched_orders")
)

query.awaitTermination()

Объединения потоков поддерживают режим вывода append. Внутренние соединения могут выполняться без водяных меток, но их состояние может расти без ограничений. Внешние соединения предъявляют дополнительные требования к watermark-меткам и откладывают вывод строк без совпадений до тех пор, пока Spark не сможет доказать, что соответствующее совпадение уже не поступит. Для подробностей см. раздел Stream-stream joins.

Режим реального времени поддерживает только определённые варианты соединения между потоками и требует дополнительной настройки. Проверьте матрицу поддержки режима реального времени, прежде чем менять этот паттерн на триггер режима реального времени.

Наблюдайте запросы с помощью StreamingQueryListener

StreamingQueryListener получает события жизненного цикла и прогресса для каждого потокового запроса в сеансе Spark. Используйте его для отправки метрик запросов и деталей завершения в вашу систему логирования или мониторинга.

import json

from pyspark.sql.streaming import StreamingQueryListener


class QueryMetricsListener(StreamingQueryListener):
    def onQueryStarted(self, event):
        print(json.dumps({
            "event": "started",
            "id": str(event.id),
            "runId": str(event.runId),
            "name": event.name,
        }))

    def onQueryProgress(self, event):
        progress = event.progress
        print(json.dumps({
            "event": "progress",
            "name": progress.name,
            "batchId": progress.batchId,
            "numInputRows": progress.numInputRows,
            "inputRowsPerSecond": progress.inputRowsPerSecond,
            "processedRowsPerSecond": progress.processedRowsPerSecond,
        }, default=str))

    def onQueryIdle(self, event):
        pass

    def onQueryTerminated(self, event):
        print(json.dumps({
            "event": "terminated",
            "id": str(event.id),
            "runId": str(event.runId),
            "exception": event.exception,
        }))


query_listener = QueryMetricsListener()
spark.streams.addListener(query_listener)

Обратные вызовы прослушивателя выполняются в драйвере и могут вызываться из разных потоков. Оставьте onQueryStarted неблокирующим, потому что запуск запроса ожидает его. Оставляйте остальные функции обратного вызова короткими, защищайте общее изменяемое состояние и помещайте данные телеметрии в очередь для асинхронной отправки вместо выполнения медленных сетевых вызовов в функции обратного вызова.

События прогресса появляются, когда Spark публикует прогресс запросов. В режиме реального времени это происходит на границе между длительно выполняющимися пакетами, а не для каждой записи. Используйте мониторинг отставания источника и задержки на нижестоящих этапах между событиями хода выполнения. Для подробностей см. Мониторинг запросов в реальном времени.

В интерактивном блокноте удалите слушателя перед регистрацией замены, чтобы повторный запуск ячейки не создавал дублирующихся обратных вызовов:

spark.streams.removeListener(query_listener)