ワークフローをデバッグする
約25分 · 1つのステップを実行、データをプレビュー、ログを読む、入力をたどる
ワークフローのどこかがおかしい状況を想定します。ステップが赤くなっている、下流の数値が誤っているように見える、実行が途中で止まった、といったケースです。このチュートリアルでは、原因を突き止めるための手動ツール一式を順に使います。1つのステップだけを単独で実行し、出力されたものをプレビューし、ワークフローログを読み、依存関係監査で入力の出どころをたどり、エラーそのものを読み解きます。各ツールは異なる問いに答えるもので、組み合わせれば、たいていは推測せずに原因にたどり着けます。
説明してもらいたい場合は？ AI支援による方法では、同じ調査を対話形式で行います。このチュートリアルは手動版で、すべて自分で操作します。アシスタントが実際に何を見ているのかを理解するために、少なくとも一度は試す価値があります。
デバッグの流れ
Section titled “デバッグの流れ”ワークフローのデバッグは、どのツールから始めても、ほとんどが同じ短いループです。
- 調査対象の問題（赤いステップ、誤った結果、停止した実行）があるワークフローを含むプロジェクトを持つ、PlaidCloudワークスペース。
- ビジュアルワークフローデザイナーに関する知識。この作業の大半は、このキャンバス上で行います。
ステップ1：壊れたステップだけを実行する
Section titled “ステップ1：壊れたステップだけを実行する”1つの変更を試すためにワークフロー全体を再実行しないでください。時間がかかるうえ、すでに信頼できる処理までやり直してしまいます。調査しているステップだけを実行します。
- ビジュアルワークフローデザイナーでワークフローを開きます。
- テストしたいステップを右クリックし、コンテキストメニューからステップを実行を選択します。
- ステップは単独で実行され、ソーステーブルにすでにあるデータが対象になります。
最後の点は、デバッグでは重要です。ステップは、ソーステーブルを現在の状態のまま読み取ります。上流のステップがまだ実行されていない、または古いデータで実行された場合、このステップを単独で実行すると、その状態がそのまま反映されます。まさにステップ4で見つけやすくなる点です。
詳細については、ワークフロー内の1つのステップの実行をご覧ください。
ステップ2：ステップの出力をプレビューする
Section titled “ステップ2：ステップの出力をプレビューする”ステップを実行したら、正しいかどうかを判断する前に、実際に何が書き込まれたかを確認します。データプレビュードロワーは、ステップの出力データをキャンバス上にそのまま表示します。型付きの列を持つ最初の100行が、下部にドッキングして表示されます。
開き方は3つあり、いずれも同じドロワーが開きます。
- ステップタイルにカーソルを合わせる — タイルの右下に、小さな参照（テーブル）アイコンが表示されます。これをクリックします。
- ステップを右クリックし、出力データをプレビューを選択します。
- インスペクターで、ステップの出力セクションにある任意の出力カードの目のアイコンをクリックします。
何を確認するかは、症状によって異なります。
| 症状 | プレビューで確認すること |
|---|---|
| 列が誤っている、または足りない | ステップは、想定した列を出力しましたか。結合や列の選択の誤りは、まずここに現れます。 |
| 行が少なすぎる、または多すぎる | ヘッダーにShowing first N of ~M rowsと表示されます。合計は、想定したおおよその件数ですか。 |
| 出力が空 | ドロワーにTable is empty（実行済みで0行）またはNo data yet — run the step（未実行）と表示されます。 |
| 不審な値 | 列を並べ替えて、NULLや外れ値を上部に表示します。 |
ドロワーを開いている間、別のステップをクリックすると、プレビューがそのステップの出力に切り替わります。ステップの連なりをたどりながら、データが最初におかしくなる箇所を確認できます。フィルター、スライス、または最初の100行を超えて表示したい場合は、ドロワーのヘッダーにあるテーブルエクスプローラーで開くをクリックします。
詳細については、ステップデータのプレビューをご覧ください。
ステップ3：ワークフローログを読む
Section titled “ステップ3：ワークフローログを読む”プレビューは出力がどのような内容かを示します。ログは、ステップの実行時に何が起きたかを示します。失敗した場合は、エラーメッセージも含まれます。
ステップの実行中や警告の発生時、そのイベントはワークフローログに書き込まれます。プロジェクトエリアのログタブから確認できます。ビジュアルワークフローデザイナー内では、ツールバーのログを表示ボタンから、開いているワークフローで絞り込み済みの同じビューが開きます。
- ログタブ（プロジェクトログ）を開きます。ツールバーのログを表示ボタン、またはプロジェクトエリアのログタブから開けます。
- ログメッセージの横にあるフィルターコントロールで、関心のあるステップと実行に絞り込みます。
- ログエントリを開いて詳細を読みます。失敗したステップのエラーメッセージは、ここにあります。
問題が複数のワークフローにまたがる可能性がある場合は、プロジェクトレベルのログで複数のワークフローをまとめて確認できます。ワークフローログの表示をご覧ください。
エラーメッセージの読み方。 ログエントリの文言を、そのままコピーしてください。誤った結合キー、型の不一致、ソーステーブルの欠落は、それぞれ異なる表現で現れます。ステップがエラーになる原因として最も多いのは、テーブル間の結合キーの不一致と、計算列での予期しないNULL値です。メッセージがステップの設定ではなくデータを指している場合は、入力をたどるべきサインです。
具体例。 変換ステップが赤くなったとします。ログを開くと、エントリには
column "revenue" does not existとあります。ソーステーブルにはrevenueではなくnet_revenueという列があります。1行の修正で、ステップの式の列名を直します。そのステップだけをもう一度実行すると、緑に戻ります。これが、ループ全体を1回で通した流れです。
ステップ4：依存関係監査で入力をたどる
Section titled “ステップ4：依存関係監査で入力をたどる”ステップが正しく設定されているのに、誤ったデータが出力されることがあります。入力が順序どおりに作成されないまま実行されたためです。データがすでにテーブルにある場合、ステップは古いデータや未更新のデータを読み取っていても、実行され、正しそうに見えます。エラーが発生していないため、ログには表れない失敗です。
ワークフロー依存関係監査は、まさにこのためのものです。相互に連携するワークフロー全体のデータとワークフローの依存関係を分析し、読み取られるタイミングに対して入力が誤った順序で作成されているステップを特定します。
次のような場合に使います。
- ステップの出力は誤っているが、ステップ自体にはエラーがない。
- ステップの順序を変更または追加したため、テーブルが作成される前に読み取っているものがないかを確認したい。
- ワークフローは全体を実行すると「動く」が、単一ステップの実行では結果が異なる。順序の依存関係がある典型的な兆候です。
監査の開き方と読み方については、依存関係監査の表示をご覧ください。
ステップ5：ワークフローがエラーをどう扱うかを決める
Section titled “ステップ5：ワークフローがエラーをどう扱うかを決める”原因を理解したら、今後このステップが失敗したときにワークフローがどう動くべきかを決めます。各ステップのエラー処理はステップフォームで設定し、PlaidCloudには3つのレベルがあります。
| 動作 | 内容 | 使いどき |
|---|---|---|
| ワークフローを停止 | 実行が停止し、ステップとワークフローの両方にエラーを示す表示が出ます。 | デフォルトであり最も一般的です。ワークフローは通常、エラーなく実行されるべきです。 |
| 処理を続行 | ステップにはエラーのマークが付きますが、ワークフローはそれを完了として扱い、続行します。 | データが欠落していてもエラーになっても問題のないステップ。注意：ワークフローにはエラーではなく、実行中の表示が出ます。 |
| 修復ワークフローを起動 | 現在のワークフローが停止し、代わりに修復ワークフローが開始されます。 | 自動通知や自動修正。処理を続行に設定されたステップでは起動しません。 |
PlaidCloudは、失敗したステップを自動的に再試行することもできます。回数を指定でき、秒から時間までの任意の待機時間も設定できます。論理的なバグではなく、リモートシステムやデータソースへの接続が断続的に失敗するステップには、これが適しています。ステップのエラーへの対処をご覧ください。
ステップ6：修正、再実行、確認
Section titled “ステップ6：修正、再実行、確認”- 調査で判明した変更を加えます。結合キーの修正、上流のステップの追加、NULLを生成する式の修正、ステップの順序の変更などです。
- そのステップだけをもう一度実行し（ステップ1）、出力をプレビューします（ステップ2）。実行中にドロワーを開いていた場合は、実行の完了後に自動的に更新されます。
- ステップが正しくなったら、ワークフローを最初から最後まで実行し、ログを見てパイプライン全体に問題がないことを確認します。
ワークフローの動作（ステップ、関数、変数）を恒久的に記録するには、ワークフロー階層のレポートアイコンから、オンデマンドのワークフローレポートを生成します。ワークフローの現在の状態が反映され、修正後のドキュメントとして役立ちます。ワークフローレポートの表示をご覧ください。
これでループ全体が完了です。 1つのステップを単独で実行し、書き込まれた内容をプレビューし、ログでエラーを読み、依存関係監査で入力をたどり、再実行して修正を確認しました。AIアシスタントが行うのと同じ調査を、今度は自分で進められます。
次のステップ
Section titled “次のステップ”- AIアシスタントでワークフローを修正する — 同じ調査を対話形式で行う
- ワークフロー内の1つのステップの実行 — 1つのステップを単独で実行する
- ステップデータのプレビュー — データプレビュードロワー
- ワークフローログの表示 — 実行イベントとエラーの記録先
- 依存関係監査の表示 — 順序が誤ったデータ依存関係を検出する
- ステップのエラーへの対処 — 停止、続行、修復、再試行
- ワークフローレポートの表示 — ワークフロー全体のオンデマンドドキュメント