커넥터로 외부 데이터 가져오기

엔지니어의 첫 표면은 커넥터입니다. 포털 안에 데이터가 한 톨도 없는 상태에서 외부 운영 시스템과 처음 잇는 단계이고, 이후 모든 파이프라인의 입력이 여기서 만들어집니다. 이번 레슨은 커넥터 하나를 처음부터 끝까지 등록하고, 그 결과로 데이터셋 한 개가 컬렉션 트리에 떨어지는 모습까지 확인합니다.

사전 준비

• 외부 시스템 접근 정보. 다음 중 하나면 됩니다.
  • 사내 운영 DB의 읽기 전용 계정 (PostgreSQL·MySQL·Snowflake 등 포털이 지원하는 RDBMS)
  • S3 또는 호환 객체 스토리지의 read 권한 access key
  • REST API endpoint + 토큰 (예: 사내 메트릭 API)
• 작업할 컬렉션 한 개. 분석가 코스 03 레슨에서 만든 컬렉션을 재활용해도 됩니다.

운영 자격증명을 자기 PC에 두지 마세요. 포털은 자격증명을 secrets 저장소에 암호화 보관하고, 운영팀이 따로 갱신하는 흐름을 가정합니다.

커넥터는 두 단계로 등록됩니다

포털 커넥터는 늘 같은 두 단계로 만들어집니다.

1. 타입 선택과 인증 등록 — 어떤 외부 시스템인지(DB·객체 스토리지·REST·메시지 큐) + 어떻게 인증할지(아이디/비밀번호·key pair·OAuth·토큰)
2. 스키마 매핑 — 그 시스템 안에서 무엇을(테이블·버킷 prefix·endpoint 경로) 어떤 데이터셋 모양으로 포털에 끌어올지

이 둘이 끝나면 커넥터는 데이터셋 하나 또는 여러 개의 발생지가 됩니다.

1단계 — 인증 등록

1. 좌측 사이드바에서 커넥터를 누르고 컬렉션 안에서 커넥터 만들기를 고릅니다.
2. 타입 목록에서 외부 시스템을 고릅니다. 흔한 출발점은 PostgreSQL·S3·REST API 셋 중 하나.
3. 호스트·포트·데이터베이스 이름(또는 버킷 이름, base URL) 같은 비밀이 아닌 식별 정보를 채웁니다.
4. 자격증명은 시크릿 저장소에 새로 등록을 골라 포털이 관리하게 둡니다. 평문을 폼에 넣지 않습니다.
5. 연결 테스트를 누르면 포털이 외부 시스템에 한 번 붙어 핸드셰이크만 확인합니다. 성공이면 녹색, 실패면 어떤 단계(DNS·인증·권한)에서 막혔는지 메시지가 돌아옵니다.

2단계 — 스키마 매핑

연결 테스트가 통과되면 포털이 외부 시스템의 스키마를 한 번 스캔합니다.

• DB 커넥터: 데이터베이스 안의 테이블 목록이 트리로 보입니다. 가져올 테이블을 체크. 컬럼 단위 선택·컬럼명 alias·타입 cast 옵션이 같은 화면에 있습니다.
• S3 커넥터: prefix 하나와 파일 패턴(*.parquet, *.csv.gz)을 지정. 같은 prefix 안에 여러 파일이 있으면 단일 데이터셋의 partitioning으로 묶입니다.
• REST API 커넥터: endpoint와 응답 JSON 경로($.data.items[*])를 지정. 포털이 그 경로의 결과를 표 한 장으로 평탄화합니다.

세 경우 모두 마지막에 만들어질 데이터셋 이름을 정합니다. 한 커넥터가 데이터셋 여러 개를 만들 수 있고, 같은 컬렉션 안에 일관된 이름 규칙(예: src_<system>_<entity>)을 두면 이후 파이프라인에서 노드 찾기가 쉽습니다.

가져오기 한 번 실행

스키마 매핑이 끝나면 가져오기 실행 버튼이 살아납니다. 누르면 포털이 외부 시스템에서 데이터를 한 번 fetch해 데이터셋으로 떨어뜨립니다. 끝나면 셋만 확인합니다.

• 컬렉션 트리에 새 데이터셋(예: src_postgres_orders)이 떴는가
• 행 수가 외부 시스템에서 예상한 수와 같은가 (간단 카운트 SQL과 비교)
• 스키마 미리보기에서 타입이 의도대로 추정됐는가 (특히 날짜 컬럼이 문자열로 잡혔는지)

이 시점의 데이터셋은 원본 그대로의 사본입니다. 변환은 다음 단계.

분석가에게 바로 보이지 않게 두기

원본 데이터셋은 보통 엔지니어만 보는 권한으로 둡니다. 분석가가 컬렉션 트리에서 source 데이터셋을 직접 조회하기 시작하면, 이후 변환 결과가 바뀔 때 누구의 위젯이 깨지는지 추적이 어렵습니다.

권장 패턴.

• 원본 데이터셋이 떨어지는 컬렉션을 데이터 엔지니어 컬렉션으로 따로 두고 Reader 권한도 좁힌다.
• 분석가에게 노출할 마트 데이터셋은 다음 레슨의 파이프라인 결과로 만들어 별도 컬렉션에 두고, 분석가에게는 그 컬렉션의 Reader 권한만 준다.

이 분리는 06 레슨의 인계 단계에서 다시 등장합니다.

자가 점검

• 새 커넥터가 좌측 트리에 보이고 연결 테스트가 녹색인가
• 가져오기 결과로 데이터셋 하나가 새로 떨어졌는가
• 자격증명이 포털 시크릿 저장소에 등록돼 있고 폼 안에 평문이 없는가
• 원본 데이터셋의 권한이 분석가에게 막혀 있는가

다음 레슨

이 데이터셋을 워크플로우 편집기에 source 노드로 올리고, 첫 파이프라인을 한 사이클 돌려 봅니다.