GET_LINEAGE
GET_LINEAGE (SNOWFLAKE.CORE)
Enterprise Edition 기능
이 기능은 Enterprise Edition(이상)이 필요해요. 업그레이드 문의는 Snowflake 지원팀에 연락하세요.
Snowflake 객체가 주어지면, 그 객체의 상위(upstream) 또는 하위(downstream) 데이터 계보(lineage) 정보를 반환해요. 상위란 객체 생성으로 이어진 객체들의 경로를, 하위란 객체로부터 생성된 객체들의 경로를 의미해요.
본문
구문
SNOWFLAKE.CORE.GET_LINEAGE(
'<object_name>',
'<object_domain>',
'<direction>',
[ <max_distance>, ]
[ '<object_version>', ]
[ '<namespace>', ]
[ '<object_type>', ]
[ '<external_id>', ]
[ '<column_name>' ]
)
인자
필수:
'object_name'
- 데이터 계보 정보를 가져오는 객체의 이름이에요. 객체가 세션의 현재 스키마와 다른 스키마에 있으면 완전히 한정된 이름을 사용하세요.
'object_domain'
- 객체의 도메인이에요. 지원되는 도메인은 'COLUMN', 'TABLE'(뷰와 동적 테이블을 포함한 모든 테이블류 객체 포함), 'SEMANTIC_VIEW'(시맨틱 뷰용), 'STAGE', 'CORTEX_AGENT'(Cortex Agent용)예요. 에이전트는 'CORTEX_AGENT'로 지정하세요. 객체 타입이 Snowsight에서 Agent로 표시되더라도 'AGENT'는 유효한 도메인이 아니에요. ML 계보에는 피처 뷰(내부적으로 동적 테이블과 뷰)에는 TABLE을, 'DATASET', 모델에는 'MODULE'을 사용해요. Snowflake에 없는 객체의 계보를 가져오려면 'EXTERNAL'을, 그런 객체의 열에는 'EXTERNAL_COLUMN'을 사용해요. 둘 다 namespace 인자가 필요해요. 자세한 내용은 Snowflake 밖 객체의 계보 문서를 참고하세요.
'direction'
- 계보를 유지할 방향이에요. 지원되는 방향은 'UPSTREAM'과 'DOWNSTREAM'이에요.
선택:
max_distance
- 가져올 계보의 수준 개수예요. 최대값은 5이며, 이것이 기본값이기도 해요.
'object_version'
- 데이터셋·모델 같은 버전 있는 객체의 경우, 계보를 가져올 객체의 버전이에요. 지정하지 않으면 기본 버전이 사용돼요.
'namespace'
- 객체의 네임스페이스로, 객체가 속한 시스템을 식별해요. object_domain이 'EXTERNAL' 또는 'EXTERNAL_COLUMN'일 때 필요하며, 다른 도메인에서는 유효하지 않아요.
'object_type'
- 데이터 카탈로그가 할당하는 타입처럼, 네임스페이스 안에서 객체의 구체적 타입이에요. object_domain이 'EXTERNAL' 또는 'EXTERNAL_COLUMN'일 때만 유효해요.
'external_id'
- 원래 시스템이 객체에 할당한 식별자예요. object_domain이 'EXTERNAL' 또는 'EXTERNAL_COLUMN'일 때만 유효해요.
'column_name'
- 계보를 가져올 열의 이름이에요. object_domain이 'EXTERNAL_COLUMN'일 때 필요하며, 다른 도메인에서는 유효하지 않아요.
출력
출력은 계보 경로의 객체 관계 각각에 대해 한 행(즉, 계보 그래프의 간선 하나)을 가지는 테이블이에요. 관계는 각 행에서 source와 target으로 지정된 객체 사이에 존재해요. 테이블에는 다음 열이 포함돼요.
| Column | Type | Description |
|---|---|---|
| SOURCE_OBJECT_DATABASE | VARCHAR | 원본 객체를 포함한 데이터베이스. |
| SOURCE_OBJECT_SCHEMA | VARCHAR | 원본 객체를 포함한 스키마. |
| SOURCE_OBJECT_NAME | VARCHAR | 원본 객체의 한정되지 않은 이름. |
| SOURCE_OBJECT_DOMAIN | VARCHAR | 원본 객체의 도메인. 가능한 값은 'COLUMN', 'TABLE', 'SEMANTIC_VIEW', 'DATASET', 'MODULE'(ML 모델), 'STAGE', 'CORTEX_AGENT'. |
| SOURCE_OBJECT_VERSION | VARCHAR | 데이터셋·모델 같은 버전 있는 객체의 원본 객체 버전. 버전 없는 객체면 NULL. |
| SOURCE_COLUMN_NAME | VARCHAR | 원본 객체가 열이면 원본 열 이름. 원본 객체가 열이 아니면 NULL. |
| SOURCE_STATUS | VARCHAR | 원본 객체의 상태. 가능한 값은 'ACTIVE'와 'MASKED'. |
| TARGET_OBJECT_DATABASE | VARCHAR | 대상 객체를 포함한 데이터베이스. |
| TARGET_OBJECT_SCHEMA | VARCHAR | 대상 객체를 포함한 스키마. |
| TARGET_OBJECT_NAME | VARCHAR | 대상 객체의 한정되지 않은 이름. |
| TARGET_OBJECT_DOMAIN | VARCHAR | 대상 객체의 도메인. 가능한 값은 'COLUMN', 'TABLE', 'SEMANTIC_VIEW', 'DATASET', 'MODULE'(ML 모델), 'STAGE', 'CORTEX_AGENT'. |
| TARGET_OBJECT_VERSION | VARCHAR | 데이터셋·모델 같은 버전 있는 객체의 대상 객체 버전. 버전 없는 객체면 NULL. |
| TARGET_COLUMN_NAME | VARCHAR | 대상 객체가 열이면 대상 열 이름. 대상 객체가 열이 아니면 NULL. |
| TARGET_STATUS | VARCHAR | 대상 객체의 상태. 가능한 값은 'ACTIVE'와 'MASKED'. |
| DISTANCE | INTEGER | 계보 경로에서 원본 객체로부터 대상 객체까지의 거리. 직접 관계는 거리 1. |
| PROCESS | VARIANT | 원본 객체와 대상 객체 사이에 계보가 어떻게 설정되었는지에 대한 세부 정보. 예를 들어 데이터를 원본 객체에서 대상 객체로 옮긴 SQL 쿼리의 쿼리 ID나 저장 프로시저 이름을 포함할 수 있음. |
| SOURCE_DETAILS | VARIANT | 원본 객체에 대한 추가 세부 정보. Object details 참고. |
| TARGET_DETAILS | VARIANT | 대상 객체에 대한 추가 세부 정보. Object details 참고. |
Object details
SOURCE_DETAILS와 TARGET_DETAILS 열은 계보 경로의 모든 객체에 대해 채워져요. 주어진 객체에 대해 값이 없는 키는 생략돼요. 각 열에는 다음 키가 포함돼요.
| Key | Description |
|---|---|
| dataset_type | 객체의 구체적 타입. SOURCE_OBJECT_DOMAIN과 TARGET_OBJECT_DOMAIN보다 더 세분화됨. 예를 들어 TABLE 도메인의 객체는 dataset_type이 TABLE 또는 VIEW일 수 있음. |
| origin | 객체 계보가 어디서 왔는지: Snowflake 객체는 NATIVE, 외부 소스에서 수집된 객체는 OPEN_LINEAGE. |
| namespace | 객체의 네임스페이스. Snowflake 객체가 아닌 객체에 존재. |
| external_id | 객체가 유래한 시스템에서의 객체 식별자. Snowflake 객체가 아닌 객체에 존재. |
사용 시 참고 사항
- 객체가 존재하지 않거나, 현재 사용자가 객체에 접근할 수 없거나, 객체가 데이터 계보를 지원하지 않거나, 객체가 지정한 도메인에 없으면 오류 메시지를 받아요.
- 지정한 객체에 대한 계보 정보가 없으면 출력 테이블에 행이 없어요. 이는 오류가 아니에요.
- GET_LINEAGE는 최대 1000만 행을 반환하며, 각 행은 계보 그래프의 간선(관계) 하나를 나타내요. 출력에 1000만 행이 넘으면 함수는 출력을 1000만 행으로 조용히 자릅니다.
- 인자를 위치 또는 이름으로 지정할 수 있지만, 같은 호출에서 둘 다는 사용할 수 없어요. 이름 있는 인자 사용 예시는 이름으로 인자 전달하기 섹션을 참고하세요.
- 이 함수 사용에 적용되는 제한 사항과 고려 사항은 계보 제한 사항과 고려 사항 문서를 참고하세요.
예시
CREATE TABLE AS SELECT를 사용해 TABLE_A로부터 TABLE_B라는 테이블을 만들고, 비슷한 방식으로 TABLE_B로부터 TABLE_C라는 테이블을 만들었다고 가정해요. 다음 SQL 쿼리는 TABLE_A로부터 하위 계보 두 단계를 가져와요.
SELECT
DISTANCE,
SOURCE_OBJECT_DOMAIN,
SOURCE_OBJECT_DATABASE,
SOURCE_OBJECT_SCHEMA,
SOURCE_OBJECT_NAME,
SOURCE_STATUS,
TARGET_OBJECT_DOMAIN,
TARGET_OBJECT_DATABASE,
TARGET_OBJECT_SCHEMA,
TARGET_OBJECT_NAME,
TARGET_STATUS,
FROM TABLE (SNOWFLAKE.CORE.GET_LINEAGE('my_database.sch.table_a', 'TABLE', 'DOWNSTREAM', 2));
출력은 다음과 비슷해요.
+----------+----------------------+------------------------+----------------------+--------------------+---------------+----------------------+------------------------+----------------------+--------------------+---------------+
| DISTANCE | SOURCE_OBJECT_DOMAIN | SOURCE_OBJECT_DATABASE | SOURCE_OBJECT_SCHEMA | SOURCE_OBJECT_NAME | SOURCE_STATUS | TARGET_OBJECT_DOMAIN | TARGET_OBJECT_DATABASE | TARGET_OBJECT_SCHEMA | TARGET_OBJECT_NAME | TARGET_STATUS |
|----------+----------------------+------------------------+----------------------+--------------------+---------------+----------------------+------------------------+----------------------+--------------------+---------------|
| 1 | TABLE | MY_DATABASE | SCH | TABLE_A | ACTIVE | TABLE | MY_DATABASE | SCH | TABLE_B | ACTIVE |
| 2 | TABLE | MY_DATABASE | SCH | TABLE_B | ACTIVE | TABLE | MY_DATABASE | SCH | TABLE_C | ACTIVE |
+----------+----------------------+------------------------+----------------------+--------------------+---------------+----------------------+------------------------+----------------------+--------------------+---------------+
이름으로 인자 전달하기
위치가 아닌 이름으로 인자를 전달할 수 있어요. 그러면 필요 없는 선택 인자를 생략할 수 있어요. 다음 쿼리는 앞의 예시와 같은 계보를 반환해요.
SELECT
DISTANCE,
SOURCE_OBJECT_NAME,
TARGET_OBJECT_NAME
FROM TABLE (SNOWFLAKE.CORE.GET_LINEAGE(
object_name => 'my_database.sch.table_a',
object_domain => 'TABLE',
direction => 'DOWNSTREAM',
max_distance => 2));
Snowflake 밖 객체의 계보
계보는 Snowflake의 객체로 제한되지 않아요. 외부 시스템에서 계보를 캡처하는 방법에 대한 정보는 External lineage 문서를 참고하세요.
해당 계보가 계정에 수집된 후에는 GET_LINEAGE가 그것을 Snowflake 계보와 함께 보고해요.
- Snowflake 밖의 객체가 출력에 나타나요. Snowflake 객체에서 시작한 계보 경로는 Snowflake에 없는 객체까지 이어질 수 있어요. SOURCE_DETAILS와 TARGET_DETAILS 열이 이런 객체를 식별하며, 이들의 origin 키가 Snowflake 객체와 구분해 줘요. Object details 참고.
- Snowflake 밖의 객체에서 시작할 수 있어요. object_domain을 'EXTERNAL'(그 열 중 하나면 'EXTERNAL_COLUMN')로 설정하고 객체 이름과 함께 객체의 네임스페이스를 전달해요. 이는 외부 객체가 어떤 Snowflake 객체에 데이터를 공급하는지, 또는 무엇이 그 객체에 공급하는지 추적하는 데 유용해요.
- 외부 객체의 사슬은 단계마다 쿼리가 하나씩 필요해요. 계보는 한 외부 객체에서 다른 객체로 이어질 수 있어요. 예를 들어 Snowflake 테이블에서 외부 객체로, 그리고 두 번째 외부 객체로 이어질 수 있어요. 그런 사슬의 다음 단계를 가져오려면 도달한 외부 객체를 기준으로 두 번째 쿼리를 실행하세요.
Snowflake에 없는 객체의 경우 SOURCE_OBJECT_DATABASE와 SOURCE_OBJECT_SCHEMA(및 그 대상 이름 표현)는 NULL이고, 객체의 도메인은 'EXTERNAL' 또는 'EXTERNAL_COLUMN'으로 보고돼요.
예시: Snowflake 밖의 객체에 도달하기
TABLE_A가 파일로 내보내졌고 그 내보내기의 계보가 계정에 수집되었다고 가정해요. 다음 쿼리는 TABLE_A의 하위 계보를 가져오며, 각 대상의 네임스페이스와 origin을 TARGET_DETAILS에서 추출해요.
SELECT
DISTANCE,
SOURCE_OBJECT_NAME,
TARGET_OBJECT_DOMAIN,
TARGET_OBJECT_NAME,
TARGET_DETAILS:namespace::VARCHAR AS TARGET_NAMESPACE,
TARGET_DETAILS:origin::VARCHAR AS TARGET_ORIGIN
FROM TABLE (SNOWFLAKE.CORE.GET_LINEAGE(
object_name => 'my_database.sch.table_a',
object_domain => 'TABLE',
direction => 'DOWNSTREAM',
max_distance => 1));
출력은 다음과 비슷하며, 대상이 Snowflake 객체가 아니므로 대상의 데이터베이스·스키마 열이 NULL이에요.
+----------+--------------------+----------------------+--------------------+------------------------+---------------+
| DISTANCE | SOURCE_OBJECT_NAME | TARGET_OBJECT_DOMAIN | TARGET_OBJECT_NAME | TARGET_NAMESPACE | TARGET_ORIGIN |
|----------+--------------------+----------------------+--------------------+------------------------+---------------|
| 1 | TABLE_A | EXTERNAL | out/daily.parquet | s3://analytics-exports | OPEN_LINEAGE |
+----------+--------------------+----------------------+--------------------+------------------------+---------------+
예시: Snowflake 밖의 객체에서 이어가기
앞의 예시에서 도달한 파일의 계보를 가져오려면 그 파일을 기준으로 삼아 object_domain을 'EXTERNAL'로 설정하고 이름과 함께 네임스페이스를 전달해요. 이 패턴을 반복해서 외부 객체의 사슬을 한 단계씩 따라갈 수 있어요.
SELECT
DISTANCE,
SOURCE_OBJECT_NAME,
TARGET_OBJECT_DOMAIN,
TARGET_OBJECT_NAME
FROM TABLE (SNOWFLAKE.CORE.GET_LINEAGE(
object_name => 'out/daily.parquet',
object_domain => 'EXTERNAL',
direction => 'DOWNSTREAM',
max_distance => 1,
namespace => 's3://analytics-exports'));
더 알아보기
- Table functions — 테이블 함수 모음