How to use Lakeflow pipelines
このページでは、データパイプラインのライフサイクル全体を通じた Lakeflow パイプラインの使用方法について、最初の設計上の決定から大規模な実行まで、および各段階におけるトレードオフを説明します。各セクションには、その方法を説明する記事へのLinkがあります。
This guide assumes familiarity with core data engineering concepts. If you are new to pipelines, start with Apache Spark Declarative Pipelines for what the product is and the declarative model behind it, then work through the Tutorial: Build an ETL pipeline using change data capture.
パイプラインのライフサイクルの概要
A pipeline moves through six stages:
- Plan and design: Decide what you are building and choose the tools, language, and compute that fit.
- Ingest data: Bring source data into the pipeline reliably and incrementally.
- 変換とモデリング: データをクリーニング、検証、結合、整形し、消費者が信頼できるテーブルを作成します。
- Operationalize: Put the pipeline under version control, test it, schedule it, and promote it across environments.
- Run in production: Monitor, alert, debug, backfill, secure, and track lineage as the pipeline runs unattended.
- Mature and scale: Confirm production readiness and keep the pipeline healthy as volume and team size grow.
各ステージは厳密に逐次的ではありませんが、質問が発生する順序に対応しています。LakeFlow Pipelines はオーケストレーション、チェックポイント、再試行、インクリメンタル処理を処理するため、各ステージでの作業は実装というよりも設計上の決定が主となります。
計画と設計
最初の決定が、下流のすべてを形作ります。宣言型モデルと、手続き型ステップを自分で記述する場合の比較については、「Databricks における手続き型データ処理と宣言型データ処理」を参照してください。
A few choices set your starting configuration:
- A standalone dataset or a pipeline. A single materialized view or streaming table can be defined in SQL as a standalone dataset, and Databricks manages the refresh pipeline behind it. Author and operate a Lakeflow pipeline as a unit when you need Python authoring, sinks, or multi-stage orchestration. See Standalone pipelines vs. Lakeflow pipelines.
- SQL または Python (あるいはその両方)。 SQL は、主にフィルター、結合、集計を行う変換に適しています。Python は、カスタムロジック、外部ライブラリ、またはプログラムによる多数の類似テーブルの生成に適しています。この選択はパイプライン全体ではなくファイルごとに行うため、両方を混在させることができ、事前に決定する必要はありません。
- Serverless or classic compute. Serverless is the recommended default and removes cluster configuration. Choose classic when you need specific instance types, custom cluster policies, or an init script. See Configure a serverless pipeline and Configure classic compute for pipelines.
- Triggered or continuous execution. Start triggered, since it only consumes compute while it runs. Continuous mode keeps compute running to process new data with minimal delay, which is usually the largest cost factor, so reserve it for a proven latency requirement. See Triggered vs. continuous pipeline mode.
A pipeline infers its execution graph from the datasets your code references, so design work is largely naming and sequencing datasets. The core decision is which type each output should be: a Streaming tables for append-heavy incremental data, or a Materialized views for recomputed aggregates and joins. That choice drives cost and correctness, because incremental processing scales with the rate of new data while a full recompute scales with your entire history. For which type fits which job, see What are pipelines?.
Because pipeline code is ordinary Python and SQL, you can write, lint, and validate it in your own editor before deploying to a shared workspace.
In this stage
このステージで考慮すべき質問：
- How do I choose between a standalone dataset and a full pipeline?
- How do I identify my data sources and figure out how to connect to them?
- コードを書く前にパイプラインのアーキテクチャをどう設計すればいいですか?
- How do I choose a file format and storage layer?
- How do I set up a local development environment?
- How do I plan for scale and estimate cost before I start building?
データを取り込む
中心となる設計上の問いは、ソースが追記専用か、それともインプレースで変更されるかという点です。それがターゲットのモデル化方法を決定します：
- Append-only sources , such as files landing in cloud storage or events on a message bus, ingest into a streaming table, which checkpoints its progress so a restart neither reprocesses nor drops data. Auto Loader handles files, discovering new ones and inferring and evolving schema as they arrive. Message buses such as Apache Kafka, Azure Event Hubs, Amazon Kinesis, and Google Pub/Sub read directly into a streaming table. Deduplicate downstream, since a bus can deliver the same event more than once. For Azure Event Hubs specifically, see Use Azure Event Hubs as a pipeline data source.
- Sources that update and delete rows , such as most databases and many software as a service (SaaS) systems, use change data capture (CDC). A full copy on every run is wasteful and grows slower as the source grows, so CDC reads only the rows that changed since the last run. The
AUTO CDCAPI applies those changes without hand-written merge logic; see The AUTO CDC APIs: Simplify change data capture with pipelines. A flow applies CDC into a streaming table, and several flows can feed one table, which is how you fan multiple sources into a single target.
Checkpointing and retries are automatic, so a pipeline resumes from the last processed offset rather than reprocessing everything. Two safeguards are opt-in:
- A rescued-data column captures records that don't match the expected schema.
- Expectations apply the row-level action you define.
ストリーミングのチェックポイントが無効になった場合は、テーブルデータを保持する最も低コストな復旧方法を優先してください。
In this stage
このステージで考慮すべき質問：
- データベースからデータを取り込むにはどうすればよいですか？また、フルロードとCDCのどちらを選択すればよいですか？
- APIからデータを取り込むにはどうすればいいですか?
- ストリーミングデータやイベントデータを取り込むには？
- How do I ingest files reliably?
- データを失わずにインジェストの失敗を処理するにはどうすればよいですか？
変換とモデル化
Transformation turns ingested data into clean tables that people and tools can trust. This is where the medallion pattern (bronze to silver to gold) takes concrete form.
Cleaning and validation come first. Expectations are a built-in Lakeflow pipeline feature: data quality constraints the pipeline evaluates on every row of every run, reporting pass and fail counts, so quality is continuous rather than a one-time gate. Decide what happens when a row fails (warn and keep it, drop it, or fail the update) and where the gate belongs. Gates usually sit at the bronze-to-silver boundary, so everything downstream can be trusted without re-checking.
Joining and aggregating shape the silver-to-gold step. A materialized view fits a batch-style join or aggregation over existing tables, because it keeps results consistent with its sources: it refreshes incrementally when the query and sources allow and otherwise recomputes in full, producing the same result either way. That makes it the right choice when correctness matters more than latency, since it recomputes joins when a dimension changes. See How do pipelines refresh?. Joining live streams raises unbounded state, so streaming joins and aggregations need a watermark to bound how long the pipeline waits for late-arriving data.
このステージには、2つの正確性に関する考え方が通底しています：
- Idempotency means a pipeline produces the same result however many times it runs over the same input. Lakeflow pipelines are idempotent for the pieces they manage, such as checkpointed reads and key-based
AUTO CDCupserts; you keep your own logic idempotent by avoiding non-deterministic functions in recomputed views. - 「最低 1 回」と「厳密に 1 回」の処理。 管理された Delta-to-Delta テーブルは、各マイクロバッチの入力と出力をまとめて commit するため、default で「厳密に 1 回」の処理が実現されます。これは、カスタムシンク、非 Delta ターゲット、または未検証のカスタムソースなどの境界で停止します。これらの場合、書き込みを「最低 1 回」として扱い、キーに基づく Upsert などによってべき等にする必要があります。
Slowly changing dimensions (SCDs) also live here: AUTO CDC implements SCD Type 1 and Type 2 directly, so you set a type rather than write history-tracking logic.
In this stage
このステージで考慮すべき質問：
- 受信データをクリーニングおよび検証するにはどうすればよいですか？
- 緩やかに変化するディメンション（SCD）を使用して時間の経過に伴う履歴を追跡するにはどうすればよいですか？SCD とは何ですか？
- ストリーミングデータと静的データをJOINする方法データを効率的に集計する方法
- 下流での使用に向けてデータをモデル化するにはどうすればよいですか？
- How do I ensure processing guarantees in Lakeflow pipelines?
- 少なくとも1回処理と厳密に1回処理の違いは何ですか？どちらが必要ですか？
- How do I handle late-arriving or out-of-order data?
Operationalize
Operationalizing moves a pipeline from something that runs for you to something the team can build, test, and ship repeatably. A pipeline is source code plus configuration, so ordinary software-engineering practices apply.
テストは、変換ロジックと、それを流れるデータの継続的な品質という 2 つの側面を同時にカバーします。エクスペクテーションは、データ側を継続的に処理します。ロジックについては、変換をプレーンな関数に分解してランタイム外で単体テストを行い、何かをマテリアライズする前にドライランでパイプライングラフを検証してください。パイプラインの単体テストを参照してください。
Keep pipeline code in Git and package it for deployment so it can be reviewed, reverted, and deployed consistently across environments. The package is not an alternative to Lakeflow pipelines. It is the project and CI/CD wrapper around your pipeline, and your data logic stays declarative. Parameterize environment-specific values like catalog names and paths so the same code runs unmodified in each environment. See Use parameters with pipelines.
スケジュール上でパイプラインを実行するには、 ワークフロー内のパイプライン実行でラップします。Databricksはジョブとのパイプラインのスケジューリングとオーケストレーションを推奨しており、これにより下流レポートや複数のパイプラインの連結など他の作業とパイプラインを調整することも可能です。実行内では パイプライン が独自のデータセットを注文・並列化するため、オーケストレーションはパイプライン外のタスクのみを調整します。
In this stage
このステージで考慮すべき質問：
- How do I test a data pipeline, and why is that different from testing regular software?
- How do I version-control and collaborate on pipeline code as a team?
- パイプラインを自動で実行させるにはどうやってスケジュールやオーケストレーションを組めばいいですか?
- パイプラインを開発環境からステージング環境、本番運用環境へ安全に移行するにはどうすればよいですか？
- パイプラインの CI/CD をセットアップするにはどうすればよいですか？
Run in production
パイプラインが実際のデータに対して無人で稼働すると、その健全かどうかを見極め、そうでないときに修正することが課題となります。
Monitoring works at three levels of depth. The Jobs & Pipelines list gives an at-a-glance status for recent runs. The pipeline monitoring UI shows every table and flow color-coded by status, with row counts, data quality metrics, and backlog metrics for streaming tables. The event log underneath both is the source of truth for anything programmatic or historical. Configure failure notifications so you learn about a broken run before your stakeholders report it. For an overview of the monitoring surfaces, see Monitor pipelines.
Debug by working backward from the failure highlighted on the graph to the full error detail in the event log, then re-run only what failed. Retry behavior differs by trigger: manually triggered updates disable automatic retries so you see errors immediately, while scheduled updates retry recoverable failures. A production alert might therefore clear itself on retry where the same failure won't during interactive development. While developing, Genie Code can help diagnose and fix code-level errors as you iterate, though today it targets authoring pipelines rather than diagnosing production runs.
バックフィルを、通常の増分フローと同じターゲットに供給する、明示的な1回限りのフローとしてモデル化します。履歴がいつ、どのように読み込まれたかを個別のレコードとして保持することで、定常状態のロジックをシンプルに保ちます。
パイプラインを保護するには、操作権限を制御し、個人アカウントではなく専用の Service Principal として実行し、認証情報をソースコードではなく Secret Scope に保持します。リネージは自動であり、列レベルまでキャプチャされます。パイプラインは、LakeFlow Pipelines のシンクを通じて外部システムに書き込みを行います。これは、前述の「少なくとも1回」という考え方が適用される境界です。
In this stage
このステージで考慮すべき質問：
- How do I monitor whether my pipeline ran successfully?
- 何かが壊れたときにどうやってアラートを受ければいいのですか?
- 失敗したパイプラインのランをデバッグするにはどうすればよいですか？
- ヒストリカルデータをバックフィルするにはどうすればよいですか？
- パイプラインの運営コストをどう管理し予測すればいいですか?
- 認証情報、アクセス制御、個人情報を含むパイプラインをどのように保護すればよいですか?
- パイプラインのドキュメント化とデータリネージの追跡を行うにはどうすればよいですか？
Mature and scale
成熟したパイプラインは、書き換えなしで自動的に実行され、拡張されます。準備状況の確認とスケーリング方法の計画が、このステージを定義します。
本番運用の準備状況は、データ品質、信頼性、観測可能性、デプロイメント、コスト、ガバナンスにわたるチェックリストです。チェックされていない項目はすべて既知のギャップとして扱ってください。不正なデータを受け取る可能性のある各データセットに期待（expectation）が設定されているか、パイプラインは手動起動ではなくスケジュールされているか、失敗通知が構成されているか、Service Principalとして実行されているか、少なくとも開発環境と本番環境のターゲットに対してバージョン管理からデプロイされているかを確認します。データ品質と通知は、追加コストが最も低く、検出されない不正なランをキャッチする可能性が最も高い機能です。
パイプラインの健全性が低下しているという具体的なシグナルに応じてスケーリングします：
- 更新期間が上昇傾向にあります。
- Autoscaling is repeatedly hitting its ceiling.
- コストが基礎となるビジネスよりも速いペースで増加しています。
- Materialized views are falling back to full recomputes.
Try compute-level levers first, such as moving to serverless or matching its performance mode to your latency needs. Beyond that, how you organize datasets across pipelines matters most:
- パイプラインには同時実行数の制限があります 。一度に更新できるデータセットの数は決まっています。パイプラインのデータセット数がその制限を超えると、超過分の更新はキューで待機するため、パイプラインの合計更新時間が増加します。
- 関連するデータセットをグループ化し、関連のないデータセットを分割します。 ドメイン、共有更新周期、依存関係でグループ化し、オーナシップ、レイヤー、レイテンシの境界で分割します。例えば、取り込みと変換を分離することで、低速な取り込みがダウンストリームのすべてを遅延させることを防ぎ、各パイプラインを同時実行制限内に収まる小ささに保つことができます。
すでに本番運用されている大きなパイプラインを分割するよりも、後から 2 つの小さなパイプラインをマージする方が簡単です。データセットのグループ化および分割方法については、Lakeflow Pipelines全体でのデータセットの整理を参照してください。
In this stage
このステージで考慮すべき質問：