外部リネージ¶

外部リネージワークフロー¶

データツールの外部リネージの実装は以下のタスクで構成されます。

1. 外部リネージエンドポイントで認証するユーザーに対して 必要な権限の付与します 。

2. OpenLineageイベントをSnowflakeRESTエンドポイントに送信するために データツールを構成します 。

3. Snowflake REST APIsに対して動作する 認証方法を選択 を選択し、次に、外部リネージエンドポイントへのリクエストを認証するためにそれを使用するようにデータツールを構成します。

4. 通常どおりデータツールを使用します。OpenLineageイベントは自動的にSnowflakeに送信され、 Snowsight のネイティブリネージグラフに表示されます。

OpenLineageイベントを出力するデータツールを構成する前に、外部リネージエンドポイントをテストしたい場合、 手動リクエストを送信してリネージを確立する をご参照ください。

データリネージを表示する¶

Snowsight でデータリネージを表示するにはの場合は、次の手順を完了します。

1. :ref:`に必要な権限 <label-lineage_privileges>`で|sf-web-interface-link| にサインインします。

2. ナビゲーションメニューで、Catalog » Database Explorer`を選択し、次にテーブルやビューなど :ref:`サポートされるオブジェクト <label-ui_lineage_supported_objects> を選択します。

3. Lineage タブを選択します。

データツールがSnowflakeにリネージ情報を送信すると、外部オブジェクトが Snowsight リネージグラフに表示され、外部ノードとしてラベル付けされます。例:

外部オブジェクトやオブジェクトを接続しているラインを選択すると、ネイティブリネージの場合と同様に追加情報を取得できます。

Snowflake権限を付与する¶

RESTリクエストが 認証された 後、Snowflakeは、リクエストに関連付けられたユーザーが外部リネージの使用を承認されているかどうかを確認します。リクエストに関連付けられたユーザーは、アカウントに対するINGEST LINEAGE権限を付与されたロールを持っている必要があります。

例えば、サービスユーザー dbt_integration_user から送信されたリクエストを Snowsight リネージに表示したい場合を考えます。管理者として、以下のコマンドを実行して専用ロールを作成し、必要な権限を付与し、そのロールをユーザーに付与します。

CREATE ROLE dbt_lineage_role;
GRANT INGEST LINEAGE ON ACCOUNT TO ROLE dbt_lineage_role;
GRANT ROLE dbt_lineage_role TO USER dbt_integration_user;

データツールを構成する¶

以下のセクションでは、dbtとApache AirFlowで外部リネージを使用するための基本的な手順を説明します。

• リネージデータをSnowflakeに送信するようにdbtを構成する

• リネージデータをSnowflakeに送信するようにAirflowを構成する

認証方法を選択する¶

Snowflakeは、外部リネージで使用されるものと同様に、SnowflakeRESTエンドポイントへのリクエストを認証する複数の方法を提供します。認証方法の完全なリストについては、 Snowflakeでの Snowflake REST APIs 認証 をご参照ください。

希望する認証方法を選択した後、特定のユーザーのセキュリティトークンを生成する必要があります。トークンは、ユーザーをRESTリクエストに関連付けるために使用され、Snowflakeがユーザーを認証し、ユーザーが 外部リネージの使用を許可済み であることを確認できるようにします。

Snowflakeでセキュリティトークンにユーザーを正常に関連付けた後、このトークンでリクエストを認証するようにデータツールを構成する必要があります。例えば、YAML構成ファイルを使用してOpenLineageトランスポート変数を設定する場合は、次のコードを使用して、リクエストの ヘッダーで送信されるセキュリティトークンを指定します。

transport:
   auth:
      type: api_key
      apiKey: eyJ0eXAiOiJKV1QiLsecuritytoken...

セキュリティトークンを指定する他の方法については、データツールのOpenLineageドキュメントをご参照ください。

手動リクエストを送信してリネージを確立する¶

外部リネージは、COMPLETEイベントのOpenLineageに準拠するJSONペイロード仕様を受け入れることで機能します。データツールと統合すると、ツールはこれらのCOMPLETEイベントを出力します。ただし、COMPLETEイベントを構築し、エンドポイントにPOSTリクエストを送信できるツールまたは言語を使用して、エンドポイントに送信することもできます。

有効なリクエストは、次のメソッド、 ベースURL 、および エンドポイント で構成されます。

POST https://<account_identifier>.snowflakecomputing.com/api/v2/lineage/external-lineage

ここで、 account_identifier はSnowflakeアカウントの アカウント識別子 です。

次の例は、curlを使用してリネージ情報を外部リネージに送信する方法を示しています。

curl -i -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLsecuritytoken..." \
 -H "Accept: application/json" \
 -H "User-Agent: myApplicationName/1.0" \
 -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
 -d "@request_body.json" \
 "https://MYORG-DEV_ACCOUNT.snowflakecomputing.com/api/v2/lineage/external-lineage"

ここで、 request_body.json はCOMPLETEイベントのOpenLineage仕様に準拠します。このJSONペイロードの詳細については、 ペイロード要件 をご参照ください。

{
   "eventType": "COMPLETE",
   "eventTime": "2025-03-12T06:51:12.000Z",
   "job": {"namespace": "exampleNamespace", "name": "exampleJob"},
   "run": {"runId": "123e4567-e89b-12d3-a456-426614174000"},
   "producer": "https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client",
   "schemaURL": "https://openlineage.io/spec/0-0-1/OpenLineage.json",
   "inputs": [{"namespace": "snowflake://AXORG-AX_TEST_PP8", "name": "OL_TEST.OL_TEST_SCH.TEST_DEMO"}],
   "outputs": [{"namespace": "postgres://localhost:5432", "name": "PDB.SCH.OUTPUT"}]
}

"outputs": [
    {
        "namespace": "postgres://db.company.com:5432",
        "name": "db.schema.view",
        "facets": {"datasetType": {"datasetType": "VIEW"}},
    },
],

リネージの削除をリクエストする¶

Snowflakeオブジェクトと外部オブジェクトの間に確立されたリネージを削除するために、外部リネージエンドポイントにDELETEリクエストを送信できます。

• ソースオブジェクトとターゲットオブジェクト間のリネージを分けるには、URLクエリパラメーターを使用して、2つのオブジェクトに関する詳細を指定します。

• オブジェクトとその下流のすべてのオブジェクトの間でリネージを分割するには、ターゲットオブジェクトを指定せずにソースオブジェクトを指定します。

• 上流にあるオブジェクトの数に関係なく、リネージグラフからターゲットオブジェクトを削除するには、ソースオブジェクトを指定せずにターゲットオブジェクトを指定します。

リネージを削除する有効なリクエストは、次のメソッド、 ベースURL 、および エンドポイント で構成されます。

DELETE https://<account_identifier>.snowflakecomputing.com/api/v2/lineage/external-lineage

制限と考慮事項¶

• Snowflakeオブジェクトは、COMPLETEイベントのINPUTまたはOUTPUTのいずれかである必要があります。つまり、入力データも出力データもSnowflakeオブジェクトでない場合、外部リネージイベントはリネージイベントをインジェストしません。

• SnowflakeはOpenLineageバージョン2をサポートしていません。

• 外部リネージイベントの保持期間は1年間です。

• SnowflakeはCOMPLETEリネージイベントのみを認識します。データツールによって発行された他のすべてのイベントは無視されます。

• 外部ソースのリネージは、GET_LINEAGE関数の出力に表示されません。

• 外部リネージは列のリネージをサポートしていません。

• データセットの完全修飾名 --- つまり、入力または出力 --- は1000文字を超えることはできません。

• 同じアカウントに10,000個を超えるイベントを保存することはできません。この制限に達すると、新しいイベントを追加する前にイベントを削除する必要があります。