Knowledge Catalog を使用すると、メタデータを保存して管理できます。Dataform リポジトリは、追加の構成なしでデフォルトで Knowledge Catalog で使用できます。Knowledge Catalog は、Dataform リポジトリから次のメタデータを自動的に取得します。
データアセット名
データアセットの親
データアセットのロケーション
データアセットのタイプ
対応する Google Cloud プロジェクト
サードパーティのリポジトリ ソース
サービス アカウント
始める前に
-
Google Cloud コンソールのプロジェクト セレクタページで、 Google Cloud プロジェクトを選択または作成します。
プロジェクトの選択または作成に必要なロール
- プロジェクトを選択する: プロジェクトを選択する際に、特定の IAM ロールは必要ありません。ロールが付与されているプロジェクトを選択できます。
-
プロジェクトを作成する: プロジェクトを作成するには、
resourcemanager.projects.create権限を含むプロジェクト作成者のロール（roles/resourcemanager.projectCreator）が必要です。詳しくは、ロールを付与する方法をご覧ください。
-
Dataplex API と Data Lineage API がまだ有効になっていない場合は、有効にします。
API を有効にするために必要なロール
API を有効にするには、
serviceusage.services.enable権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を確認する。 必要な Identity and Access Management（IAM）権限があることを確認します。
必要なロール
Dataform リポジトリを管理し、Knowledge Catalog でデータリネージを表示するには、Dataform リソースへのアクセス権を付与する事前定義された Dataform ロールと、必要な Knowledge Catalog ロールが必要です。
次の表に、各プリンシパルが Dataform データリネージを記録して表示するために必要なロールを示します。
| タスク | プリンシパル | 必要なロール | ロールを付与する場所 |
|---|---|---|---|
| ワークフロー呼び出しからリネージを記録する | リポジトリ、リリース構成、ワークフロー構成のカスタム サービス アカウント。カスタム サービス アカウントが設定されていない場合は、Dataform サービス エージェント（service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com）。 |
データリネージ イベント プロデューサー（roles/datalineage.producer） |
リポジトリが含まれているプロジェクト |
| Dataform CLI からリネージを記録する | CLI が使用するアプリケーションのデフォルト認証情報 | データリネージ イベント プロデューサー（roles/datalineage.producer） |
各出力テーブルのプロジェクト |
| リネージグラフを表示する | リネージを表示するユーザー | データリネージ閲覧者（roles/datalineage.viewer） |
リネージが記録されるプロジェクトと、リネージを表示するプロジェクト |
| リネージグラフから Dataform を開く | リネージを表示するユーザー | Dataform 閲覧者（roles/dataform.viewer）、または dataform.repositories.get 権限と dataform.workflowInvocations.get 権限 |
リポジトリが含まれているプロジェクト |
| BigQuery テーブルの詳細を表示する | リネージを表示するユーザー | BigQuery データ閲覧者（roles/bigquery.dataViewer）または bigquery.tables.get 権限 |
テーブルを保存するプロジェクト |
| BigQuery ジョブの詳細を表示する | リネージを表示するユーザー | BigQuery リソース閲覧者（roles/bigquery.resourceViewer）または bigquery.jobs.get 権限 |
ジョブを実行するプロジェクト |
データリネージ イベント プロデューサーのロールには、リネージの記録に必要な datalineage.locations.processOpenLineageMessage 権限が含まれています。
Knowledge Catalog でメタデータを管理する
Knowledge Catalog は、Dataform リポジトリを次の値を持つエントリとしてログに記録します。
- システム エントリ グループ
- Dataform リポジトリのシステム エントリ グループは
@dataformです。Knowledge Catalog でリポジトリ エントリの詳細を表示するには、dataformシステム エントリ グループを表示する必要があります。エントリ グループ内のすべてのエントリのリストを表示する方法については、Knowledge Catalog のドキュメントのエントリ グループの詳細を表示するをご覧ください。 - システム エントリ タイプ
- Dataform リポジトリのシステム エントリタイプは
dataform-repositoryです。Dataform リポジトリの詳細を表示するには、dataform-repositoryシステム エントリタイプを表示する必要があります。選択したエントリタイプの詳細を表示する手順については、Knowledge Catalog ドキュメントのエントリタイプの詳細を表示するをご覧ください。選択したエントリの詳細を表示する手順については、Knowledge Catalog ドキュメントのエントリの詳細を表示するをご覧ください。
アセットを検索する
Knowledge Catalog でデータアセットを検索する方法については、Knowledge Catalog ドキュメントの Knowledge Catalog でデータアセットを検索するをご覧ください。
リポジトリにアノテーションを付ける
Knowledge Catalog の Dataform リポジトリにコンテキストを追加するには、Dataform エントリにアスペクトをアノテーションします。
Dataform リポジトリのシステム アスペクト タイプは dataform-repository です。
エントリにアスペクトをアノテーションする方法については、Knowledge Catalog ドキュメントのアスペクトを管理してメタデータを拡充するをご覧ください。
Knowledge Catalog でデータリネージを追跡する
Dataform は、Dataform ワークフローと BigQuery パイプラインで実行するアクションのデータリネージを Knowledge Catalog に報告します。実行されたアクションごとに、Knowledge Catalog と BigQuery のリネージグラフに、アクションが読み取るテーブルと書き込むテーブル間の Dataform プロセスが表示されます。リネージを報告するために SQLX ファイルを変更する必要はありません。
Dataform データリネージは、次のタスクに使用できます。
影響分析: テーブルを変更する前に、すべてのダウンストリーム アクションとテーブルを特定します。
根本原因分析: 誤ったデータを、そのデータを書き込んだアクションとワークフロー呼び出しまで追跡します。
ガバナンス: プロジェクト間でデータがどのように流れるか、どのパイプラインがデータを移動したかを示します。
エンドツーエンドのリネージ: BigQuery、Managed Service for Apache Airflow、Managed Service for Apache Spark、Dataflow のリネージとともに、Dataform のリネージを 1 つのグラフで表示します。
データリネージの仕組み
Dataform は、アクションの開始時に OpenLineage START イベントを Data Lineage API に送信します。アクションが終了すると、Dataform は COMPLETE、FAIL、または ABORT イベントを送信します。各 Dataform アクションは、BIGQUERY_PIPELINES ソースタイプを持つプロセスとして Knowledge Catalog に表示され、アクションの各実行はそのプロセスの実行として表示されます。
次の表に、リネージを報告する Dataform アクション タイプを示します。
| 操作の種類 | リネージを報告する |
|---|---|
hasOutput: true を使用したテーブル、ビュー、増分テーブル、マテリアライズド ビュー、アサーション、プロパティ グラフ、データ準備、オペレーション |
はい。プロセス、実行、テーブル間のリネージリンクを報告します。 |
hasOutput: true を使用しないオペレーション |
処理と実行のみ。入力と出力が空であるため、テーブル間のリネージリンクは作成されません。 |
| 宣言 | いいえ。宣言は、他のアクションへの入力としてのみ表示されます。 |
| Notebook、SQL 単体テスト | いいえ |
リネージの報告によってワークフローの呼び出しが失敗することはありません。Data Lineage API が無効になっている、権限がない、または割り当てを超過している場合、Dataform はリネージ レポートをスキップし、ワークフローの呼び出しは変更なしで続行されます。
Dataform は、各アクションの BigQuery 処理ロケーションのリージョン エンドポイントにリネージを書き込みます。リージョン エンドポイントが使用できない場合、Dataform はリネージをグローバル エンドポイントに書き込みます。
Dataform ワークフローがデータリネージにマッピングされる仕組み
次の表に、Dataform 実行エンティティが Knowledge Catalog データリネージ情報モデルにどのようにマッピングされるかを示します。
| データリネージ オブジェクト | Dataform の同等機能 |
|---|---|
| プロセス | Dataform アクション |
| 実行 | ワークフロー呼び出しでのアクションの 1 回の実行 |
| リネージ イベント | その実行の入力テーブルから出力テーブルへのリンク |
データリネージを設定する
データリネージを報告するように Dataform を設定する手順は次のとおりです。
Dataform リポジトリを含むプロジェクトと、ユーザーがリネージを表示するプロジェクトで、Data Lineage API（
datalineage.googleapis.com）を有効にします。リポジトリを含むプロジェクトで、ワークフローを実行する ID にデータリネージ イベント プロデューサーのロール（
roles/datalineage.producer）を付与します。リポジトリ、リリース構成、またはワークフロー構成でカスタム サービス アカウントを使用する場合は、カスタム サービス アカウントにロールを付与します。
カスタム サービス アカウントが設定されていない場合は、Dataform サービス エージェント（
service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com）にロールを付与します。
Google アカウントのユーザー認証情報で実行されるワークフロー呼び出しは、リネージを報告しません。
データリネージを有効または無効にする
最初のロールアウト期間中は、データリネージ レポートはオプトインです。
リポジトリまたは BigQuery パイプラインのデータリネージ レポートを制御するには、workflow_settings.yaml ファイルで lineage.enabled プロパティを設定します。
Google Cloud コンソールで、[Dataform] ページに移動します。
リポジトリを選択し、開発ワークスペースを選択します。
[Files] ペインで、
workflow_settings.yamlファイルを開きます。データリネージ レポートを有効にするには、次の
lineageブロックを追加します。lineage: enabled: trueリネージがデフォルトで有効になった後に、リポジトリをデータリネージ レポートから除外するには、
enabledをfalseに設定します。lineage: enabled: false変更をリポジトリに commit して push します。
プロジェクト全体でデータリネージ レポートを停止するには、プロジェクトで Data Lineage API を無効にします。API を無効にすると、プロジェクト内の他のサービスからのデータリネージ レポートも停止します。
データリネージを表示する
Dataform アクションによって生成されたテーブルのデータリネージを表示する手順は次のとおりです。
Google Cloud コンソールで、[BigQuery] ページに移動します。
[エクスプローラ] ペインで、プロジェクトとデータセットを開き、Dataform アクションによって生成されるテーブルを選択します。
[リネージ] タブをクリックします。
アクション、リポジトリ、実行を表示するには、Dataform プロセスノードを選択します。
Dataform でリポジトリを開くには、[Dataform で開く] をクリックします。
リネージグラフの操作の詳細については、Knowledge Catalog でデータリネージを表示するをご覧ください。
Dataform CLI からデータリネージを報告する
Dataform CLI のローカル実行または CI 実行からデータリネージを報告するには、workflow_settings.yaml で lineage.enabled: true を設定するか、次のコマンドを実行します。
dataform run --emit-lineage
--emit-lineage フラグと --no-emit-lineage フラグは、1 回の実行で lineage.enabled 設定をオーバーライドします。
Dataform CLI は、アプリケーションのデフォルト認証情報を使用し、各出力テーブルのプロジェクトにリネージを記録します。これらの各プロジェクトで、Data Lineage API を有効にし、データリネージ イベント プロデューサーのロール（roles/datalineage.producer）を認証情報に付与します。CLI は、[lineage] 接頭辞を付けてリネージ メッセージを stderr に書き込みます。
CLI からリネージを報告する方法については、GitHub の Dataform CLI リファレンスをご覧ください。
データリネージのトラブルシューティング
次の表に、一般的なデータリネージの問題とその修正方法を示します。
| 症状 | 考えられる原因 | 修正 |
|---|---|---|
| [リネージ] タブに Dataform ノードが表示されない。 | Data Lineage API が無効になっている。 | リポジトリを含むプロジェクトと、リネージを表示するプロジェクトで API を有効にします。 |
| リポジトリがリネージを報告しない。 | ワークフローを実行する ID に、データリネージ イベント プロデューサーのロールがない。 | カスタム サービス アカウントまたは Dataform サービス エージェントに roles/datalineage.producer を付与します。 |
| ユーザー認証情報で実行されるワークフロー呼び出しは、リネージを報告しません。 | リネージ レポートはユーザー認証情報をサポートしていません。 | カスタム サービス アカウントを使用してワークフローを実行します。 |
| ロールが付与されているにもかかわらず、リポジトリがリネージを報告しない。 | Dataform がカスタム サービス アカウントとして機能できない。 | カスタム サービス アカウントに対するサービス アカウント トークン作成者のロール（roles/iam.serviceAccountTokenCreator）を Dataform サービス エージェントに付与します。 |
| 1 つのリポジトリがリネージを報告しない。 | リポジトリがオプトアウトされている。 | lineage.enabled: false を workflow_settings.yaml から削除してください。 |
| 一部の実行でリネージが欠落している。 | Data Lineage API の割り当てを超過している。 | ワークフローの実行を分散するか、割り当ての増加をリクエストします。 |
| CLI の実行で、一部のテーブルのリネージが報告されない。 | 出力テーブルのプロジェクトで API が有効になっていないか、ロールが付与されていない。 | API を有効にして、そのプロジェクトでロールを付与します。 |
| [Dataform で開く] をクリックすると、権限エラーが返されます。 | ユーザーに Dataform へのアクセス権がない。 | ユーザーに Dataform 閲覧者ロール（roles/dataform.viewer）を付与します。 |
ワークフロー呼び出しで最初の権限エラーまたは API エラーが発生すると、Dataform はそのワークフロー呼び出しの残りのリネージの報告を停止します。次のワークフロー呼び出しで、リネージの報告が再試行されます。
データリネージの問題についてサポートに問い合わせる場合は、ワークフロー呼び出し ID、プロジェクト ID、リージョンを記載してください。
ワークフロー呼び出しのリネージログを表示する
Cloud Logging では、Dataform はリネージ ログエントリを dataform.googleapis.com/lineage_emission ログに書き込みます。各エントリには、workflowInvocationId、actionTarget、eventType フィールドが含まれます。
ワークフロー呼び出しのリネージログを表示する手順は次のとおりです。
Google Cloud コンソールで、ワークフロー呼び出しの詳細ページを開きます。
[ログを表示] をクリックします。
Logging が開き、
jsonPayload.workflowInvocationIdによるワークフロー呼び出しにフィルタされたログが表示されます。
各リネージ ログエントリの outcome フィールドには、次のいずれかの値が含まれます。
SUCCEEDED: Data Lineage API がイベントを受け入れました。これらのエントリの重大度はDEBUGで、eventTypeはSTART、COMPLETE、FAIL、ABORTのいずれかです。SKIPPED: Dataform がリネージ レポートをスキップしました。これらのエントリの重大度はINFOで、ワークフロー呼び出しの理由ごとに 1 回ログに記録されます。skipReasonフィールドがAPI_DISABLED、PERMISSION_DENIED、EUC_UNSUPPORTED、AUTHORITY_UNAVAILABLEのいずれかで、errorMessageフィールドに修復手順が含まれている。FAILED: 再試行後にリネージ レポートが失敗しました。これらのエントリの重大度はWARNINGで、errorCodeフィールドとerrorMessageフィールドが含まれています。
ログ エクスプローラでスキップされたリネージ レポートまたは失敗したリネージ レポートをフィルタするには、次のクエリを実行します。
log_id("dataform.googleapis.com/lineage_emission")
jsonPayload.outcome=("SKIPPED" OR "FAILED")
Dataform CLI からのデータリネージ メッセージ
Dataform CLI は、次のリネージ メッセージを stderr に書き込みます。
skip_reason=workflow_opt_out:lineage.enabledはfalseに設定されています。skip_reason=invocation_override:--no-emit-lineageまたは--emit-lineage=falseを使用したこの実行では、リネージ レポートがオフになっています。skip_reason=dry_run: ドライランではリネージは報告されません。skip_reason=api_disabled: Data Lineage API が有効になっていません。CLI は、この実行でこれ以上リネージ リクエストを送信しません。skip_reason=permission_denied: 認証情報にデータリネージ イベント プロデューサーのロール（roles/datalineage.producer）がありません。CLI は、この実行でリネージ リクエストを送信しません。Failed to emit lineage for action ...: : 1 つの アクションでリネージ レポートが失敗しました。他のアクションのリネージ レポートは継続されます。
制限事項
Knowledge Catalog で Dataform リポジトリを管理し、データリネージを追跡するには、次の制限があります。
Knowledge Catalog で使用できるのは、リポジトリレベルとワークフローレベルのエントリのみです。Dataform の個々のファイルレベルのコードアセット（SQLX 定義ファイルなど）は、個別のエントリとしてカタログ化されません。
Dataform はテーブルレベルのリネージのみを報告します。列レベルのリネージは報告されません。
宣言、ノートブック、SQL 単体テストでは、リネージは報告されません。宣言は、他のアクションへの入力としてのみ表示されます。
hasOutput: trueのないオペレーションでは、プロセスと実行のみが報告され、テーブル間のリネージリンクは報告されません。Google アカウントのユーザー認証情報で実行されるワークフロー呼び出しは、リネージを報告しません。リネージを報告するには、カスタム サービス アカウントを使用します。
データリネージ レポートは、プロジェクト、ID、リージョンごとの書き込みに関する Data Lineage API の割り当ての対象となります。標準ティアでは、割り当ては 1 分あたり約 1,000 アクションです。
ロケーション
Knowledge Catalog を使用すると、すべての Dataform ロケーションから Dataform リポジトリを管理できます。
割り当て
Knowledge Catalog で Dataform リポジトリを管理する場合は、Knowledge Catalog の割り当てと上限が適用されます。
料金
Knowledge Catalog で Dataform リポジトリを管理する場合は、Knowledge Catalog の料金が適用されます。
データリネージの取り込みは、Knowledge Catalog プレミアム処理 SKU で課金されます。テーブル間のリネージリンクを書き込むイベントのみが課金されます。データリネージ ストレージは、メタデータ ストレージ SKU で課金されます。データリネージの費用を管理するには、workflow_settings.yaml でワークフローをオプトアウトするか、Data Lineage API を無効にします。
次のステップ
- Knowledge Catalog の詳細については、Knowledge Catalog のドキュメントの Knowledge Catalog の概要をご覧ください。