마지막 업데이트: 2026년 3월 | 대상: 데이터 엔지니어, 플랫폼 엔지니어
Databricks Auto Loader는 클라우드 오브젝트 스토리지(S3, ADLS, GCS)에 새로 도착하는 파일을 자동으로 감지하고 스트리밍 방식으로 수집하는 핵심 기능이다. 파일을 "어떻게 감지할 것인가"에 따라 두 가지 모드를 선택할 수 있다.
- Directory Listing — 디렉토리를 주기적으로 스캔해 새 파일을 찾는 방식
- File Notification — 클라우드 이벤트 시스템을 구독해 파일 도착 즉시 알림을 받는 방식
두 방식의 동작 원리, 장단점, 그리고 어떤 상황에서 무엇을 선택해야 하는지를 깊이 있게 살펴본다.
1. Auto Loader와 파일 감지의 문제
데이터 레이크 파이프라인에서 가장 기본적인 질문은 "새 파일이 도착했는지 어떻게 알 것인가"다. Spark의 기본 파일 소스는 모든 서브디렉토리를 병렬로 리스팅한다. 예를 들어 /logs/YYYY/MM/DD/HH/ 구조라면:
1 (루트) + 365 (일별) × 24 (시간별) = 8,761번의 API 호출이 방식은 파일이 수백만 개로 늘어나면 클라우드 API 비용과 지연이 폭발적으로 증가한다. Auto Loader는 이 문제를 두 가지 전략으로 해결한다.
2. Directory Listing 모드
동작 원리
Directory Listing은 Auto Loader의 기본값이다. 입력 디렉토리를 주기적으로 리스팅해 이미 처리된 파일 목록(체크포인트)과 비교하여 새 파일을 식별한다.
Databricks는 일반 Spark 파일 소스 대비 최적화된 플랫 리스팅(flattened response)을 사용해 API 호출 수를 크게 줄였다.
| 클라우드 스토리지 | API 호출 1번당 반환 결과 수 |
|---|---|
| Amazon S3 | 1,000개 |
| Azure ADLS | 5,000개 |
| Google Cloud Storage | 1,024개 |
Incremental Listing (DBR 9.1+): 파일이 사전순(lexical order)으로 업로드되는 경우 — 날짜 파티션, 버전 번호 형식 등 — Auto Loader가 이를 자동 감지하고, 마지막으로 수집한 파일 이후 경로만 스캔해 API 호출을 추가로 절감한다.
⚠️ Incremental Listing은 deprecated 됐다. DBR 14.3+ 환경에서는 File Notification with File Events로 마이그레이션을 권장한다.
코드 예시
# Directory Listing (기본값, 별도 설정 불필요)
df = (spark.readStream
.format("cloudFiles")
.option("cloudFiles.format", "json")
# cloudFiles.useNotifications 옵션 생략 시 Directory Listing 동작
.load("s3://my-bucket/landing/events/")
)장점
- 설정이 간단하다. 클라우드 리소스(SQS, SNS, Event Grid 등)를 별도로 생성할 필요 없이, 스토리지 읽기 권한만 있으면 바로 시작할 수 있다.
- 경로 변경이 가능하다. DBR 11.3+에서는 기존 체크포인트를 유지하면서 소스 경로를 변경할 수 있다.
- Unity Catalog Volume을 지원한다. DBR 13.3+ 부터 Volume 경로를 소스로 사용할 수 있다.
단점
- 규모 확장에 한계가 있다. 파일 수백만 개가 쌓이면 리스팅 자체에 소요되는 시간과 비용이 커진다.
- 감지 지연이 발생한다. 스트림 트리거 주기마다 리스팅을 하므로, 파일 도착과 처리 시작 사이에 필연적인 지연이 생긴다.
- 클라우드 API 비용이 증가한다. 디렉토리 구조가 깊고 파일이 많을수록 LIST API 요청이 누적된다.
3. File Notification 모드
동작 원리
File Notification 모드는 클라우드 벤더의 이벤트 알림 인프라를 구독(subscribe)한다. 파일이 스토리지에 도착하는 즉시 이벤트가 발행되고, Auto Loader는 이 이벤트를 소비해 새 파일을 처리한다.
클라우드별로 사용하는 서비스 조합이 다르다.
| 클라우드 | 이벤트 브로커 | 큐 서비스 | 리소스 이름 접두사 | 버킷당 최대 스트림 수 |
|---|---|---|---|---|
| AWS S3 | AWS SNS | AWS SQS | databricks-auto-ingest- | 100 |
| Azure ADLS / Blob | Azure Event Grid | Azure Queue Storage | databricks | 500 |
| Google Cloud Storage | Google Pub/Sub | Google Pub/Sub | databricks-auto-ingest- | 100 |
File Notification의 두 가지 구현 방식
현재 File Notification에는 두 가지 변형이 존재한다.
(권장) File Events + Managed File Events Service
DBR 14.3+에서 도입된 방식으로, Databricks가 File Events Service를 통해 클라우드 이벤트를 중앙에서 수집하고 메타데이터 캐시에 저장한다. Auto Loader는 이 캐시를 읽어 새 파일을 식별한다.
# File Notification with File Events (권장)
df = (spark.readStream
.format("cloudFiles")
.option("cloudFiles.format", "parquet")
.option("cloudFiles.useManagedFileEvents", True) # 핵심 옵션
.load("abfss://container@storage.dfs.core.windows.net/landing/")
)File Events 방식의 핵심 이점:
- 외부 로케이션(External Location) 하나당 큐 하나만 생성 → 클라우드 리소스 한도에 여유
- Databricks가 클라우드 리소스를 자동으로 설정/관리
- 별도 자격증명 추가 불필요 (Unity Catalog 권한 재사용)
- 주기적 디렉토리 전체 스캔을 통한 누락 파일 자동 보정
(레거시) 클래식 File Notification
스트림마다 별도 큐를 생성하는 구형 방식이다. cloudFiles.useNotifications=true 옵션을 사용하며, 여전히 동작하지만 새 프로젝트에서는 권장되지 않는다.
# 클래식 File Notification (레거시)
df = (spark.readStream
.format("cloudFiles")
.option("cloudFiles.format", "json")
.option("cloudFiles.useNotifications", True)
# AWS의 경우 추가 IAM 권한 및 cloudFiles.region 필요
.load("s3://my-bucket/landing/")
)File Events vs 클래식 File Notification 비교
아래 다이어그램은 두 방식의 구조적 차이를 한눈에 보여준다. File Events 방식은 여러 Auto Loader 스트림이 하나의 큐를 공유하는 반면, 클래식 방식은 스트림마다 별도 큐가 필요하다.
장점
- 대규모 수집에 최적화. 시간당 수백만 건의 파일을 처리할 수 있다.
- 감지 지연이 최소화. 파일 도착과 동시에 이벤트가 발행되므로 처리 지연이 거의 없다.
- API 비용이 절감. 스토리지 LIST API 호출 횟수가 Directory Listing 대비 대폭 줄어든다.
- 클라우드 리소스 한도를 피할 수 있다 (File Events). 버킷당 큐 한도에 걸릴 우려가 없다.
단점
- 초기 설정이 복잡하다. IAM 역할, SNS/SQS, Event Grid 등의 클라우드 권한 설정이 선행되어야 한다.
- 경로 변경이 불가하다. 소스 경로를 변경하면 기존 알림 리소스와 불일치가 생겨 파일 누락이 발생할 수 있다.
- Unity Catalog Volume은 클래식 방식을 지원하지 않는다. Volume 경로에는 File Events 방식만 사용 가능하다.
- 7일 이상 비활성 시 캐시 만료. File Events 캐시가 만료되면 자동으로 전체 디렉토리 리스팅으로 폴백된다.
4. 두 모드 핵심 비교 요약
| 항목 | Directory Listing | File Notification (File Events) |
|---|---|---|
| 기본값 여부 | ✅ 기본값 | 별도 설정 필요 |
| 설정 복잡도 | 낮음 (스토리지 읽기 권한만) | 중간 (Unity Catalog + External Location) |
| 파일 감지 지연 | 트리거 주기만큼 지연 | 거의 실시간 |
| 대용량 처리 | 파일 수 증가 시 성능 저하 | 시간당 수백만 파일 처리 가능 |
| 클라우드 API 비용 | 파일 수에 비례해 증가 | 최소화 |
| 클라우드 리소스 필요 | 없음 | 필요 (자동 생성 가능) |
| 경로 변경 | ✅ 지원 (DBR 11.3+) | ❌ 미지원 |
| Unity Catalog Volume | ✅ 지원 (DBR 13.3+) | ✅ 지원 (DBR 14.3+, File Events만) |
| 정확히 1회 처리 보장 | ✅ | ✅ |
| 모드 간 전환 | ✅ 체크포인트 유지하며 전환 가능 | ✅ |
| Databricks 권장 | 소규모·단순 환경 | ✅ 대부분의 워크로드 |
5. 클라우드 스토리지별 지원 매트릭스
| 클라우드 스토리지 | Directory Listing | File Notification (클래식) | File Notification (File Events) |
|---|---|---|---|
| AWS S3 | 전 버전 | 전 버전 | DBR 14.3+ |
| Azure ADLS | 전 버전 | 전 버전 | DBR 14.3+ |
| Google Cloud Storage | 전 버전 | 전 버전 | DBR 14.3+ |
| Azure Blob Storage | 전 버전 | 전 버전 | ❌ 미지원 |
| DBFS | 전 버전 | 마운트 포인트만 | DBR 14.3+ (External Location 필요) |
| Unity Catalog Volume | DBR 13.3+ | ❌ 미지원 | DBR 14.3+ |
6. 어떤 모드를 선택해야 하나?
파일 수가 수십만 개 이상이거나 시간당 수만 건을 처리해야 하는가?
└─ YES → File Notification (File Events) 사용
└─ NO ─┐
파이프라인이 수 개 이내이고, 경로 변경이 자주 필요한가?
└─ YES → Directory Listing 유지
└─ NO → File Notification (File Events)로 전환 권장실무에서는 아래 기준으로 판단하면 된다.
Directory Listing이 적합한 경우:
- PoC, 개발 환경처럼 빠르게 시작해야 할 때
- 파일 수가 적고 수집 지연이 몇 분 이내로 허용될 때
- 소스 경로가 주기적으로 바뀌는 경우 (예: 날짜별 경로 로테이션)
File Notification (File Events)이 적합한 경우:
- 프로덕션 환경, 특히 파일이 지속적으로 대량 도착하는 파이프라인
- 실시간에 가까운 감지 지연이 요구될 때
- Unity Catalog를 사용 중이고 External Location이 이미 설정된 환경
- 클라우드 API 비용을 최소화하고 싶을 때
7. Directory Listing에서 File Events로 마이그레이션
Databricks는 Directory Listing을 사용 중인 스트림을 File Events로 마이그레이션할 것을 공식 권고하고 있다. 전환 절차는 다음과 같다.
# 1단계: External Location에 File Events 활성화 (Unity Catalog에서 설정)
# Catalog Explorer → External Locations → 해당 Location → File Events 활성화
# 2단계: 기존 스트림에 옵션 추가 후 재시작
df = (spark.readStream
.format("cloudFiles")
.option("cloudFiles.format", "json")
.option("cloudFiles.useManagedFileEvents", True) # 이 줄 추가
.load("s3://my-bucket/landing/")
# 체크포인트 경로는 그대로 유지
)✅ 정확히 1회 처리 보장 유지: 체크포인트를 유지한 채 모드를 전환해도 Exactly-Once 처리 보장이 깨지지 않는다. 전환 시 첫 실행에서 전체 디렉토리 리스팅이 한 번 발생하지만 이후부터는 캐시 기반으로 동작한다.
마치며
Auto Loader의 두 파일 감지 모드는 단순한 옵션 차이가 아니라, 파이프라인 아키텍처 전략의 차이다.
Directory Listing은 진입 장벽이 낮고 유연하지만 규모에 한계가 있다. File Notification (File Events)은 초기 설정이 필요하지만 프로덕션 대규모 환경에서 압도적인 성능과 비용 효율을 보여준다.
Databricks 자체도 "대부분의 워크로드에 File Events 방식을 권장"한다고 명시하고 있다. 새로 파이프라인을 구성한다면 처음부터 File Events 방식으로 시작하고, 레거시 Directory Listing 스트림은 단계적으로 마이그레이션하는 것이 바람직하다.
참고 자료:
