Ordonner l’exécution du pipeline avec depends_on

Important

Cette fonctionnalité est disponible en préversion publique.

Pour utiliser depends_on, configurez votre pipeline pour utiliser le canal PREVIEW. Consultez channel les configurations de pipeline.

Par défaut, un pipeline planifie les flux selon leurs dépendances de données : si un flux lit la table qu’un autre flux écrit, le lecteur court après l’auteur. L’ordre des flux permet à un flux d’attendre un autre flux dont il ne lit pas , en déclarant explicitement la dépendance avec depends_on.

depends_on="other_flow" signifie que ce flux ne démarre qu’après que other_flow se soit terminé avec succès. C’est un avantage de planification : il contrôle quand un flux commence, pas comment il s’exécute. Déclarer depends_on ne change pas le déclencheur, le mode ou le fait qu’il s’agisse d’un flux à usage unique. Vous déclarez toujours ces éléments sur le flux lui-même, par exemple avec once=True.

Quand utiliser l’ordre des flux

Le cas d’usage principal consiste à purger les données historiques avant de basculer vers une source en temps réel tout en préservant l’état du streaming, par exemple lors de la migration d’une table d’un rechargement historique par lots vers une source Apache Kafka en temps réel.

Lire les deux sources en même temps ne fonctionne pas bien : le renvoi borné retient le filigrane, ce qui retarde l’expulsion de l’État et les résultats fenêtrés. Vider d’abord le renvoi, puis lancer le live stream, évite cela. L’ordonnancement des flux séquence les deux.

L’ordre des flux prend également en charge d’autres motifs :

  • Ordonner strictement plusieurs backfills dans la même table.
  • Pipelines par phases, comme une charge initiale, puis un rattrapage, puis un flux en direct.
  • Les flux de séquençage qui écrivent sur différentes tables mais doivent s’exécuter dans un ordre défini.

Ordonnancement des flux avec depends_on

depends_on est disponible pour les décorateurs @dp.append_flow et @dp.update_flow dans l’API des pipelines Python. Il accepte un seul nom de flux ou une liste de noms de flux uniques. Avec une liste, chaque flux nommé doit être complété avant que le flux dépendant ne commence.

L’exemple suivant injecte un backfill ponctuel dans la table de streaming events, puis démarre un flux Kafka en temps réel dans la même table seulement une fois le backfill terminé :

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()
    )

Pour attendre plusieurs prédécesseurs, fournissez une liste. L’exemple suivant exécute deux backfills en parallèle et ne lance le flux en direct qu’une fois les deux terminés :

@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()

Pour exécuter les backfills les uns après les autres plutôt qu’en parallèle, chaînez depends_on entre eux :

@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")

Ordonner les flux foreachBatch

Utilisez depends_on sur le flux d’ajout qui cible un foreachBatch récepteur pas sur l’élément décoratif @dp.foreach_batch_sink. Un flux foreachBatch ne peut pas être un flux à usage unique (once). Pour le comportement des puits et les considérations de réessayage, voir Utiliser ForEachBatch pour écrire sur des puits de données arbitraires dans les pipelines.

Séquence de flux foreachBatch dans un pipeline déclenché

Dans un pipeline déclenché, un foreachBatch flux peut être à la fois un prédécesseur et un successeur. L’exemple suivant remplit une table de diffusion, exporte ses lignes via un récepteur foreachBatch, puis traite les mêmes lignes via un second récepteur foreachBatch.

Les deux flux récepteurs indiquent ordered_events. La depends_on="export_events" dépendance séquence le flux d’audit après le flux d’exportation, même si le flux d’audit ne lit pas la table d’exportation. Remplacez <catalog> et <schema> par le catalogue et le schéma pour vos tables source et destination.

import dlt
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 dlt.read_stream("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 dlt.read_stream("ordered_events")

Exécutez un flux foreachBatch après un backfill dans un pipeline continu

Dans un pipeline continu, un foreachBatch flux peut être un successeur, mais pas un prédécesseur. Son prédécesseur doit être un flux à usage unique (once). L’exemple suivant traite les lignes backfillées via un foreachBatch sink après la fin du backfill :

import dlt
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 dlt.read_stream("backfilled_events")

N’ajoutez pas un autre flux avec depends_on="export_events" à cet exemple continu. Le flux d’exportation n’est pas un flux à exécution unique, donc le pipeline le rejette comme prédécesseur avec DEPENDS_ON_PREDECESSOR_MUST_BE_ONCE.

Exigences et comportement

Les règles suivantes s’appliquent à l’ordre des flux :

  • L’ordre des flux ne fonctionne qu’à l’intérieur d’un pipeline. Sans le planificateur de pipeline, la commande ne peut pas être respectée.
  • Un prédécesseur doit écrire dans une table ou un récepteur, pas dans une vue. Un flux qui écrit dans une vue n’atteint jamais un état terminal, donc un flux ordonné après celui-ci ne commencerait jamais. Les cibles de tables de diffusion sont des prédécesseurs valides. Un flux récepteur foreachBatch peut être un prédécesseur dans un pipeline déclenché, mais pas dans un pipeline continu.
  • L’ordre entre destinations est autorisé. Un flux peut dépendre d’un flux qui écrit dans une autre table.
  • Les noms et cycles de flux inconnus sont détectés lors de la validation, avant que le pipeline ne démarre.

Quels éléments peuvent servir de prédécesseur dans les pipelines déclenchés et en continu

Les types de flux pouvant agir comme prédécesseurs dépendent du mode d’exécution du pipeline :

  • Pipelines déclenchés : n’importe quel flux peut être un prédécesseur. Chaque flux dans une exécution déclenchée atteint un état terminal, donc l’ordre s’applique à chaque exécution.
  • Pipelines continus : un prédécesseur doit être un flux à usage unique (once) qui atteint un état terminal. Un flux qui fonctionne en continu ne se termine jamais, donc un flux ordonné après celui-ci ne commencerait jamais, et le pipeline le rejette lors de la validation.

Comme un foreachBatch flux est toujours un puits de streaming et ne peut pas être un flux ponctuel, il ne peut servir de prédécesseur que dans un pipeline déclenché. Dans un pipeline continu, un flux foreachBatch peut dépendre d’un prédécesseur once, mais il ne peut pas lui-même être un prédécesseur.

Comportement opérationnel

L’état d’achèvement du prédécesseur once est persistant ; il survit donc aux redémarrages et aux mises à jour du pipeline :

  • Redémarrage : les flux déjà drainés le restent et sont ignorés. Le pipeline reprend au premier flux qui n’est pas encore terminé. Après que l’exécution atteigne le flux en direct, les redémarrages ultérieurs ne reprennent que le flux en direct.
  • Rafraîchissement complet : efface l’état de complétion de la chaîne et le réexécute depuis le début, dans l’ordre.
  • Réinitialisation du point de contrôle pour un seul flux : la réinitialisation du flux actif rejoue uniquement le flux actif. Les remblais en amont once restent vidés et ne sont pas relancés. C’est la manière habituelle de récupérer une requête en temps réel sans re-drainer l’historique.

Ressources additionnelles