Skip to main content

%sql 결과를 Python DataFrame으로 변환하는 실전 패턴

노트북에서 %sql%python을 혼합할 때, SQL 결과를 Python에서 사용하는 방법이 필요합니다.

방법 1: 임시 뷰 활용 (가장 일반적)

%sql
-- SQL에서 복잡한 쿼리 실행
CREATE OR REPLACE TEMP VIEW daily_sales AS
SELECT order_date, SUM(amount) AS total_sales
FROM catalog.schema.orders
GROUP BY order_date
ORDER BY order_date;
# Python에서 임시 뷰를 DataFrame으로 읽기
df = spark.table("daily_sales")

# 이제 Python으로 추가 처리 가능
import pandas as pd
pandas_df = df.toPandas()  # 데이터가 작을 때만 사용

방법 2: spark.sql() 함수 활용

# Python 셀에서 SQL을 직접 실행하고 결과를 DataFrame으로 받기
df = spark.sql("""
    SELECT order_date, SUM(amount) AS total_sales
    FROM catalog.schema.orders
    WHERE order_date >= '2025-01-01'
    GROUP BY order_date
""")
display(df)

방법 3: _sqldf 매직 변수 (간편하지만 비공식)

%sql
SELECT * FROM catalog.schema.orders LIMIT 100
# 직전 %sql 셀의 결과가 _sqldf에 자동 저장됩니다
display(_sqldf)
💡 현업에서는 이렇게 합니다: SQL이 가독성이 좋은 경우(집계, 조인 등)에는 %sql로 쿼리를 작성하고, 그 결과를 Python에서 ML 모델에 넣거나 복잡한 로직을 처리할 때 혼합 사용합니다. “SQL을 잘 하는 분석가가 쿼리를 작성하고, ML 엔지니어가 Python으로 모델을 학습하는” 협업 패턴이 매우 흔합니다.

Notebook 고급 기능

위젯(Widgets) — 동적 매개변수

위젯을 사용하면 노트북 상단에 드롭다운, 텍스트 입력 등을 추가하여, 코드를 수정하지 않고도 매개변수를 변경할 수 있습니다.
# 드롭다운 위젯 생성
dbutils.widgets.dropdown("city", "서울", ["서울", "부산", "대구", "인천"])

# 위젯 값 사용
selected_city = dbutils.widgets.get("city")
display(df.filter(df.도시 == selected_city))

dbutils — Databricks 유틸리티

💡 dbutils 는 Databricks Notebook에서 사용할 수 있는 유틸리티 모음입니다. 파일 시스템 접근, 비밀 키 관리, 위젯 제어 등의 기능을 제공합니다.
유틸리티용도예시
dbutils.fs파일 시스템 조작dbutils.fs.ls("/mnt/data")
dbutils.widgets매개변수 위젯dbutils.widgets.text("name", "default")
dbutils.secrets비밀 키 접근dbutils.secrets.get("scope", "key")
dbutils.notebook다른 노트북 실행dbutils.notebook.run("./other", 60)

dbutils 핵심 기능 상세

dbutils는 Databricks Notebook에서만 사용할 수 있는 강력한 유틸리티입니다. 각 모듈별로 실전에서 가장 많이 쓰이는 기능을 상세히 살펴보겠습니다.

dbutils.secrets — 비밀 키 관리

비밀번호, API 키, 접속 정보를 코드에 직접 입력하면 안 됩니다. dbutils.secrets를 사용하면 안전하게 관리할 수 있습니다.
# 절대 이렇게 하지 마세요!!
password = "my_super_secret_123"  # 코드에 비밀번호 하드코딩 ❌

# 이렇게 하세요
password = dbutils.secrets.get(scope="my-scope", key="db-password")
jdbc_url = f"jdbc:postgresql://host:5432/mydb?user=admin&password={password}"
⚠️ 현업에서의 사고 사례: 노트북에 AWS Access Key를 하드코딩한 채로 Git에 push하여 보안 사고가 발생한 경우가 실제로 있습니다. dbutils.secrets를 쓰면 값이 [REDACTED]로 표시되어 실수로 노출될 위험이 없습니다.

dbutils.widgets — 매개변수화된 노트북

위젯은 노트북을 재사용 가능한 템플릿으로 만들어 줍니다.
# 위젯 생성
dbutils.widgets.text("start_date", "2025-01-01", "시작 날짜")
dbutils.widgets.text("end_date", "2025-03-31", "종료 날짜")
dbutils.widgets.dropdown("env", "dev", ["dev", "staging", "prod"], "환경")

# 위젯 값 사용
start = dbutils.widgets.get("start_date")
end = dbutils.widgets.get("end_date")
env = dbutils.widgets.get("env")

catalog = f"catalog_{env}"  # catalog_dev, catalog_staging, catalog_prod
df = spark.sql(f"""
    SELECT * FROM {catalog}.sales.orders
    WHERE order_date BETWEEN '{start}' AND '{end}'
""")
💡 위젯은 Lakeflow Jobs에서 파라미터로 전달 할 수 있습니다. 개발 시에는 위젯으로 값을 입력하고, 운영 시에는 Jobs에서 자동으로 파라미터를 주입하는 패턴이 매우 유용합니다.

dbutils.notebook.run — 노트북 간 호출

# 다른 노트북을 호출하고 결과를 받기
result = dbutils.notebook.run(
    path="./etl/load_customers",
    timeout_seconds=600,
    arguments={"date": "2025-03-15", "env": "prod"}
)
print(f"결과: {result}")  # 호출된 노트북의 dbutils.notebook.exit() 반환값
💡 현업에서는 이렇게 합니다: dbutils.notebook.run은 간단한 워크플로우에는 유용하지만, 복잡한 파이프라인에서는 Lakeflow Jobs 를 사용하는 것이 좋습니다. Jobs는 병렬 실행, 재시도, 알림, 의존성 관리 등 운영에 필요한 기능을 모두 제공합니다.

dbutils.fs — 파일 시스템 조작

# 파일 목록 확인
dbutils.fs.ls("/Volumes/my_catalog/my_schema/my_volume/")

# 파일 복사
dbutils.fs.cp(
    "dbfs:/Volumes/catalog/schema/raw/data.csv",
    "dbfs:/Volumes/catalog/schema/archive/data_20250315.csv"
)

# 파일/폴더 삭제 (recurse=True면 하위 전체 삭제)
dbutils.fs.rm("/Volumes/catalog/schema/temp/", recurse=True)

노트북 버전 관리 전략

노트북의 버전 관리는 크게 두 가지 방법이 있습니다.

방법 1: Databricks 내장 리비전 히스토리

노트북 우측 상단의 Revision history 버튼을 클릭하면, 자동 저장된 모든 버전을 확인하고 복원할 수 있습니다.
장점단점
별도 설정 불필요브랜치, PR 등의 협업 기능이 없습니다
자동 저장다른 프로젝트와 코드를 공유하기 어렵습니다
특정 시점으로 복원 가능코드 리뷰 프로세스가 없습니다
적합한 경우: 개인 실험, 일회성 분석, 빠른 프로토타이핑

방법 2: Git 연동 (Repos)

Databricks의 Repos 기능을 사용하면 GitHub, GitLab, Azure DevOps 등의 Git 저장소와 연동할 수 있습니다.
장점단점
브랜치, PR, 코드 리뷰 가능초기 설정이 필요합니다
CI/CD 파이프라인 연동Git 사용법을 알아야 합니다
팀 협업에 필수적노트북 출력 결과는 저장되지 않습니다
다른 IDE(VS Code 등)와 함께 사용 가능
적합한 경우: 팀 프로젝트, 프로덕션 코드, 코드 리뷰가 필요한 모든 경우
💡 현업에서는 이렇게 합니다: “개인 실험은 Workspace 폴더에서, 프로덕션 코드는 반드시 Repos(Git)로” 라는 원칙을 팀 내에서 명확히 합니다. 또한 Databricks에서는 노트북을 .py 파일로 저장하는 방식(Databricks Notebook 포맷)을 지원하므로, Git에서 diff(변경 사항 비교)가 깔끔하게 표시됩니다.

결과 내보내기

노트북 실행 결과는 다양한 형태로 내보낼 수 있습니다.
  • DBC 파일: Databricks 전용 포맷 (다른 Workspace로 가져오기 가능)
  • IPython Notebook (.ipynb): Jupyter Notebook 포맷
  • HTML: 실행 결과를 포함한 웹 페이지
  • Python/SQL 파일: 코드만 추출

정리

핵심 기능설명
셀 기반 실행코드를 셀 단위로 나누어 실행하고, 결과를 바로 확인할 수 있습니다
매직 커맨드%sql, %md, %sh 등으로 하나의 노트북에서 여러 언어를 혼합 사용할 수 있습니다
실시간 협업여러 사용자가 동시에 편집하고, 변경 이력이 자동 저장됩니다
시각화SQL/DataFrame 결과를 클릭 한 번으로 차트로 변환할 수 있습니다
dbutils파일 접근, 비밀 키 관리, 위젯 등 유틸리티를 제공합니다
다음 문서에서는 Databricks 무료 체험 을 시작하는 방법을 안내해 드리겠습니다.

참고 링크