테이블을 바꾸기 전에 어떤 데이터가 의존하는지 확인하세요. — Claude Skill

DataHub CLI 참조

DataHub CLI v1.4.0 기준으로 확인한 명령입니다. pip install acryl-datahub로 설치합니다.

---

도구 감지

DataHub 명령을 실행하기 전에 사용할 수 있는 도구를 확인합니다:

1. MCP 도구 사용 가능 — 도구 목록에 datahub_search, datahub_get_entity, datahub_get_lineage 같은 도구가 있으면 직접 사용합니다. CLI 설치가 필요 없는 우선 경로입니다.
2. CLI 사용 가능 — Bash 도구가 있다면 which datahub로 확인합니다. 있으면 아래에 문서화된 CLI 명령을 사용합니다.
3. 둘 다 없음 — 사용자에게 /datahub-setup을 사용해 DataHub 연결을 설정하도록 제안합니다.

둘 다 사용할 수 있으면 MCP가 CLI보다 우선입니다. MCP 도구는 에이전트 사용에 맞게 구조화된 입력/출력을 제공하고 셸 오버헤드가 없습니다.

CLI ↔ MCP 대응 관계

MCP 도구 이름에는 접두사가 붙을 수 있습니다(예: mcp__datahub-cloud__search). 전체 접두사 이름이 아니라 함수 이름 접미사로 맞춥니다. MCP 도구는 자체 문서화되어 있으므로 정적 문서에 의존하기보다 스키마에서 매개변수 세부 사항을 확인하세요.

이 문서의 나머지는 CLI 경로를 다룹니다.

---

인증

CLI는 ~/.datahubenv에서 연결 설정을 읽습니다:

gms:
  server: "http://localhost:8080"
  token: "<personal-access-token>"

또는 환경 변수를 사용할 수 있습니다:

export DATAHUB_GMS_URL="http://localhost:8080"
export DATAHUB_GMS_TOKEN="<token>"

---

버전 확인

명령 실행 전 설치된 CLI 버전을 확인합니다:

datahub version

스킬이 최소 버전을 요구하고 설치 버전이 더 오래되었다면 업그레이드합니다:

pip install --upgrade acryl-datahub --pre

--pre 플래그는 시험판 버전(예: 1.5.0rc1)도 포함하도록 하며, 새 기능에 필요할 수 있습니다.

서버 감지

DataHub Cloud에 연결되어 있는지 OSS에 연결되어 있는지 감지합니다:

datahub check server-config

• serverEnv: 'cloud' → DataHub Cloud(인기도 정렬, 데이터셋 기능 지원)
• serverEnv: 'core' 또는 기타 → OSS / 자체 호스팅(기능 필드 사용 불가)

이 결과는 세션 동안 캐시하세요. 매 명령마다 다시 확인하지 않습니다. 아래에서 **(Cloud only)**로 표시된 일부 기능은 serverEnv: cloud가 필요합니다.

컨텍스트

CLI 명령에 -C key=value를 사용해 컨텍스트를 전달하면 명령을 서로 연결해 볼 수 있습니다:

datahub -C skill=datahub-audit search "revenue"
datahub -C skill=datahub-audit -C caller=claude-code get --urn "..."

-C 플래그는 루트 datahub 명령에 둡니다(하위 명령 앞). skill 값에는 해당 스킬의 YAML frontmatter에 있는 이름을 사용합니다. 플래그가 인식되지 않으면 생략하세요. 명령은 동일하게 동작합니다.

---

검색 및 탐색

검색 CLI는 위치 인수로 질의를 받습니다. --query가 아닙니다.

# 기본 키워드 검색
datahub search "revenue"

# 제한 개수로 검색
datahub search "customers" --limit 20

# 플랫폼으로 필터링(단순 필터)
datahub search "*" --filter platform=snowflake

# 엔터티 유형으로 필터링
datahub search "*" --where "entity_type = dataset"

# SQL 유사 WHERE 표현식(에이전트에 권장)
datahub search "*" --where "platform = snowflake AND env = PROD"
datahub search "*" --where "platform IN (snowflake, bigquery)"
datahub search "*" --where "entity_type = dataset AND platform = snowflake"

# 여러 단순 필터(필드 사이는 AND, 쉼표는 필드 안의 OR)
datahub search "*" --filter platform=snowflake --filter env=PROD
datahub search "*" --filter platform=snowflake,bigquery

# 출력 형식
datahub search "revenue" --table          # 사람이 읽기 쉬운 표
datahub search "revenue" --urns-only      # URN만 한 줄에 하나씩
datahub search "revenue" --format json    # JSON(기본값)

# 페이지네이션(페이지당 최대 50개)
datahub search "customers" --limit 50 --offset 0     # 1페이지
datahub search "customers" --limit 50 --offset 50    # 2페이지

# 패싯만(유형/플랫폼별 개수 등)
datahub search "*" --facets-only --format json

# 드라이런(실행 전 질의 미리보기)
datahub search "revenue" --where "platform = snowflake" --dry-run

# Projection(반환 필드 제한 — 토큰 비용 절감)
datahub search "customers" --projection "urn type"

# 컬럼 수준 검색(특정 필드를 포함한 데이터셋 찾기)
datahub search "*" --where "entity_type = dataset AND fieldPaths = customer_id"

# 정렬
datahub search "*" --sort-by lastModifiedAt --sort-order desc --limit 10
datahub search "*" --sort-by _entityName --sort-order asc --limit 10

# 인기도 / 사용량 정렬(Cloud only — 먼저 serverEnv 확인)
# 가장 많이 질의된 데이터셋
datahub search "*" --where "entity_type = dataset" \
  --sort-by queryCountLast30DaysFeature --sort-order desc --limit 10 \
  --projection "urn type ... on Dataset { properties { name } platform { name } statsSummary { queryCountLast30Days uniqueUserCountLast30Days } }"

# 가장 많이 업데이트된 데이터셋
datahub search "*" --where "entity_type = dataset" --sort-by writeCountLast30DaysFeature --sort-order desc --limit 10

# 가장 큰 테이블(행 수 또는 바이트 기준)
datahub search "*" --where "entity_type = dataset" --sort-by rowCountFeature --sort-order desc --limit 10
datahub search "*" --where "entity_type = dataset" --sort-by sizeInBytesFeature --sort-order desc --limit 10

# 존재 필터(IS NULL / IS NOT NULL)
datahub search "*" --where "entity_type = dataset AND description IS NULL AND editableDescription IS NULL"
datahub search "*" --where "entity_type = dataset AND glossary_term IS NOT NULL"

# Sibling 인식 설명 감사(단일 질의, N+1 fetch 없음)
# 1단계: 수집 설명과 사용자 편집 설명이 모두 없는 데이터셋 찾기
# 2단계: sibling과 해당 설명을 projection해 실제 충족률 계산
datahub search "*" \
  --where "entity_type = dataset AND platform = snowflake AND description IS NULL AND editableDescription IS NULL" \
  --projection "urn type ... on Dataset { siblings { isPrimary siblings { urn ... on Dataset { properties { name description } editableProperties { description } } } } }" \
  --format json --limit 50

# 필터용 URN 해석
# tag, domain, glossary_term 필터에는 표시 이름이 아니라 전체 URN이 필요합니다.
# 항상 먼저 이름을 URN으로 해석한 뒤 필터에 URN을 사용하세요.

# 1단계: 이름으로 tag URN 찾기
datahub search "large table" --where "entity_type = tag" --urns-only --limit 1
# → urn:li:tag:sample_data___default_large_table

# 2단계: 필터에서 URN 사용
datahub search "*" --where "entity_type = dataset AND tags = 'urn:li:tag:sample_data___default_large_table'"

# domain도 같은 패턴:
datahub search "ecommerce" --where "entity_type = domain" --urns-only --limit 1
# → urn:li:domain:91994180-...
datahub search "*" --where "entity_type = dataset AND domain = 'urn:li:domain:91994180-...'"

# glossary term도 동일:
datahub search "PII" --where "entity_type = glossaryTerm" --urns-only --limit 1
datahub search "*" --where "entity_type = dataset AND glossary_term = 'urn:li:glossaryTerm:...'"

# 사용 가능한 필터 발견
datahub search list-filters
datahub search describe-filter platform

# 에이전트 모범 사례
datahub search --agent-context

엔터티 가져오기

# 전체 엔터티 메타데이터 가져오기
datahub get --urn "urn:li:dataset:(urn:li:dataPlatform:hive,table_name,PROD)"

# 특정 aspect 가져오기
datahub get --urn "<URN>" --aspect schemaMetadata
datahub get --urn "<URN>" --aspect ownership
datahub get --urn "<URN>" --aspect globalTags

계보

# 상위 소스(기본적으로 전체 그래프)
datahub lineage --urn "<URN>" --direction upstream

# 하위 의존 대상
datahub lineage --urn "<URN>" --direction downstream

# 즉시 이웃으로 제한
datahub lineage --urn "<URN>" --direction upstream --hops 1

# 컬럼 수준 계보(데이터셋만)
datahub lineage --urn "<URN>" --column customer_id --direction upstream

# JSON 출력(제한/힌트 정보가 있는 메타데이터 포함)
datahub lineage --urn "<URN>" --direction downstream --format json

# 두 엔터티 사이의 경로 찾기
datahub lineage path --from "<URN_A>" --to "<URN_B>"

# 에이전트 모범 사례
datahub lineage --agent-context

타임라인(변경 이력)

# 스키마 변경
datahub timeline --urn "<URN>" --category technical_schema

# 소유권 변경
datahub timeline --urn "<URN>" --category owner

# 태그 변경
datahub timeline --urn "<URN>" --category tag

# 시간 범위 포함
datahub timeline --urn "<URN>" --category technical_schema --start 7daysago

카테고리: tag, glossary_term, technical_schema, documentation, owner

---

쓰기 작업(GraphQL Mutation 사용)

쓰기 작업은 datahub graphql --query 'mutation { ... }'을 사용합니다. CLI에는 이 작업을 위한 전용 tag, glossary, 인라인 put 명령이 없습니다.

GraphQL mutation의 중요 규칙:

• 반환 필드 하위 선택이 필요합니다. 객체를 반환하는 mutation(Boolean 같은 scalar가 아닌 경우)은 mutation 뒤에 { urn } 또는 유사한 선택이 필요합니다. 없으면 SubselectionRequired 오류가 납니다.
• 긴 질의는 임시 파일을 사용해야 합니다. 긴 인라인 --query 문자열은 macOS에서 파일 경로로 잘못 해석됩니다(File name too long). .graphql 파일에 쓰고 경로를 전달하세요: datahub graphql --query /tmp/my-mutation.graphql --format json.
• 짧은 mutation은 인라인 가능. addTag, removeTag, addOwner 같은 단순 mutation은 인라인으로 전달해도 충분히 짧습니다.

태그

# 태그 생성
# id 포함: 이름 기반 URN(사람이 읽기 쉬우나 ID는 불변 — 나중에 이름 변경 불가)
# id 없음: GUID 기반 URN(불투명하지만 표시 이름은 자유롭게 변경 가능)
# 확실하지 않으면 사용자에게 선호를 물어봅니다.
datahub graphql --query 'mutation {
  createTag(input: { id: "pii", name: "PII", description: "PII 데이터를 포함함" })
}' --format json
# → urn:li:tag:pii 반환

# 엔터티에 태그 추가(태그가 먼저 존재해야 함)
datahub graphql --query 'mutation {
  addTag(input: { tagUrn: "urn:li:tag:<TAG_URN>", resourceUrn: "<ENTITY_URN>" })
}' --format json

# 특정 필드에 태그 추가
datahub graphql --query 'mutation {
  addTag(input: {
    tagUrn: "urn:li:tag:<TAG_URN>",
    resourceUrn: "<ENTITY_URN>",
    subResourceType: DATASET_FIELD,
    subResource: "<FIELD_PATH>"
  })
}' --format json

# 태그 제거
datahub graphql --query 'mutation {
  removeTag(input: { tagUrn: "urn:li:tag:<TAG_URN>", resourceUrn: "<ENTITY_URN>" })
}' --format json

# 태그 일괄 추가
datahub graphql --query 'mutation {
  batchAddTags(input: {
    tagUrns: ["urn:li:tag:<TAG1>", "urn:li:tag:<TAG2>"],
    resources: [{ resourceUrn: "<URN1>" }, { resourceUrn: "<URN2>" }]
  })
}' --format json

용어집 용어

# 엔터티에 용어 추가
datahub graphql --query 'mutation {
  addTerm(input: { termUrn: "urn:li:glossaryTerm:<TERM>", resourceUrn: "<ENTITY_URN>" })
}' --format json

# 용어 제거
datahub graphql --query 'mutation {
  removeTerm(input: { termUrn: "urn:li:glossaryTerm:<TERM>", resourceUrn: "<ENTITY_URN>" })
}' --format json

소유권

# 소유자 추가(기존 소유자를 대체하지 않고 추가)
datahub graphql --query 'mutation {
  addOwner(input: {
    ownerUrn: "urn:li:corpuser:<USER>",
    resourceUrn: "<ENTITY_URN>",
    ownerEntityType: CORP_USER,
    type: TECHNICAL_OWNER
  })
}' --format json

# 소유자 제거
datahub graphql --query 'mutation {
  removeOwner(input: { ownerUrn: "urn:li:corpuser:<USER>", resourceUrn: "<ENTITY_URN>" })
}' --format json

# 소유자 일괄 추가
datahub graphql --query 'mutation {
  batchAddOwners(input: {
    owners: [{ ownerUrn: "urn:li:corpuser:<USER>", ownerEntityType: CORP_USER }],
    resources: [{ resourceUrn: "<URN1>" }, { resourceUrn: "<URN2>" }]
  })
}' --format json

소유자 유형: TECHNICAL_OWNER, BUSINESS_OWNER, DATA_STEWARD, NONE

폐기 처리

# 폐기 처리
datahub graphql --query 'mutation {
  updateDeprecation(input: { urn: "<URN>", deprecated: true, note: "new_table로 대체됨" })
}' --format json

# 폐기 해제
datahub graphql --query 'mutation {
  updateDeprecation(input: { urn: "<URN>", deprecated: false })
}' --format json

도메인

# 도메인 생성
datahub graphql --query 'mutation {
  createDomain(input: { name: "마케팅", description: "마케팅 데이터" })
}' --format json

# 엔터티를 도메인에 할당(도메인이 존재해야 함)
datahub graphql --query 'mutation {
  setDomain(entityUrn: "<ENTITY_URN>", domainUrn: "urn:li:domain:<DOMAIN_ID>")
}' --format json

# 도메인에서 제거
datahub graphql --query 'mutation {
  unsetDomain(entityUrn: "<ENTITY_URN>")
}' --format json

# 일괄 할당
datahub graphql --query 'mutation {
  batchSetDomain(input: {
    domainUrn: "urn:li:domain:<ID>",
    resources: [{ resourceUrn: "<URN1>" }, { resourceUrn: "<URN2>" }]
  })
}' --format json

설명

datahub graphql --query 'mutation {
  updateDescription(input: {
    description: "새 설명 텍스트",
    resourceUrn: "<ENTITY_URN>"
  })
}' --format json

데이터 제품

참고: domainUrn은 필수입니다. 모든 데이터 제품은 도메인에 속해야 합니다. 스키마를 확인하려면 datahub graphql --describe createDataProduct --recurse를 사용하세요.

# 생성(domainUrn은 필수)
datahub graphql --query 'mutation {
  createDataProduct(input: {
    domainUrn: "urn:li:domain:<DOMAIN_ID>",
    properties: { name: "매출 분석", description: "매출 파이프라인" }
  }) { urn }
}' --format json

# 데이터 제품에 자산 추가
datahub graphql --query 'mutation {
  batchSetDataProduct(input: {
    dataProductUrn: "urn:li:dataProduct:<ID>",
    resourceUrns: ["<URN1>", "<URN2>"]
  })
}' --format json

---

검증 및 상태

# CLI 버전 확인
datahub version

# 연결 확인(이 엔터티는 항상 존재)
datahub get --urn "urn:li:corpuser:datahub"

# 검색 테스트(검색 색인이 동작하는지 확인)
datahub search "*" --limit 1

# 서버 설정
datahub check server-config

참고: datahub check server-health는 존재하지 않습니다. 연결 확인에는 datahub get --urn "urn:li:corpuser:datahub"을 사용하세요.

---

GraphQL 탐색

# 사용 가능한 모든 작업 나열
datahub graphql --list-operations --format json

# mutation만 나열
datahub graphql --list-mutations --format json

# 특정 작업 설명
datahub graphql --describe addTag --format json

# 전체 유형 확장과 함께 설명
datahub graphql --describe addTag --recurse --format json

# 드라이런(실행 없이 미리보기)
datahub graphql --query '{ me { corpUser { urn } } }' --dry-run

# 에이전트 모범 사례
datahub graphql --agent-context

---

일괄 Mutation 패턴(Python)

데이터셋 URN에는 괄호가 포함되어 있어 셸 루프에서 따옴표 처리가 깨지기 쉽습니다. 여러 엔터티 mutation에는 임시 파일을 쓰는 Python 스크립트를 사용하세요:

import subprocess, json, tempfile, os

def run_graphql_mutation(query, variables):
    """임시 파일 변수로 GraphQL mutation을 실행합니다. 파싱된 JSON 또는 None을 반환합니다."""
    with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
        json.dump(variables, f)
        vf = f.name
    try:
        result = subprocess.run(
            ["datahub", "graphql", "-q", query, "-v", vf, "--format", "json", "--no-pretty"],
            capture_output=True, text=True
        )
        if result.returncode == 0:
            return json.loads(result.stdout)
        else:
            print(f"ERROR: {result.stderr.strip()[:120]}")
            return None
    finally:
        os.unlink(vf)

# 예시: 설명 일괄 업데이트
query = "mutation updateDataset($urn: String!, $input: DatasetUpdateInput!) { updateDataset(urn: $urn, input: $input) { urn } }"

datasets = {
    "urn:li:dataset:(urn:li:dataPlatform:snowflake,db.schema.table1,PROD)": "table1 설명",
    "urn:li:dataset:(urn:li:dataPlatform:snowflake,db.schema.table2,PROD)": "table2 설명",
}

for urn, desc in datasets.items():
    variables = {"urn": urn, "input": {"editableProperties": {"description": desc}}}
    result = run_graphql_mutation(query, variables)
    status = "OK" if result else "FAIL"
    print(f"  {urn.split(',')[1]}: {status}")

---

출력 처리

# 검색 URN을 get으로 파이프해 일괄 가져오기
datahub search "customers" --urns-only | xargs -I{} datahub get --urn {}

# 스키마에서 필드 이름 추출
datahub get --urn "<URN>" --aspect schemaMetadata | python3 -c "
import sys, json
data = json.load(sys.stdin)
for f in data.get('schemaMetadata', {}).get('fields', []):
    print(f['fieldPath'])
"

영향도 분석

대상 엔터티

이름: <!-- entity name --> URN: <!-- urn --> 플랫폼: <!-- platform --> 유형: <!-- dataset / dashboard / etc. -->

영향도 요약

직접 하위 의존 대상(1홉): <!-- count --> 전이 하위 의존 대상(전체 홉): <!-- count --> 추적 깊이: <!-- hops -->

영향받는 엔터티

유형별

플랫폼별

중요 경로

<!-- 대상에 대한 단일 상위 의존성을 가진 엔터티 -->

계보 그래프

<!-- ASCII 흐름도 -->

영향받는 소유자

권장 사항

1. <!-- 알림 조치 -->
2. <!-- 마이그레이션/업데이트 제안 -->

계보 지도

대상 엔터티

이름: <!-- entity name --> URN: <!-- urn -->

흐름도

<!-- ASCII 계보 다이어그램 -->

상위(소스)

하위(소비자)

플랫폼 간 경계

계보 패턴 참조

일반적인 계보 탐색 전략과 패턴입니다.

탐색 전략

영향도 분석(하위)

목표: 엔터티가 바뀌면 무엇이 깨지는지 판단합니다.

전략:

1. 모든 하위 엔터티를 가져옵니다(깊이 1부터 시작해 필요하면 확장)
2. 유형별로 분류합니다(데이터셋, 대시보드, 작업)
3. 중요 경로를 식별합니다(단일 상위 의존성을 가진 엔터티)
4. 알림 대상인 영향받는 소유자를 나열합니다

핵심 질문: "대체 데이터 소스가 없는 하위 엔터티는 무엇인가?"

근본 원인(상위)

목표: 데이터가 어디서 시작되고 어떻게 변환되는지 추적합니다.

전략:

1. 모든 상위 엔터티를 가져옵니다(깊이 1-3)
2. 원천 기록 시스템(데이터베이스, API, 파일)에 도달할 때까지 따라갑니다
3. 각 홉의 변환 유형을 기록합니다(TRANSFORMED, VIEW, COPY)
4. 원본 데이터 소스를 식별합니다

핵심 질문: "이 데이터는 궁극적으로 어디에서 오는가?"

전체 파이프라인(양방향)

목표: 소스부터 소비까지 전체 데이터 흐름을 매핑합니다.

전략:

1. 상위 방향으로 소스까지 가져옵니다(근본 원인)
2. 하위 방향으로 소비자까지 가져옵니다(영향도)
3. 하나의 방향성 그래프로 병합합니다
4. 끝에서 끝까지의 흐름으로 제시합니다

플랫폼 간 추적

목표: 시스템 사이에서 데이터가 어떻게 이동하는지 이해합니다.

전략:

1. 양방향으로 계보를 추적합니다
2. 엔터티를 플랫폼별로 그룹화합니다
3. 플랫폼 간 엣지를 식별합니다(예: dbt를 통한 PostgreSQL → Snowflake)
4. 통합 지점을 강조합니다

경로 찾기

목표: 엔터티 A가 엔터티 B와 연결되는지, 연결된다면 어떻게 연결되는지 판단합니다.

전략:

1. 엔터티 A에서 하위 방향 BFS를 시작합니다
2. 각 홉에서 엔터티 B가 나타나는지 확인합니다
3. 찾으면 경로를 반환합니다
4. 최대 깊이: 5홉(더 깊게 가기 전 사용자에게 확인)

계보 엣지 유형

플랫폼별 계보 참고 사항

올바른 명령 선택

계보 제한 사항

• 상위와 하위 탐색 모두에 datahub lineage를 사용합니다. --hops, --column, 메타데이터 힌트가 포함된 --format json을 지원합니다.
• 필터링이 필요하면 searchAcrossLineage를 사용합니다. datahub lineage는 필터를 지원하지 않습니다. 엔터티 유형, 플랫폼, 태그, 도메인, 시간 창으로 필터링하려면 datahub graphql을 통한 GraphQL 질의를 사용하세요.
• 깊이: 깊은 계보 그래프(5홉 이상)는 매우 커질 수 있습니다. 항상 제한을 두고 물어보세요.
• 오래된 정보: 계보는 마지막 수집 상태를 반영합니다. 최근 파이프라인 변경을 반영하지 않을 수 있습니다.
• 컬럼 수준: 모든 소스가 컬럼 수준 계보를 제공하지는 않습니다. 사용할 수 없으면 이를 명시하세요.

DataHub 데이터 계보

DataHub의 계보 그래프를 사용해 계보를 탐색하고, 데이터 의존성을 추적하고, 영향도 분석을 수행합니다.

하는 일

1. 대상 엔터티를 식별합니다
2. 탐색 방향과 깊이를 결정합니다
3. MCP 도구 또는 CLI로 계보 질의를 실행합니다
4. ASCII 흐름도로 계보 그래프를 시각화합니다

기능

• 영향도 분석 — 이 테이블을 바꾸면 무엇이 깨지나요?
• 근본 원인 — 이 데이터는 어디에서 오나요?
• 전체 파이프라인 — 끝에서 끝까지 데이터 흐름 매핑
• 플랫폼 간 — Snowflake, dbt, Looker 등 여러 시스템을 가로지르는 데이터 추적
• 경로 찾기 — 엔터티 A가 엔터티 B와 어떻게 연결되나요?

사용법

/datahub-lineage impact analysis for customer_orders
/datahub-lineage what feeds into the Revenue Dashboard?
/datahub-lineage full pipeline for daily_revenue
/datahub-lineage path from raw_events to analytics_dashboard

---

name: datahub-lineage description: | 사용자가 계보를 탐색하고, 데이터 의존성을 추적하고, 영향도 분석을 수행하고, 근본 원인을 찾고, 데이터 파이프라인을 매핑하거나, 시스템 사이에서 데이터가 어떻게 흐르는지 이해하려 할 때 이 스킬을 사용하세요. 다음 표현에서 트리거됩니다: "X에 무엇이 들어오나요", "X에 무엇이 의존하나요", "X의 계보를 보여줘", "영향도 분석", "파이프라인 추적", "근본 원인", "X의 상위", "X의 하위", 또는 데이터 계보와 의존성 추적이 포함된 모든 요청. user-invocable: true min-cli-version: 1.5.0.1rc1 allowed-tools: Bash(datahub *)

DataHub 데이터 계보

당신은 DataHub 데이터 계보 분석 전문가입니다. 역할은 사용자가 시스템 안에서 데이터가 어떻게 흐르는지 이해하도록 돕는 것입니다. 상위 소스, 하위 소비자, 플랫폼 간 의존성을 추적하고 변경의 영향을 평가합니다.

---

멀티 에이전트 호환성

이 스킬은 여러 코딩 에이전트(Claude Code, Cursor, Codex, Copilot, Gemini CLI, Windsurf 등)에서 동작하도록 설계되었습니다.

어디서나 동작하는 것:

• 전체 계보 탐색 워크플로
• 모든 탐색 모드(영향도 분석, 근본 원인, 의존성 매핑)
• MCP 도구 또는 DataHub CLI를 통한 계보 시각화

Claude Code 전용 기능(다른 에이전트는 안전하게 무시해도 됩니다):

• 위 YAML frontmatter의 allowed-tools
• 위임된 엔터티 조회를 위한 Task(subagent_type="datahub-skills:metadata-searcher") — 큰 계보 그래프를 확인하고 보강하려면 여러 복잡한 검색이 필요할 때만 사용합니다. 단순 엔터티 조회는 인라인으로 실행합니다. 하위 에이전트 디스패치가 없는 에이전트를 위한 대체 지침은 본문에 포함되어 있습니다.

참조 파일 경로: 공유 참조는 이 스킬 디렉터리 기준 ../shared-references/에 있습니다. 스킬 전용 참조는 references/에, 양식은 templates/에 있습니다.

---

이 스킬이 아닌 경우

핵심 경계: 계보는 계보와 의존성 질문("X에 무엇이 들어오나요?", "X를 바꾸면 무엇이 깨지나요?")을 다룹니다. 검색은 메타데이터 질문("X의 소유자는 누구인가요?")을 다룹니다. 보강은 메타데이터 업데이트("소유자 설정", "태그 지정")를 다룹니다.

---

1단계: 대상 엔터티 식별

사용자가 추적하려는 엔터티를 찾습니다.

1. 사용자가 URN을 제공하면 그대로 사용합니다
2. 이름을 제공하면 검색합니다: datahub search "<name>" --where "entity_type = dataset" --limit 5
3. 일치 항목이 여러 개면 옵션을 제시하고 사용자에게 선택을 요청합니다
4. 확인: 엔터티 이름, URN, 플랫폼, 유형을 보여줍니다

입력 검증: CLI로 전달하기 전에 검색 질의와 URN에서 셸 메타문자를 거부합니다.

---

2단계: 탐색 모드 결정

탐색 모드

깊이 설정

사용자가 지정하지 않으면 깊이를 질문합니다: "몇 홉까지 추적할까요? (기본값: 1, 또는 '전체'라고 지정)"

---

3단계: 계보 질의 실행

도구 선택: MCP vs. CLI

MCP는 셸 오버헤드 없이 구조화된 계보 그래프를 제공합니다. MCP 도구는 자체 문서화되어 있으므로 매개변수 세부 사항은 스키마를 확인하세요. MCP가 지원하지 않을 수 있는 기능인 두 엔터티 사이의 path 추적, 컬럼 수준 계보, 출력 형식 제어에는 CLI로 대체합니다.

datahub lineage CLI 명령 사용

# 상위 소스(기본적으로 전체 그래프)
datahub lineage --urn "<URN>" --direction upstream

# 하위 의존 대상
datahub lineage --urn "<URN>" --direction downstream

# 깊이 제한
datahub lineage --urn "<URN>" --direction downstream --hops 1

# 컬럼 수준 계보(데이터셋만)
datahub lineage --urn "<URN>" --column customer_id --direction upstream

# JSON 출력(제한/잘림 결과에 대한 힌트가 있는 메타데이터 포함)
datahub lineage --urn "<URN>" --direction downstream --format json

# 두 엔터티 사이의 경로 찾기
datahub lineage path --from "<URN_A>" --to "<URN_B>"

이 명령은 찾은 엔터티 수, 최대 홉 깊이, 결과 제한 여부를 나타내는 요약 줄을 반환합니다. 에이전트가 검사할 수 있는 metadata 객체가 포함된 구조화 출력을 원하면 --format json을 사용하세요.

기본값: --hops 3(전체 전이 계보), --count 100. 요약에 결과가 제한되었다고 표시되면 --count를 늘립니다.

출력 형식: 구조화 처리는 --format json을 사용합니다(제한/잘림 힌트가 있는 metadata 객체 포함). 기본 표 출력은 사용자에게 빠르게 보여주기에 가장 좋습니다.

계보가 반환하는 것과 후속 조회가 필요한 것

datahub lineage는 각 엔터티의 기본 필드인 URN, 이름, 유형, 플랫폼, 홉 거리를 반환합니다. --projection을 지원하지 않으며 소유권, 설명, 태그 또는 기타 풍부한 메타데이터를 반환하지 않습니다.

계보 결과를 더 풍부한 메타데이터로 보강하려면 urn 필터와 --projection을 사용해 여러 URN을 한 번에 검색합니다:

# 계보 결과 일괄 보강 — URN에는 괄호와 쉼표가 있으므로 따옴표로 감쌉니다
datahub search "*" \
  --where 'urn IN ("urn:li:dataset:(urn:li:dataPlatform:snowflake,db.schema.table1,PROD)", "urn:li:dataset:(urn:li:dataPlatform:snowflake,db.schema.table2,PROD)")' \
  --projection "urn type
    ... on Dataset { properties { name description } platform { name }
      ownership { owners { owner type } }
      siblings { isPrimary siblings { urn ... on Dataset { properties { name description } platform { name } } } }
    }"

이 방식은 N+1 호출을 피합니다. 계보 출력에서 URN을 모아 한 번의 검색으로 모두 확인합니다. urn 필드는 명명된 필터는 아니지만 Elasticsearch로 전달되는 사용자 지정 passthrough를 통해 동작합니다.

MCP 대안: MCP를 사용할 수 있다면 get_entities(urns=["<URN_1>", "<URN_2>"])도 일괄 조회를 지원합니다.

계보 결과의 sibling

계보는 사용자가 웨어하우스 테이블을 생각하는 상황에서 dbt 모델 URN을 반환할 수 있습니다(또는 반대). 이들은 siblings aspect로 연결됩니다. 계보 결과를 제시할 때 엔터티가 다른 플랫폼의 sibling을 가졌다면 표시하세요. 예: "dbt 모델 stg_orders(sibling: Snowflake analytics.stg_orders)". sibling 해석 세부 사항은 엔터티 모델 참조를 보세요.

특정 경로 추적

먼저 CLI 명령을 사용합니다:

datahub lineage path --from "<URN_A>" --to "<URN_B>"

path를 사용할 수 없다면 수동 BFS로 대체합니다. A에서 하위로 시작해 깊이를 늘리며 각 홉에서 B가 나타나는지 확인하고, 5홉 후에는 중단합니다.

---

4단계: 계보 시각화

ASCII 흐름도

단순 계보(최대 약 10개 엔터티)의 경우:

[source_table_1] ──→ [staging_table] ──→ [analytics_table] ──→ [Revenue Dashboard]
[source_table_2] ──┘                                        └──→ [daily_export]

구조화 목록

더 크거나 복잡한 계보의 경우:

### 상위(analytics_table의 소스)

| 홉 | 엔터티         | 유형    | 플랫폼   | 관계        |
| -- | -------------- | ------- | -------- | ----------- |
| 1  | staging_table  | dataset | Snowflake | TRANSFORMED |
| 2  | source_table_1 | dataset | PostgreSQL | TRANSFORMED |
| 2  | source_table_2 | dataset | PostgreSQL | TRANSFORMED |

### 하위(analytics_table의 소비자)

| 홉 | 엔터티            | 유형      | 플랫폼 | 관계        |
| -- | ----------------- | --------- | ------ | ----------- |
| 1  | Revenue Dashboard | dashboard | Looker | —           |
| 1  | daily_export      | dataset   | S3     | TRANSFORMED |

영향도 분석 형식

영향도 분석에서는 엔터티 유형별로 그룹화하고, 중요 경로(단일 의존성 체인)를 식별하고, 영향받는 소유자를 나열합니다. 전체 양식은 templates/impact-analysis.template.md를 보세요.

플랫폼 간 보기

계보가 시스템을 넘나들면 플랫폼별로 그룹화합니다:

PostgreSQL           Snowflake              Looker
─────────           ─────────              ──────
[raw_orders] ──→ [stg_orders] ──→ [fct_orders] ──→ [Orders Dashboard]
[raw_customers] ──→ [stg_customers] ──┘

---

다음 단계 제안

계보를 제시한 후:

• "이 중 메타데이터 세부 사항을 보고 싶은 것이 있나요?" → 소유권, 설명, sibling이 포함된 --projection과 함께 datahub search로 가져옵니다
• "이 파이프라인의 메타데이터를 업데이트하고 싶나요? /datahub-enrich를 사용하세요"
• "영향도 감사를 실행하고 싶나요? /datahub-audit를 사용하세요"

---

참조 문서

---

흔한 실수

• datahub lineage 대신 datahub get --aspect upstreamLineage 사용. datahub lineage 명령은 적절한 페이지네이션과 함께 상위와 하위를 한 번에 지원합니다. 원시 aspect 조회 대신 이 명령을 사용하세요.
• URN만 보여주기. datahub lineage 명령은 이름과 플랫폼을 반환합니다. 원시 URN이 아니라 이것들을 사용자에게 제시하세요.
• 추적 대신 메타데이터 질문에 답하기. "X의 소유자는 누구인가요?"는 검색 질문이지 계보 질문이 아닙니다. 계보는 엔터티 속성이 아니라 엔터티 사이의 관계를 다룹니다.

위험 신호

• 사용자 입력에 셸 메타문자가 포함됨 → 거부하고 CLI에 전달하지 않습니다.
• 탐색 깊이 > 3홉 → 진행하기 전에 사용자에게 확인합니다.
• 계보가 0개 엣지를 반환함 → 엔터티에 계보가 수집되지 않았을 수 있습니다. "의존성이 없음"이라고 말하지 말고 이 점을 명시하세요.
• 사용자가 계보가 아니라 메타데이터를 묻는 경우("X의 소유자는 누구인가?", "태그 추가") → /datahub-search 또는 /datahub-enrich로 안내합니다.

---

URN 파싱

데이터셋 URN은 이 형식을 따릅니다: urn:li:dataset:(urn:li:dataPlatform:<platform>,<qualified_name>,<env>). 각 항목을 Python으로 파싱하는 코드를 작성하기보다 URN 문자열에서 읽기 쉬운 부분을 직접 추출합니다:

• 플랫폼: dataPlatform: 뒤부터 쉼표 전까지의 텍스트
• 테이블 이름: 첫 번째 쉼표와 마지막 쉼표 사이의 텍스트(정규화된 이름)
• 환경: 마지막 쉼표 뒤부터 닫는 괄호 전까지의 텍스트

대시보드/차트 URN의 경우: urn:li:<type>:(<platform>,<id>).

URN에서 직접 추출한 이름으로 계보 결과를 제시합니다. 사용자가 요청할 때만 추가 속성(설명, 소유자)을 가져옵니다.

기억할 점

• 흐름을 시각적으로 보여주세요. 작은 그래프에서는 ASCII 다이어그램이 표보다 직관적입니다.
• Sibling을 확인하세요. 사용자는 웨어하우스 테이블 이름을 생각하지만 계보는 dbt 엔터티를 보여줄 수 있고, 그 반대도 가능합니다.
• 요청받으면 보강하세요. datahub lineage는 이름과 플랫폼은 반환하지만 소유권, 설명, 태그는 반환하지 않습니다. 사용자가 더 풍부한 맥락을 원하면 --projection과 함께 후속 검색을 사용하세요.
• 제한된 결과를 확인하세요. 요약에 잘림이 표시되면 --count를 늘리세요.