수집 · CH05
dlt로 API 데이터 수집하기
dlt(data load tool)는 Python 함수가 내보내는 데이터를 받아 스키마를 자동으로 만들고, 목적지 DB에 적재하는 오픈소스 라이브러리입니다. 04장에서 손으로 짠 중복 방지·스키마 관리를 맡겨 봅니다. 실제로 돌리며 걸린 함정 세 가지도 함께 적었습니다.
설치
pip install "dlt[duckdb]==1.32.0"
DuckDB 버전 충돌: 2026-11-22 기준
dlt[duckdb]1.32.0은 DuckDB 2.0과 함께 설치되지 않았습니다(pip가 버전 충돌로 거부). dlt를 쓸 때는 별도 가상환경을 만들거나 DuckDB 1.5를 씁니다.
코드
import dlt
from dlt.sources.helpers import requests
@dlt.resource(name="seoul_hourly", primary_key="time", write_disposition="merge")
def seoul_hourly():
r = requests.get("https://api.open-meteo.com/v1/forecast", params={
"latitude": 37.5665, "longitude": 126.978, "timezone": "Asia/Seoul",
"hourly": "temperature_2m,precipitation", "forecast_days": 2})
h = r.json()["hourly"]
for t, temp, rain in zip(h["time"], h["temperature_2m"], h["precipitation"]):
yield {"time": t, "temp": temp, "rain": rain}
pipeline = dlt.pipeline(pipeline_name="weather", destination="duckdb", dataset_name="raw_weather")
print(pipeline.run(seoul_hourly()))
print(pipeline.run(seoul_hourly())) # 두 번 돌려도 primary_key 기준 merge
import duckdb
con = duckdb.connect("weather.duckdb", read_only=True)
print(con.sql("SELECT count(*) AS rows, min(time), max(time) FROM raw_weather.seoul_hourly").fetchall())
print(con.sql("SELECT table_name FROM information_schema.tables WHERE table_schema='raw_weather' ORDER BY 1").fetchall())
print(con.sql("DESCRIBE raw_weather.seoul_hourly").fetchall())
primary_key="time"과 write_disposition="merge"가 04장의 upsert를 대신합니다. 실제로 두 번 실행해도 행 수는 48행(2일×24시간) 그대로였고, dlt가 적재 기록용 테이블(_dlt_loads, _dlt_version, _dlt_pipeline_state)을 함께 만들었습니다.
직접 돌리며 걸린 함정
| 증상 | 원인 | 해결 |
|---|---|---|
Ambiguous reference to catalog or schema "weather" | DuckDB 파일 이름(weather.duckdb)과 데이터셋 이름(weather)이 같아 구분하지 못함 | 데이터셋 이름을 raw_weather처럼 다르게 |
| 저장된 시각이 9시간 밀려 보임 | API가 서울 시간을 시간대 표시 없이("2026-11-22T00:00") 보냈고, dlt가 이를 UTC로 저장 | API에 timezone=UTC로 받거나, 적재 전에 시간대를 붙여 변환 |
| DuckDB 2.0과 같이 설치 안 됨 | dlt의 duckdb 의존성이 2.0 미만으로 묶여 있음 | 도구별 가상환경 분리 |
두 번째 함정은 저장된 값만 보면 알아채기 어렵습니다. 최솟값이 2026-11-22 09:00+09로 나와서, API가 준 첫 시각(서울 0시)과 비교하고서야 9시간 밀린 것을 찾았습니다. 수집 단계에서 시간대를 확인하는 테스트를 하나 두는 편이 안전합니다.
이것만 기억하세요
dlt는 스키마 생성과 중복 방지를 맡겨 주지만, 이름 충돌과 시간대는 사람이 확인해야 합니다. 적재 후 첫 행과 마지막 행의 시각을 원본과 한 번 대조합니다.