탐색(Explore)
분석 엔지니어처럼 웨어하우스 또는 로컬 DuckDB 데이터베이스를 파악하세요: 중요한 것을 순위 매기고, 선택적으로 드릴다운하며, 초안 맵을 저장합니다. 이는 주력이며 완전한 읽기 전용(read-only) 스킬입니다. 프로파일링과 관계 추론을 기능으로 흡수합니다. 별도의 스킬이 아닙니다.
사용 방법
래퍼(wrapper)를 통해 엔진을 실행합니다. 정리된 JSON 인벨로프(envelope) 하나만 출력하며, 그 외에는 아무것도 출력하지 않습니다. 인벨로프를 읽고 다음 단계를 결정하세요.
uv run "${CLAUDE_SKILL_DIR}/scripts/run.py" <하위명령어> [플래그]
하위명령어는 일반적인 순서대로 다음과 같습니다:
connect test --path <file.duckdb>읽기 전용 연결을 확인하고 기능을 보고합니다.explore inventory --rank순위가 매겨진 객체 요약(개수와 크기, 행 데이터는 포함되지 않음)을 반환합니다.explore profile <objects>(공백 또는 쉼표로 구분) 열 프로필, (열, 카테고리, 신뢰도)로 기록된 PII 플래그(예시 값은 절대 포함되지 않음), 후보 키, 예상 그레인(grain), 데이터 품질 경고(예: 조인 시 확산될 고유하지 않은 id)를 반환합니다. 일반적인*_name플래그의 신뢰도는 동일한 스캔의 값 형태 증거에 의해 양방향으로 정제됩니다: 사람 형태의 값은 이를 뒷받침하고, 폐쇄된 참조 어휘 또는 긴 레이블은 방화벽 차단 임계값 이하로 낮추며, 증거가 없으면 아무 변화도 없습니다(플래그 자체는 절대 제거되지 않음). 고유 개수는 규모에 따라 근사치이지만, 근사 오차 내에서 고유해 보이는 열은 정확한 COUNT(DISTINCT)로 격상됩니다(distinct_count_exact: true). 따라서 고유성과 그레인 판정은 증거에 기반합니다. 경고에서~접두사는 여전히 근사치임을 나타냅니다. 요청된 객체의 캐시된 프로필이 여전히 최신 상태(동일한 커넥터, 스키마 변경 없음,profile_freshness_hours기본값 24시간 이내)인 경우, 다시 스캔하지 않고 캐시에서 제공됩니다(cache_hit_count). 따라서map이 방금 쓴 테이블을 프로파일링하는 데는 비용이 들지 않습니다. 소스가 무료 메타데이터 검사로 감지할 수 없는 방식으로 변경된 경우--refresh를 전달하여 강제로 다시 스캔하세요.explore relationships추론 및 선언된 조인을 신뢰도와 함께 반환하며, 추론이 무엇을 검토했는지 설명하는 메모도 포함합니다(따라서 빈 목록도 의미가 있습니다).--verify를 추가하여 각 추론된 조인을 집계 중첩 프로브(고아 비율, 조정된 신뢰도)로 측정합니다.explore map.dex/캐시를 쓰거나 업데이트하고 요약을 출력합니다(--verify도 여기서 작동합니다). 50개 객체를 초과하면 순위 기준 상위 25개만 프로파일링하고notes에 이를 명시합니다(skipped_count포함). 전체를 프로파일링하려면--full을 전달하세요. 다시 맵핑할 때, 이번 실행에서 건너뛴 객체는 이전 프로필을 유지합니다(carried_forward_count). 각 프로필에는 자체profiled_at타임스탬프가 찍혀 있어, 열 세부 정보가 조용히 사라지는 대신 오래되었음을 알 수 있습니다. 선택된 객체의 캐시된 프로필이 여전히 최신 상태(동일한 커넥터, 스키마 변경 없음,profile_freshness_hours기본값 24시간 이내에 프로파일링됨)인 경우, 다시 스캔 없이 재사용됩니다(cache_hit_count). 따라서 재실행 비용이 들지 않습니다. 소스가 무료 메타데이터 검사로 감지할 수 없는 방식으로 변경된 경우(예: 행은 변경되었지만 스키마는 변경되지 않음)--refresh를 전달하여 강제로 전체 재프로파일링을 수행하세요.explore relationships와 독립형explore profile도 동일한 방식으로 최신 프로필을 재사용합니다.explore diagram [--full]캐시된 맵을data.mermaid에 있는 Mermaid ER 다이어그램으로 렌더링합니다. 무료이며 연결이 필요 없습니다(캐시를 읽고 웨어하우스에는 연결하지 않음). 따라서 그림을 구성하는 동안 안전하게 다시 실행할 수 있습니다. 문자열을 축어적으로 펜싱된 ```mermaid 블록에 복제하여 사람이 볼 수 있게 하고, 디스크에 저장하려면.mmd또는 마크다운 파일에 작성하세요: 엔진은 의도적으로 파일을 쓰지 않습니다. 다이어그램을 수동으로 다시 그리거나 "정리"하지 마세요. 글리프(glyphs)는 엔진이 증거로부터 도출한 주장이며, 사용자가 제공한 그럴듯한 카디널리티는 이 명령이 방지하고자 하는 정확한 과장 주장입니다: 선언된 조인은 실선, 추론된 조인은 점선이며, 검증되지 않은 추론은 절대 "정확히 하나"라고 말하지 않습니다. 다이어그램을 제시하기 전에notes를 읽으세요. 생략된 객체나 열이 명시되어 있습니다.--full은 기본값(프로파일링된 객체, 조인된 객체 및 해당 그레인, 키, 조인, PII 열)에서 모든 적격 항목으로 범위를 넓힙니다.explore query "<SELECT ...>" ["<SELECT ...>" ...]고정 명령어로 다루지 않는 임시 질문에 답변합니다: SQL을 작성하면, 엔진의 쿼리 방화벽이 이를 거부하거나 제한합니다. 인수당 하나의 문을 전달하거나, 더 긴 목록을 위해--sql-file <path>를 사용하고, 한 번의 호출로 전체 질문 체인을 요청하세요(각 호출당 하나씩이 아님). 각 문은 독립적으로 판단되고 응답되므로, 하나가 거부되어도 다른 문에 영향을 주지 않으며,data.results는 문당 하나의 항목을 전달합니다. 프로파일링하지 않은 테이블(방금 빌드한 모델 포함)은 자동으로 프로파일링된 후 문이 실행되므로, 새로운 것을 탐색하는 데 세 번의 호출 대신 한 번의 호출이 필요합니다. 인벨로프는 무엇을 프로파일링했는지 말하며, 과금 연결자에서는 해당 프로필이 문과 동일한 확인에 가격이 책정됩니다. 결과는 행-메이저(row-major) 형식으로 반환되며 상한이 있습니다. 거부 시 위반 열과 수정 방법을 알려주므로, 한 번의 재작성으로 충분합니다. 프로브를 작성하기 전에${CLAUDE_SKILL_DIR}/references/probe-playbook.md를 읽으세요: 일반적인 질문을 효과적인 프로브 형태에 매핑합니다.explore cluster <object> [--features a,b,c] [-k N]객체의 숫자 열에 대한 제한된 샘플에 대해 k-평균(k-means)을 실행하고 세그먼트 구조를 반환합니다: 클러스터별 크기와 비율, 중심점(각 좌표는 해당 기능에 대한 클러스터의 평균(집계)), 실루엣 점수, 그리고-k가 생략된 경우 선택한 k와 선택 기준이 된 실루엣 스윕을 포함합니다..dex/캐시가 필요합니다(먼저map/profile실행). 기능은 프로파일링된 숫자, 비-PII, 비-키 열에서 자동 선택됩니다.--features를 전달하여 직접 선택할 수 있습니다(PII 열 또는 키 이름 지정은 의도적으로 포함시키며, 평균만 보고됩니다). 키는 절대 기능이 아닙니다: 그 평균은 의미가 없으며, 사실 테이블은 대부분 키와 소수의 측정값으로 구성되므로, 키로 클러스터링하면 대리 키 범위만 분할합니다. 키는 고유 열, 조인되는 열(map이 추론한 조인에서), 그리고 그렇게 명명된 열입니다. 여기서는 단순profile보다map을 선호하세요. 추론된 조인이 없으면 외래 키는 이름이 드러내는 경우에만 포착됩니다. 메모는 제외된 모든 열을 명명하므로, 결과를 신뢰하기 전에 확인하세요. 실루엣만으로는 알 수 없는 두 가지 사항이 있으며, 둘 다 메모에 있습니다. 샘플의 1% 미만을 보유한 클러스터는 세그먼트가 아닌 이상치 포켓이며, 정확히 멀리 떨어져 있기 때문에 점수를 높입니다: 이를 이상치 탐지로 보고하거나,-k로 재실행하여 본체를 분할하세요. 그리고 시드를 샘플링할 수 없는 연결자에서는 드로우가 실행마다 변경되므로, 두 번의 실행이 k에 대해 다를 수 있습니다. 인벨로프의sample_repeatable은 현재 상황을 알려주며, 다른 드로우에 걸친 실행 비교는 의미가 없습니다. 집계만 경계를 넘습니다: 샘플 행은 프로세스 내에서 클러스터링되며 컨텍스트에 들어가지 않습니다. 과금 연결자에서는 아래 스캔 명령어와 동일한 비용 핸드셰이크가 필요합니다(기능 열만 스캔되며, 방언 인식 샘플 절이 일부를 읽습니다). 따라서 먼저 예상치를 표시하고 예산을 확보하세요.[cluster]추가 기능(scikit-learn)이 필요합니다. 래퍼는 이 하위 명령어에 대해 자동으로 설치합니다.explore semantic list및explore semantic query는 dbt 시맨틱 레이어(메트릭, 차원, 엔티티)에 도달합니다.list는 발견입니다: 어떤 메트릭이 존재하며 각 메트릭이 그룹화할 수 있는 차원은 무엇인지.query는 명시적 모드 이후 위치 인수로 메트릭을 받고(--metric은 호환성을 위해 유지됨),--group-by <entity__dim>(선택적--where,--grain,--limit포함)을 사용하여 메트릭의 값을 상한이 있는 컬럼별 결과로 반환합니다. 이름 플래그는 쉼표로 구분된 목록이나 반복 플래그를 사용합니다(--group-by a,b는--group-by a --group-by b와 동일).--where는 절대 분할되지 않습니다. 두 가지 백엔드가 이에 응답하며,.dex/config.ymlsemantic.backend에 의해 선택되고--local/--api로 재정의 가능합니다.--local은 MetricFlow로 SQL을 렌더링하고 dex 자체 커넥터와 비용 핸드셰이크를 통해 실행하므로, 지출 전에 비용이 표시됩니다(dbt 프로젝트가 필요하며,query의 경우[semantic]추가 기능이 필요함.list는 둘 다 필요 없는 매니페스트 읽기 뷰입니다).--api는 호스팅된 dbt Cloud 배포에 쿼리를 보냅니다(호스트, 환경 ID,DBT_SL_TOKEN만 필요하며,[semantic-api]추가 기능이 필요하고 로컬 프로젝트는 필요 없음). 호스팅된 백엔드는 비용 가드가 적용되지 않는 유일한 곳입니다: dbt Cloud가 서버 측에서 실행하므로, 결과에는 지출이 dex가 아닌 dbt Cloud에서 관리된다는 명시적 경고가 포함되며,--confirm이 요청되지 않습니다. 어느 쪽이든 PII 형태의 그룹화 또는 필터링된 차원(예:user__email)은 쿼리 실행 전에 거부됩니다. 이는 레이어를 쿼리합니다. 레이어를 작성하는 것은transform의 작업입니다.
query에 대한 행동 규칙: 질문에 답할 수 있을 때는 고정 명령어를 선호하세요. 하나의 프로브는 하나의 질문에 답합니다. 여러 건의 관련 측정값을 여러 번 발행하지 말고 단일 쿼리로 일괄 처리하세요. PII 플래그가 지정된 열에 대한 집계는 측정(COUNT, APPROX_COUNT_DISTINCT, AVG(LENGTH(...)))이어야 하며, 값을 전달하는(MIN, ANY_VALUE, STRING_AGG) 것이 아니어야 합니다. FROM 절은 커넥터의 고유 관용구로 JSON 및 배열 열을 언네스트(unnest)할 수 있으며, 이는 스키마리스 데이터를 탐색하는 올바른 방법입니다(예: "이 JSON 열의 모든 행에 나타나는 키는 무엇인가"): BigQuery t, UNNEST(JSON_KEYS(doc)) AS k, Snowflake t, LATERAL FLATTEN(input => doc) f, Databricks t LATERAL VIEW EXPLODE(json_object_keys(doc)) x AS k, Postgres t, jsonb_object_keys(doc) AS k, Redshift t, UNPIVOT t.doc AS v AT k, DuckDB t, UNNEST(json_keys(doc)) AS u(k). 언네스트된 값은 쿼리의 테이블 열(단독, 또는 JSON/배열 함수를 통해)에서 와야 합니다. 서브쿼리, 다른 테이블, 리터럴, 생성기를 언네스트하는 것은 거부되며, 언네스트의 출력은 소스 열의 PII 플래그를 상속합니다. 플래그가 0.5 차단 임계값 이하로 낮아진 열은 해당 열을 명명하는 인벨로프 경고와 함께 정상적으로 투영됩니다. 경고를 수정해야 할 오류가 아닌 사용자용 정보로 취급하세요. 사용자가 거부된 열이 개인 데이터가 아니라고 말하면, .dex/config.yml에 pii_overrides 항목(완전히 정규화된 열, 선택적 이유)을 권장하세요. 이는 즉시 쿼리를 차단 해제하고, 재프로파일링 후에도 유지되며, git에서 검토 가능합니다. 플래그를 지우기 위해 .dex/cache.json을 수동으로 편집하지 마세요. SQL 실행을 위해 raw Python이나 데이터베이스 CLI로 대체하지 마세요. 방화벽 경로만이 허용된 유일한 경로입니다.
클라우드 및 데이터베이스 대상 (BigQuery, Snowflake, Databricks, Postgres, Redshift)
원격 웨어하우스 또는 데이터베이스는 --path를 커넥터 구성으로 대체합니다. connect test --connector <name>으로 시작하거나(또는 connector:와 함께 .dex/config.yml에 해당 블록 설정: bigquery:는 project 및 datasets 허용 목록, snowflake:는 고정된 warehouse 및 databases 허용 목록, databricks:는 고정된 SQL warehouse 및 catalogs 허용 목록, postgres:는 schemas 허용 목록, redshift:는 Serverless workgroup 및 schemas 허용 목록). 자격 증명은 발견되며, 절대 묻지 않습니다: 인벨로프가 누락되었거나 만료된 자격 증명을 보고하면, 그것이 명명하는 수정 사항을 중계하세요(BigQuery의 경우 gcloud auth application-default login, Snowflake의 경우 connections.toml 항목 또는 SNOWFLAKE_* 환경 변수, Databricks의 경우 databricks auth login 또는 DATABRICKS_* 환경 변수, Postgres의 경우 DATABASE_URL, PG* 환경 변수 또는 pg_service.conf 항목, Redshift의 경우 AWS 자격 증명 체인(aws configure, AWS_* 환경 변수) 또는 REDSHIFT_* 환경 변수). 사용자에게 키, 토큰 또는 비밀번호를 붙여넣도록 요청하지 마세요.
과금 연결자에서 스캔 명령어(profile, map, relationships, query)는 2단계 핸드셰이크를 실행합니다. 첫 번째 호출은 needs_confirmation을 반환하며, cost.estimate에 추정치(해당되는 경우 테이블별 분석 포함)가 있습니다: BigQuery의 경우 정확한 드라이런 바이트 수치, Snowflake의 경우 웨어하우스-초 단위의 경험적 추정치(레이블 estimate_quality: "heuristic", 크레딧 함께), Databricks의 경우 웨어하우스-초 단위의 하한(레이블 estimate_quality: "low", DBU 함께, 확인된 예산 내에서 스스로 정교해짐), Redshift의 경우 컴퓨트-초 단위의 경험적 추정치(RPU-시간 함께, Serverless 추정치는 한 번 60초 웨이크 최소값 포함), Postgres의 경우 데이터베이스-초(달러 없음, 보호되는 양은 운영 데이터베이스의 부하). 추정치를 사람이 읽을 수 있는 단위로 사용자에게 표시하고, 명시적인 예산을 받은 후 동일한 명령을 해당 패러다임 단위의 --confirm 및 --budget <magnitude>와 함께 재발행하세요. 사용자가 동의하지 않은 예산을 절대 임의로 생성하지 말고, 초과 한도 거부 시 예산을 인상하여 재시도하기 전에 반드시 물어보세요. 메타데이터는 무료입니다(connect test, inventory는 즉시 실행됨). OK 인벨로프는 data.spend 아래에 실제 지출을 보고합니다.
BigQuery에서 프로파일링 추정치는 집계 스캔 후에도 여전히 프로파일이 발행할 수 있는 각 상향 조정(escalation) 쿼리에 대해 테이블당 10MB의 기본값을 보유합니다. 따라서 많은 소규모 테이블이 있는 웨어하우스에서는 대부분의 숫자가 실제로 발생하지 않는 작업에 대한 예비가 될 수 있습니다. 핸드셰이크와 초과 한도 거부 모두 이 분할을 보고합니다(reserved_bytes 및 reserved_queries, 그리고 설명). 추정치를 표시할 때 이를 전달하세요. 숫자가 스캔인지 예비인지에 따라 예산 인상이 작업을 구매하는지 또는 헤드룸을 구매하는지가 결정됩니다.
추정치가 작업에 비해 너무 클 때는 예산을 인상하는 대신 범위를 좁히세요. --scope(반복 가능)는 명령을 구성된 소스 허용 목록의 일부로 제한하며, 커넥터 자체 용어를 사용합니다: BigQuery의 데이터셋, Snowflake의 schema 또는 database.schema, Databricks의 catalog.schema, Postgres 또는 Redshift의 스키마. 해결하는 데 무료이며, 명령 자체의 확정된 예산만 소비하므로 실험에 안전합니다.
로컬 DuckDB (빠른 시작, 프로토타이핑, 작은 폭발 반경)
로컬 DuckDB 파일을 사용하면 연결 문자열이나 자격 증명이 필요 없으며, 과금 문제가 없고, .dex/ 캐시 외부에는 아무것도 기록되지 않습니다. 이것이 기본값입니다. DuckDB를 찾을 수 없으면(import duckdb 실패) 래퍼가 이를 알려주므로 설치(pip install duckdb 또는 프로젝트 매니저를 통해)하세요.
dbt 통합
dex는 디렉토리 트리(dbt 프로젝트, profiles.yml, 또는 둘 다) 안에서 실행될 때 dbt 프로젝트를 감지하고 강제로 사용합니다: --project-dir로 명시적으로 전달하거나 dex가 CWD를 거슬러 올라가 dbt_project.yml을 찾도록 하세요. --profiles-dir(기본값 ~/.dbt)은 profiles.yml을 찾는 곳이며, dbt에 의해 프로파일이 확인되지 않으면 연결 확인 시 오류가 발생합니다. dbt 프로젝트가 있으면 Dex는 explore에서 프로젝트의 리소스(source, model, seed, snapshot, exposure, metric)를 사용하여 다음을 수행합니다:
inventory는 프로젝트 리소스 맵과 웨어하우스 객체를 병합하여, dbt가 모델링하지 않은 객체를 식별합니다.explore profile은 프로젝트의 열 설명과 테스트를 프로필에 병합합니다.relationships는 프로젝트의source및model선언(ref및source)에서 알려진 조인을 추론합니다.map은 dbt의 리소스 유형과 설명으로 모든 객체에 주석을 답니다.semantic명령어는 MetricsFlow 변환을 위해 프로젝트를 사용해야 합니다.
하위 명령어 참조
아래 참조는 편의상 나열된 것입니다. 이 문서의 주요 섹션이 권위 있는 소스이며, run.py --help는 각 하위 명령어에 대한 최신 도움말을 인쇄합니다. 불일치가 발생하면 문서에 버그를 신고하세요.
connect test [--connector ] [--path ] [플래그]
연결을 확인하고 기능을 보고합니다. --path(로컬 DuckDB) 또는 --connector(원격, 구성 파일에서 모든 세부 정보 확인)가 필요합니다. 연결 실패 시 인벨로프에 수정 방법이 포함됩니다.
explore inventory [--connector ] [--path ] [--rank] [--scope <항목> [...]]
스키마의 객체를 나열합니다. --rank는 객체가 더 많은 데이터를 보유하거나 더 많은 참조를 가질 때 점수를 높여 순서를 매깁니다.
explore profile <객체> [--connector ] [--path ] [--scope <항목> [...]] [<공통 플래그>]
객체의 각 열에 대한 프로파일을 반환합니다: 유형, 고유성, 널(null) 비율, 최소/최대 길이, PII 추정치, 후보 키, 데이터 품질 경고. 예시 값은 포함되지 않습니다.
explore relationships [--connector ] [--path ] [--scope <항목> [...]] [--verify] [<공통 플래그>]
추론된 조인(통계적 중첩 기반)과 명시적으로 선언된 조인(dbt ref/source에서)을 반환합니다. 덜 명확한 조인은 신뢰도가 낮습니다.
explore map [--connector ] [--path ] [--scope <항목> [...]] [--verify] [--full] [--refresh] [<공통 플래그>]
프로파일과 조인을 캐시에 저장하고 요약을 출력합니다. 50개 객체를 초과하면 상위 25개만 프로파일링됩니다. --full을 전달하면 모든 객체를 프로파일링합니다. --refresh는 캐시된 프로필을 무시하고 강제로 다시 스캔합니다.
explore diagram [--full]
캐시된 .dex/ 맵에서 Mermaid ER 다이어그램을 생성합니다. 연결이 필요 없습니다. --full은 프로파일링된 객체에서 모든 열로 확장됩니다.
explore query "" [...] [--connector ] [--path ] [--scope <항목> [...]] [--sql-file ] [<공통 플래그>]
임시 SQL을 실행합니다. 방화벽이 거부하거나 제한합니다. 여러 문을 전달할 수 있으며, 각 문은 독립적으로 처리됩니다.
explore cluster <객체> [--features a,b,c] [-k N] [<공통 플래그>]
k-평균 클러스터링을 실행합니다. 프로파일 캐시가 필요합니다. 기능은 자동 선택되거나 직접 지정할 수 있습니다.
explore semantic list
시맨틱 레이어 메트릭을 나열합니다.
explore semantic query <메트릭> --group-by <entity__dim> [--where ...] [--grain ...] [--limit N] [--local] [--api] [<공통 플래그>]
시맨틱 레이어 메트릭을 쿼리합니다.
공통 플래그
--connector <name>: 원격 커넥터를 지정합니다.--path <file>: 로컬 DuckDB 파일을 지정합니다.--scope <항목>: 허용 목록의 하위 집합으로 범위를 좁힙니다.--confirm: 비용 추정치를 확인합니다.--budget <숫자>: 과금 연결자의 최대 예산을 설정합니다.--refresh: 캐시를 우회하고 강제로 다시 스캔합니다.--output json(기본값): JSON 인벨로프를 출력합니다. 이 형식은 에이전트가 파싱하기 위한 것입니다.
출력 형식
모든 출력은 단일 JSON 객체(인벨로프)이며, 사람의 개입을 위한 추가 텍스트는 없습니다. 구조는 다음과 같습니다:
{
"status": "ok" | "error" | "needs_confirmation",
"data": { /* 하위 명령어별 페이로드 */ },
"cost": { /* 과금 연결자에 대한 예상 또는 실제 비용, 선택 사항 */ },
"notes": [ /* 경고, 설명 등. */ ]
}
JSON 인벨로프는 전체 JSON 객체가 아니라 한 줄로 인코딩된 JSON입니다. 에이전트는 이를 파싱하고 다음 단계를 결정해야 합니다.
구성 파일
.dex/config.yml은 프로젝트별 설정(커넥터, 자격 증명, dbt 경로, PII 재정의, 시맨틱 백엔드 등)을 저장합니다. Dex는 필요에 따라 이 파일을 생성하고 업데이트합니다. 직접 편집할 수 있지만, Dex가 이를 읽고 존중합니다.
현재 제한 사항
explore cluster는[cluster]추가 기능이 필요합니다(scikit-learn).- 시맨틱 쿼리(
query)는[semantic]또는[semantic-api]추가 기능이 필요합니다. explore query는 SQL 방화벽에 의해 제한됩니다: SELECT 문만 허용됩니다.- 매우 큰 웨어하우스(수천 개의 객체)에서
explore map --full은 시간과 비용이 많이 소요될 수 있습니다.