データリネージ

要点 Apache Doris は、INSERT、INSERT OVERWRITE、CREATE TABLE AS SELECT の解析済み Nereids プランから、JOIN、FILTER、GROUP BY、WINDOW、CASE WHEN の依存関係を含むカラム単位のリネージを抽出します。イベントは SPI を通じて、カスタムエミッター、OpenLineage の受信側、Apache Atlas、DataHub など、用意したリネージの送信先に流れます。アドホッククエリのテーブル単位のリネージについては、audit_log システムテーブルにクエリごとの参照元テーブルと選択されたマテリアライズドビューが記録されます。

Apache Doris のデータリネージを使う理由

Apache Doris のデータリネージを使うと、プランナーがすでに計算したカラム単位の依存関係を取得できます。そのため、ガバナンスツール内に SQL パーサーを作らなくても、変更の影響分析や監査上の問いに答えられます。たとえば、ベーステーブルのカラムの型を変更した四時間後に、ダッシュボードが NULL を返し始めたとします。あるいは、tgt_region_revenue.revenue の値が実際にはどこから来たのか尋ねられても、「過去三年間の INSERT 文のどこかから」としか答えられないかもしれません。依存関係は実在し、SQL もシステム内にありますが、照会できるグラフにまとめられていません。マルチカタログ連携を経由する書き込みや、増分マテリアライズドビューへの書き込みは、そのグラフをさらに大きくします。

ガバナンスツール内に独自の SQL パーサーを作るのは適切な解決策ではありません。データベースはすでに SQL を解析しています。必要なのは、データベースが見つけた依存関係を、各出力カラムを生成した変換とともに、カラム単位で受け取ることです。そうすれば、リネージは DDL を静的に読み取った結果ではなく、実際に実行された処理に対応します。

この機能で答えられる代表的な問いは次のとおりです。

• orders.o_discount を削除すると、下流のどのテーブルとカラムに影響が出るか。
• ダッシュボード上のこの数値はどこから来たか。
• このユーザーは先週、規制対象のどのテーブルにアクセスしたか。

Apache Doris のデータリネージとは

Apache Doris のデータリネージは、Nereids プランナーに組み込まれたカラム単位のリネージ抽出機能と、抽出したイベントを任意のガバナンスバックエンドに送信する SPI で構成されます。組み込みの閲覧画面はありません。Apache Doris がデータの生成側であり、既存のツール（Atlas、DataHub、OpenMetadata、社内サービス）が受信側です。クエリ履歴から得るテーブル単位のリネージについては、audit_log テーブルにクエリごとの参照元テーブルとマッチしたマテリアライズドビューがすでに記録されています。そのため、プラグインを書かなくても大まかなグラフを構築できます。

主な用語

• LineageInfo: メモリ内で使用するイベント形式です。出力カラムごとに、直接リネージの種類（IDENTITY、TRANSFORMATION、AGGREGATION）と参照元の式を保持します。また、データセット単位の間接リネージ（JOIN、FILTER、GROUP_BY、SORT）と、カラム単位の間接リネージ（WINDOW、CONDITIONAL）も保持します。
• LineagePlugin: LineageInfo イベントを受け取るために実装する SPI です。クラスパス上の ServiceLoader、または $plugin_dir/lineage/ に配置した外部 jar によって検出されます。
• activate_lineage_plugin: イベントを受け取るプラグインを指定する FE 設定です。デフォルトでは空なので、プラグインを有効にするまでプランナーはリネージの処理を行いません。
• audit_log.queried_tables_and_views: 各クエリが参照したカタログ名付きのテーブルを列挙する ARRAY<STRING> 型のカラムで、__internal_schema.audit_log にあります。
• audit_log.chosen_m_views: オプティマイザーがクエリの書き換えに使用したマテリアライズドビューを列挙するカラムです。

Apache Doris のデータリネージの仕組み

Apache Doris は最適化前の Nereids プランナーにフックを設け、解析済みプランをたどって各出力カラムの参照元を特定し、JOIN、FILTER、GROUP BY、WINDOW、CASE WHEN の依存関係を記録します。その後、クエリのスレッドとは別に、登録済みのすべての LineagePlugin にイベントを送信します。

1. プランナーにフックを登録する。 各書き込みコマンド（INSERT INTO、INSERT OVERWRITE、CTAS）は、解析済みプランを受け取るフックを登録します。フックは最適化前の解析済み LogicalPlan を取得するため、カラム参照には参照元のスロットが残り、リネージはユーザーが記述した SQL に対応します。
2. 直接リネージを抽出する。 LineageInfoExtractor はプランをたどり、各出力カラムを参照元の式まで追跡します。単純なカラム参照は IDENTITY、スカラー式は TRANSFORMATION、集約関数は AGGREGATION になります。CTE の参照側のスロットは定義側のスロットにあらかじめ解決されるため、WITH 句の境界で追跡が途切れません。
3. 間接リネージを抽出する。 JOIN キー、フィルター条件、GROUP BY のカラムは、すべての出力に影響するため、データセット単位の間接リネージとして記録されます。WindowExpression のパーティションキーと、CaseWhen、If、Coalesce の分岐は出力カラムごとに記録されるため、個々の値がその経路をたどった理由を追跡できます。
4. 非同期で送信する。 単一のワーカースレッドが、サイズに上限のあるキュー（lineage_event_queue_size、デフォルトは 50000）からイベントを取り出し、各イベントを有効なすべてのプラグインに順番に渡します。プラグインの処理はクエリのスレッド外で行われるため、下流システムが遅い場合に遅くなるのは、ユーザーが待っているクエリではなくキューの処理です。
5. 不要なものを除外する。 VALUES のみを使用する挿入と、__internal_schema を書き込み先とする操作は、抽出前に除外されます。不要なイベントのためにオプティマイザーがコストを負担することはありません。

書き込みを伴わないアドホックな SELECT クエリの場合は、もっと単純です。監査ログにクエリごとの参照元テーブルとマッチしたマテリアライズドビューがすでに記録されているため、そこからテーブル単位のリネージを導き出せます。

クイックスタート

-- 1. Enable the audit plugin so query-level lineage is recorded.
SET GLOBAL enable_audit_plugin = true;

-- 2. Run a query that joins two base tables.
SELECT n.n_name, SUM(o.o_totalprice)
FROM orders o JOIN nation n ON o.o_custkey = n.n_nationkey
GROUP BY n.n_name;

-- 3. Read the lineage out of the audit log.
SELECT time, queried_tables_and_views, chosen_m_views, stmt_id
FROM   internal.__internal_schema.audit_log
WHERE  user = CURRENT_USER() AND is_query = 1
ORDER  BY time DESC LIMIT 5;

想定される結果

+---------------------+--------------------------------------------+----------------+
| time                | queried_tables_and_views                   | chosen_m_views |
+---------------------+--------------------------------------------+----------------+
| 2026-05-09 10:14:22 | ["internal.tpch.orders","internal.tpch.    | []             |
|                     |  nation"]                                  |                |
+---------------------+--------------------------------------------+----------------+

この行には、カタログ名付きのテーブル名と、オプティマイザーが書き換えに使用した MV が含まれます。アドホッククエリのテーブル単位のグラフを描くには、これで十分です。書き込みのカラム単位のリネージを取得するには、LineagePlugin を実装し、その jar を plugin_dir/lineage/ に配置して、プラグイン名を activate_lineage_plugin に追加します。以後、すべての INSERT と CTAS で LineageInfo イベントが生成されます。

Apache Doris のデータリネージを使う場面

Apache Doris のデータリネージは、変更の影響分析、コンプライアンスのための追跡、MV のガバナンス、外部カタログ（Atlas、DataHub、OpenMetadata）へのカラム単位のイベント送信に適しています。組み込みのリネージ閲覧機能はなく、書き込みを伴わない SELECT クエリについてはカラム単位のリネージを取得できません。

適している場面

• スキーマ変更の影響分析。「orders.o_discount を削除すると、下流のどのテーブルとカラムに影響が出るか」という問いには、カラムごとの参照元の式が答えを示します。
• 規制対象テーブルへの一定期間内のすべての読み取りを示す必要がある監査やコンプライアンスのための追跡。監査ログには、クエリごとのテーブル一覧に加え、ユーザー、時刻、SQL が記録されます。
• マテリアライズドビューのガバナンス。監査ログの chosen_m_views と非同期マテリアライズドビューを組み合わせると、実際にトラフィックを処理している MV と、使われていない MV を見分けられます。
• OpenLineage イベントを送信する LineagePlugin を使い、カラム単位のリネージを外部のメタデータカタログ（Apache Atlas、DataHub、OpenMetadata、社内サービス）に提供する場合。
• Doris が共有カタログに書き込む複数の生成側システムの一つである場合の、エンジンをまたぐリネージ。

適していない場面

• 組み込みのリネージ閲覧画面が必要な場合。Doris はイベントを送信します。可視化はガバナンスツールが担います。ガバナンス基盤がない状態ですぐにグラフが必要なら、DataHub または Marquez をデプロイし、プラグインからそこに送信してください。
• 書き込みを伴わない SELECT クエリのリネージが必要な場合。Nereids の抽出処理が動作するのは、INSERT、INSERT OVERWRITE、CTAS に限られます。読み取り専用のクエリについては、監査ログの queried_tables_and_views 配列を使ってテーブル単位で追跡してください。
• Doris を一切経由しないシステム間のリネージが必要な場合。プラグインが認識するのは Doris 側のクエリです。Spark ジョブが Parquet を書き込み、後から Doris が読み取る場合は、Spark 側の計測（たとえば OpenLineage の Spark 連携）が必要です。二つのイベントの流れはカタログ内で統合されます。
• 正本となるメタデータを Doris 内に保存したい場合。リネージイベントは送信されますが、Doris 内には保持されません。選択したカタログに保存してください。
• __internal_schema を書き込み先とする操作や、VALUES のみを使用する挿入。これらは設計上除外され、リネージイベントを生成しません。

関連資料

• audit_log システムテーブル: テーブル単位のリネージを照会するための queried_tables_and_views 配列と chosen_m_views 配列を含む、すべてのカラムの説明です。
• 監査ログプラグイン: enable_audit_plugin の有効化、バッチ間隔と SQL の長さの設定、内部ユーザーの除外方法を説明します。
• 非同期マテリアライズドビュー: 書き換えの判断が chosen_m_views に現れるエンジンと、MTMVRelationManager が追跡するベーステーブルへの依存関係を説明します。
• 増分マテリアライズドビュー: 書き込み経路のカラム単位のリネージを補完する、MV とベーステーブル間のパーティション単位の依存関係の追跡を説明します。
• OpenLineage の仕様: カラム単位のリネージイベントのオープン標準です。LineagePlugin 実装の送信先スキーマとして利用できます。
• レイクテーブルの管理: Iceberg、Paimon、Hive への書き込みでもリネージイベントが生成されます。このページでは関連する書き込み経路を説明します。
• Apache Atlas の概要: 現在 OpenLineage を受け取り、カラム単位のグラフを表示できる一般的な送信先です。
• Iceberg: スナップショット履歴が Doris 内部テーブルとともにリネージグラフに反映される、外部テーブル形式です。