使用 depends_on 排定管線流程的執行順序

Important

這項功能目前處於 公開預覽版。

使用 depends_on時,設定你的管線使用預覽通道。 詳見channel管線配置。

依預設,管線會根據資料相依性來排定各流程的執行順序:如果某個流程會讀取另一個流程寫入的資料表,則讀取該資料表的流程會在寫入該資料表的流程之後執行。 流程排序可讓一個流程等待另一個未從中讀取資料的流程,方法是使用 depends_on 明確宣告相依性。

depends_on="other_flow" 這表示這個流程只有在成功完成後 other_flow 才會開始。 它是一種排程優勢:它控制流程 何時 開始,而非 如何 運行。 宣告 depends_on 不會改變流程的觸發條件、模式,或是否為一次性流程。 你仍然直接在流程本身中宣告這些,例如 once=True。

何時使用流程排序

主要的使用情境是在切換到即時來源前先抽乾歷史資料,同時保留串流狀態,例如將資料表從批次回填遷移到即時 Apache Kafka 來源。

同時讀取兩個來源效果不佳:有界回填會阻擋浮水印,延遲州政府淘汰和視窗結果。 先排乾回填土,再開始直播,可以避免這種情況。 流程排序將兩者排序。

流量排序也支援其他模式:

  • 嚴格地將多個回填材料放入同一張表格。
  • 分階段的管線,例如初始負載、追趕、再即時傳輸。
  • 序列流程會寫入 不同的 資料表,但必須以固定順序執行。

使用 depends_on 排序流程

depends_on 可用於 Python pipelines API 中的 @dp.append_flow 和 @dp.update_flow 裝飾器。 它接受單一流程名稱或多個流程名稱清單。 使用清單時,每個命名流程必須在依賴流程開始前完成。

以下範例會先將一次性回填排入 events 串流表,然後在回填完成後才開始在同一表中進行即時 Kafka 串流:

from pyspark import pipelines as dp

dp.create_streaming_table(name="events")

# Drain the historical backfill first.
@dp.append_flow(target="events", once=True, name="events_backfill")
def events_backfill():
    return spark.read.table("historical_events")

# Start the live stream only after the backfill completes.
@dp.append_flow(target="events", name="events_live", depends_on="events_backfill")
def events_live():
    return (
        spark.readStream.format("kafka")
        .option("kafka.bootstrap.servers", "<server>:<port>")
        .option("subscribe", "events")
        .load()
    )

要等待多位前任,請傳閱一份名單。 以下範例會並行執行兩個回填作業,並僅在兩者皆完成後才啟動即時串流:

@dp.append_flow(target="events", once=True, name="backfill_2024")
def backfill_2024():
    return spark.read.table("events_2024")

@dp.append_flow(target="events", once=True, name="backfill_2025")
def backfill_2025():
    return spark.read.table("events_2025")

@dp.append_flow(
    target="events",
    name="events_live",
    depends_on=["backfill_2024", "backfill_2025"],
)
def events_live():
    return spark.readStream.format("kafka").option("subscribe", "events").load()

若要讓回補作業依序逐一執行,而非平行執行,請使用 depends_on 將它們串接起來:

@dp.append_flow(target="events", once=True, name="backfill_2024")
def backfill_2024():
    return spark.read.table("events_2024")

@dp.append_flow(
    target="events", once=True, name="backfill_2025", depends_on="backfill_2024"
)
def backfill_2025():
    return spark.read.table("events_2025")

foreachBatch 流程排序

在以 foreachBatch 接收端為目標的附加流程上使用 depends_on,不要在 @dp.foreach_batch_sink 裝飾器上使用。 一個 foreachBatch 流程不能是一次性(once)流程。 關於資料接收端行為與重試考量,請參見 使用 ForEachBatch 寫入管線中的任意資料接收端。

已觸發的管線中的 Sequence foreachBatch 流程

在觸發管線中,流程 foreachBatch 既可以是前驅,也可以是後繼。 以下範例會回填串流資料表,將其列匯出至 foreachBatch 接收端,然後再透過第二個 foreachBatch 接收端處理相同的列。

兩個接收端流量都顯示為 ordered_events。 depends_on="export_events"相依性會使稽核流程在匯出流程之後執行,即使稽核流程並未讀取匯出表。 將 <schema> 和 <catalog> 替換為你的來源和目的地資料表的目錄和結構。

from pyspark import pipelines as dp

dp.create_streaming_table(name="ordered_events")


@dp.append_flow(target="ordered_events", once=True, name="events_backfill")
def events_backfill():
    return spark.read.table("<catalog>.<schema>.historical_events")


@dp.foreach_batch_sink(name="events_export_sink")
def export_batch(batch_df, batch_id):
    batch_df.write.format("delta").mode("append").saveAsTable(
        "<catalog>.<schema>.exported_events"
    )


@dp.append_flow(
    target="events_export_sink", name="export_events", depends_on="events_backfill"
)
def export_events():
    return spark.readStream.table("ordered_events")


@dp.foreach_batch_sink(name="events_audit_sink")
def audit_batch(batch_df, batch_id):
    batch_df.write.format("delta").mode("append").saveAsTable(
        "<catalog>.<schema>.audited_events"
    )


@dp.append_flow(
    target="events_audit_sink", name="audit_events", depends_on="export_events"
)
def audit_events():
    return spark.readStream.table("ordered_events")

在連續管線中完成回填後執行 foreachBatch 流程

在連續管線中,foreachBatch流程可以是後繼,但不能是前驅。 其前置流程必須是一次性(once)流程。 以下範例是在回填完成後,將回填的行處理進 foreachBatch sink:

from pyspark import pipelines as dp

dp.create_streaming_table(name="backfilled_events")


@dp.append_flow(target="backfilled_events", once=True, name="events_backfill")
def events_backfill():
    return spark.read.table("<catalog>.<schema>.historical_events")


@dp.foreach_batch_sink(name="events_export_sink")
def export_batch(batch_df, batch_id):
    batch_df.write.format("delta").mode("append").saveAsTable(
        "<catalog>.<schema>.continuous_exported_events"
    )


@dp.append_flow(
    target="events_export_sink", name="export_events", depends_on="events_backfill"
)
def export_events():
    return spark.readStream.table("backfilled_events")

不要在這個連續範例中加入另一個流程 depends_on="export_events"。 輸出流程不是一次性的流程,因此管線會拒絕將其作為前驅流程 DEPENDS_ON_PREDECESSOR_MUST_BE_ONCE。

需求與行為

以下規則適用於流程排序:

  • 流程的順序僅適用於管線內。 沒有管線排程器,訂單無法被遵守。
  • 前置程式必須寫入資料表或匯表,而非檢視。 寫入檢視的流程永遠不會達到終端狀態,因此在它之後排序的流程永遠不會開始。 串流表目標是有效的前置項目。 foreachBatch接收流程可以是觸發管線的前驅,但不可能是連續管線中的前驅。
  • 允許跨目的地訂購。 一個流程可以相依於將資料寫入另一個資料表的流程。
  • 未知的流程名稱與循環會在驗證階段被偵測到,並在管線執行前發現。

在觸發式與持續管線中,可作為前置項目的有哪些

可作為前置流程的流程類型取決於管線的執行模式:

  • 觸發管線: 任何流程都可能是前導。 每個觸發執行中的流程都會達到最終狀態,因此該排序會在每次執行內套用。
  • 連續管線: 前驅必須是once一次性()流,達到終端狀態。 持續運行的流程永遠不會終止,因此在它之後排序的流程永遠不會開始,且管線會在驗證時拒絕該流程。

由於 foreachBatch 流程一律是串流接收端,無法作為一次性流程,因此只能在觸發式管線中作為前驅。 在連續管線中,foreachBatch 流程可以等待 once 前置流程,但其本身不能作為前置流程。

操作行為

once 前置項的完成狀態會持久保留,因此在重新啟動和管線更新後仍會保留:

  • 重新啟動: 已排空的流程會維持排空狀態,並予以略過。 管線會在尚未完成的第一筆水流時恢復。 執行進入即時流程後,之後重新啟動只會恢復即時流程。
  • 完全刷新: 清除該鏈的完成狀態,並依序從頭重新執行。
  • 單一流程的檢查點重設:重設即時流程時,只會重新播放即時流程。 上游 once 回填作業會維持排空狀態,且不會重新執行。 這是通常在不重新抽取歷史的情況下恢復即時查詢的方法。

其他資源