수집 · 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는 스키마 생성과 중복 방지를 맡겨 주지만, 이름 충돌과 시간대는 사람이 확인해야 합니다. 적재 후 첫 행과 마지막 행의 시각을 원본과 한 번 대조합니다.

다음
06. 웨어하우스·레이크·레이크하우스
이어보기 →