dlt (Data Load Tool) — Python 기반 데이터 수집은(는) 무엇을 하나요?
당신은 dlt, 오픈소스 Python 데이터 파이프라인 라이브러리의 전문가입니다. 개발자가 간단한 Python 데코레이터를 사용해 API, 파일, 데이터베이스에서 웨어하우스와 레이크로 데이터를 로드할 수 있도록 돕습니다. 자동 스키마 추론, 증분 로드, 내장 데이터 계약을 제공합니다. dlt는 '데이터 파이프라인을 위한 requests 라이브러리'입니다.
핵심 기능
기본 파이프라인
import dlt
# 가장 간단한 파이프라인: Python 제너레이터 → 웨어하우스
@dlt.resource(write_disposition="append")
def github_events():
"""GitHub 저장소 이벤트를 로드합니다."""
import requests
response = requests.get("https://api.github.com/repos/org/repo/events")
yield from response.json()
# 파이프라인 실행
pipeline = dlt.pipeline(
pipeline_name="github_events",
destination="bigquery", # 또는: postgres, snowflake, duckdb, motherduck
dataset_name="raw_github",
)
load_info = pipeline.run(github_events())
print(load_info) # 스키마 자동 추론
증분 로드
@dlt.resource(
write_disposition="merge", # Upsert: 기존 업데이트, 새 항목 삽입
primary_key="id",
)
def orders(
updated_at=dlt.sources.incremental(
"updated_at",
initial_value="2025-01-01T00:00:00Z"
)
):
"""주문을 증분 로드 — 마지막 실행 이후 새로운/변경된 항목만.
dlt가 커서를 실행 간 자동 추적합니다.
수동으로 상태를 저장할 필요가 없습니다.
"""
import requests
page = 1
while True:
response = requests.get("https://api.shop.com/orders", params={
"updated_after": updated_at.last_value,
"page": page,
"per_page": 100,
})
data = response.json()
if not data:
break
yield from data
page += 1
REST API 소스 (선언형)
from dlt.sources.rest_api import rest_api_source
# 선언형 API 소스 — 표준 REST API에 코드 불필요
source = rest_api_source({
"client": {
"base_url": "https://api.hubspot.com/crm/v3/",
"auth": { "type": "bearer", "token": dlt.secrets["hubspot_token"] },
"paginator": { "type": "offset", "limit": 100, "offset_param": "offset" },
},
"resources": [
{
"name": "contacts",
"endpoint": { "path": "objects/contacts" },
"write_disposition": "merge",
"primary_key": "id",
},
{
"name": "deals",
"endpoint": { "path": "objects/deals" },
"write_disposition": "merge",
"primary_key": "id",
},
],
})
pipeline = dlt.pipeline(destination="bigquery", dataset_name="raw_hubspot")
pipeline.run(source)
데이터 계약
# 스키마 계약 강제 — 예상치 못한 변경에 명확하게 실패
@dlt.resource(
write_disposition="merge",
primary_key="id",
columns={
"id": {"data_type": "bigint", "nullable": False},
"email": {"data_type": "text", "nullable": False},
"plan": {"data_type": "text", "nullable": False},
"mrr_cents": {"data_type": "bigint"},
},
schema_contract="evolve", # "freeze" | "evolve" | "discard_value" | "discard_row"
)
def customers():
# API가 예상치 못한 필드를 반환하면 dlt가 계약 설정에 따라 처리
yield from fetch_customers()
설치
pip install dlt[bigquery] # + 대상 어댑터
# 다른 대상: dlt[snowflake], dlt[postgres], dlt[duckdb], dlt[motherduck]
모범 사례
- DuckDB로 시작 —
destination="duckdb"로 로컬 개발, 프로덕션은 BigQuery/Snowflake로 전환 - API는 증분 로드 사용 —
dlt.sources.incremental로 상태 저장; dlt가 실행 간 커서 추적 - REST API 소스 — 표준 REST API에는 선언형
rest_api_source사용; 복잡한 API만 사용자 정의 리소스 작성 - 엔터티는 병합 사용 — 엔터티 테이블에는
write_disposition="merge"+primary_key; 이벤트 스트림에는append - 스키마 계약 — 프로덕션에서
schema_contract="freeze"설정하여 API 변경 시 즉시 발견 - 시크릿 관리 — 환경 변수 또는
.dlt/secrets.toml로 백업된dlt.secrets["key"]사용 - 변환 — 로드 중 행 수준 변환에는
add_map()사용; 더 무거운 변환은 dbt에 적합 - 어디든 배포 — dlt는 라이브러리이지 서비스가 아님; cron, Airflow, Dagster, GitHub Actions, Lambda에 배포