외부 계보¶

외부 계보 워크플로¶

데이터 도구에 대한 외부 계보 구현은 다음 작업으로 구성됩니다.

1. 외부 계보 엔드포인트에 인증하는 사용자에게 :ref:`필요한 권한을 부여<label-external_lineage_privilege>`합니다.

2. :ref:`데이터 도구를 구성<label-external_lineage_configure>`하여 OpenLineage 이벤트를 Snowflake REST 엔드포인트로 전송합니다.

3. Snowflake REST APIs에 적합한 :ref:`인증 방법을 선택<label-external_lineage_auth>`한 후 외부 계보 엔드포인트에 대한 요청을 인증하는 데 사용하도록 데이터 도구를 구성합니다.

4. 평소처럼 데이터 도구를 사용합니다. OpenLineage 이벤트는 자동으로 Snowflake로 전송되고 |sf-web-interface|의 네이티브 계보 그래프에 표시됩니다.

OpenLineage 이벤트를 내보내도록 데이터 도구를 구성하기 전에 외부 계보 엔드포인트를 테스트하려는 경우 계보 설정을 위한 수동 요청 전송하기 섹션을 참조하세요.

데이터 계보 보기¶

|sf-web-interface|에서 데이터 계보를 보려면 다음 단계를 완료합니다.

1. Snowsight 필수 권한 :ref:`<label-lineage_privileges> 으로 ` 에 로그인합니다.

2. 탐색 메뉴에서 Catalog » :ui:`Database Explorer`를 선택한 다음, :ref:`지원되는 오브젝트<label-ui_lineage_supported_objects>`(예: 테이블 또는 뷰)를 선택합니다.

3. Lineage 탭을 선택합니다.

데이터 도구가 계보 정보를 Snowflake로 전송하면 외부 오브젝트가 Snowsight 계보 그래프에 표시되며 외부 노드로 레이블이 지정됩니다. 예:

외부 오브젝트 또는 오브젝트를 연결하는 선을 선택하여 네이티브 계보에서와 마찬가지로 추가 정보를 얻을 수 있습니다.

Snowflake 권한 부여하기¶

REST 요청이 :ref:`인증<label-external_lineage_auth>`되면 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는 외부 계보에서 사용하는 것과 같은 Snowflake REST 엔드포인트에 대한 요청을 인증하는 여러 가지 방법을 제공합니다. 인증 방법의 전체 목록은 Snowflake를 사용하여 Snowflake REST APIs 인증하기 섹션을 참조하세요.

원하는 인증 방법을 선택한 후 특정 사용자에 대한 보안 토큰을 생성해야 합니다. 토큰은 Snowflake가 사용자를 인증하고 사용자에게 :ref:`외부 계보를 사용할 수 있는 권한이 부여<label-external_lineage_privilege>`되었는지 확인할 수 있도록 사용자와 REST 요청을 연결하는 데 사용됩니다.

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

여기서 :samp:`{account_identifier}`는 Snowflake 계정의 :doc:`계정 식별자</user-guide/admin-account-identifier>`입니다.

다음 예제에서는 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 쿼리 매개 변수를 사용하여 두 오브젝트에 대한 세부 정보를 지정합니다.

• 오브젝트 및 모든 해당 다운스트림 오브젝트 간의 계보를 끊으려면 대상 오브젝트를 지정하지 않고 소스 오브젝트를 지정합니다.

• 업스트림의 오브젝트 수와 관계없이 계보 그래프에서 대상 오브젝트를 제거하려면 소스 오브젝트를 지정하지 않고 대상 오브젝트를 지정합니다.

계보를 제거하기 위한 유효한 요청은 기본 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 함수의 출력에 표시되지 않습니다.

• 외부 계보는 열의 계보를 지원하지 않습니다.

• 데이터 세트의 정규화된 이름(즉, 입력 또는 출력)은 1,000자를 초과할 수 없습니다.

• 같은 계정에 10,000개 이상의 이벤트를 저장할 수 없습니다. 이 제한에 도달하면 새 이벤트를 추가하기 전에 이벤트를 삭제해야 합니다.