소속팀: Developer팀 작성자: 유수영
“업로드 완료” 다음에 필요한 설명이 있습니다.
어떤 문서인지 확인하고, 재전송과 개정을 구분해야 합니다. 변경된 내용이 검색까지 이어졌는지도 살펴야 합니다. 기존 프로젝트의 수집·등록 설계를 따라, 파일 도착을 AI 활용 준비 데이터로 연결해 봅니다.
1. 업로드했는데 왜 예전 내용이 검색될까요? 💬
오전 9시, 담당자가 새 상품 안내문을 올렸습니다. 전송은 끝났는데 검색에는 이전 안내가 나옵니다. 다시 올려도 달라지지 않자 전송이 실패했다고 생각합니다.
실제로는 원문이 도착했을 수 있습니다. 문서 번호와 적용 정보를 담은 대장을 기다리는 중일 수 있습니다. 등록과 정제는 끝났지만 검색 반영만 남았을 수도 있습니다.
같은 화면 증상이어도 해결할 일은 다릅니다. 수집 체계는 지금 어느 단계에 있는지 설명해야 합니다. 사용자에게는 내부 실행 번호보다 대기 이유와 다음 조치가 필요합니다.
그림 1. 원문을 식별 가능한 데이터로 정리하는 AI 생성 일러스트입니다. 실제 Databricks 화면은 아닙니다.
| 사용자에게 보이는 상태 | 확인할 사실 | 다음 행동 |
|---|---|---|
| 접수 확인 중 | 저장소 도착과 접근 가능 여부 | 전송 완료 확인 |
| 문서 정보 대기 | 원문에 연결할 정보 부족 | 대장 도착 또는 필수 정보 보완 |
| 문서 등록 완료 | 원문과 업무 식별 연결 | 내용 정리와 검증 대기 |
| 검색 반영 중 | 검색용 결과는 있으나 갱신 미완료 | 검색 단계 진행 확인 |
| 검색 반영 확인 | 현재 개정과 검색 결과 일치 | 대표 질문으로 근거 검토 |
상태명은 사용자 설명을 위한 예시입니다. 실제 상태와 화면 문구를 연결하는 규칙은 서비스에서 정합니다. 등록 완료와 검색 완료를 같은 표시로 묶지 않는 것이 핵심입니다.
2. 파일 도착과 테이블 변경은 다른 신호입니다 🧭
현재 사례의 수집과 정제는 파일 도착 기반으로 연결됩니다. 원문과 대장을 받아 등록 정보를 만들고, 후속 작업이 처리할 입력을 발견합니다. CDF가 모든 수집 단계를 연결하는 구조는 아닙니다.
CDF는 테이블에서 바뀐 행을 전달할 때 사용합니다. 뒤의 실습은 테이블 기반 연동을 이해하기 위한 별도 예시입니다. 현재 구현과 확장 예시를 구분하면 각 기능의 책임이 명확해집니다.

그림 2. 수집의 목표는 최신 문서와 출처를 검색에 전달하는 것입니다. 기존 개념도와 draw.io 원본을 유지했습니다.
| 확인할 질문 | 담당하는 기능·규칙 |
|---|---|
| 새 자료가 오면 언제 시작할까 | 파일 도착 트리거 |
| 아직 읽지 않은 파일은 무엇인가 | Auto Loader와 체크포인트 |
| 이 자료는 어떤 업무 문서인가 | 문서 대장과 식별 규칙 |
| 테이블의 어느 행이 바뀌었나 | CDF |
| 이용자가 최신 근거를 찾는가 | 게시·검색 검증 |
Auto Loader는 새 파일을 증분으로 읽는 기반입니다. 업무상 같은 문서인지는 별도의 등록 규칙으로 판단합니다. 기본 동작은 Auto Loader 공식 설명을 참고합니다.

그림 3. 원문과 대장을 연결한 뒤에도 내용 정리와 검색 갱신이 남습니다. CDF 부분은 테이블 변경 연동의 확장 예시입니다.
3. 문서 대장은 제목보다 안정적인 연결을 만듭니다 🗂️
“상품 안내”라는 제목은 여러 부서에서 사용할 수 있습니다. 같은 문서도 개편하면서 제목이 바뀝니다. 제목만으로 문서를 식별하면 서로 다른 자료가 섞이기 쉽습니다.
이번 사례는 외부 식별자가 제공되면 이를 우선합니다. 사용 가능한 문서 번호를 정규화해 원문과 연결합니다. 대장을 사용하지 않는 자동 식별 정책과는 구분합니다.
문서 번호는 같은 업무 문서를 계속 가리킵니다. 원문 참조값은 이번에 받은 자료를 가리킵니다. 이 둘을 연결해야 개정 전후에도 출처를 설명할 수 있습니다.
그림 4. 검색 근거를 원문과 연결하는 AI 생성 일러스트입니다. 문서 식별과 출처 연결의 의미를 표현했습니다.
샘플 대장으로 전달 규칙 읽어 보기
아래 데이터는 설명용입니다. 실제 운영의 필드명이나 저장 구조를 그대로 옮기지는 않았습니다.
|
{ |
|---|
오늘 접수한 문서가 다음 달부터 적용될 수도 있습니다. 접수 시각과 원문 수정 시각, 업무 적용일을 구분합니다. 가장 늦게 업로드됐다는 이유만으로 지금 적용할 자료라고 판단하지 않습니다.
| 항목 | 연결할 의미 |
|---|---|
| 문서 식별자 | 같은 업무 문서를 계속 추적 |
| 원문 개정 | 내용 변경과 순서를 구분 |
| 표시 제목 | 검색 결과에 보여줄 이름 |
| 원문 참조 | 이번에 전달한 실제 자료 |
| 적용 정보 | 이용 가능한 시점과 범위 |
| 변경 의도 | 갱신과 명시적 철회를 구분 |
잘못된 대장은 일찍, 구체적으로 알려주기
대장이 열렸다는 사실과 올바른 원문에 연결된다는 사실은 다릅니다. 다음 Python은 필수 문자열과 중복 식별자를 확인합니다. 한 묶음에 문서별 원문이 하나씩 온다는 샘플 계약입니다.
|
import unicodedata |
|---|
NFC 정규화는 같은 한글의 서로 다른 문자 표현을 맞춥니다. 서로 다른 업무 번호를 하나로 합치는 규칙은 아닙니다. 열 중복, 인코딩, 원문 위치의 허용 범위는 입력 처리 단계에서 추가로 확인합니다.
오류에는 해당 행과 수정할 항목을 알려줍니다. “대장 오류”보다 “3행의 문서 번호가 중복됩니다”가 수정하기 쉽습니다. 🛠️
4. Auto Loader로 수신 사실부터 남깁니다 📦
PDF나 이미지는 우선 바이트와 파일 속성으로 받을 수 있습니다. 본문 해석을 뒤로 나누면 변환에 실패해도 도착 사실은 추적할 수 있습니다. 아래는 Databricks Spark 세션에서 사용하는 함수 정의 예제입니다.
호출 시 입력 위치, 전용 체크포인트 위치, 샘플 Delta 테이블을 전달합니다. 입력과 체크포인트는 다른 위치로 지정하고 접근·쓰기 권한을 확인합니다. 함수를 호출하면 수신 기록을 저장하므로 별도 실습 대상을 사용합니다.
|
from pyspark.sql import functions as F |
|---|
이 코드는 수신 속성과 내용 지문을 남깁니다. 원문 보존, 문서 번호 연결, 업무 중복 제거, 검색 등록까지 하는 완성 파이프라인은 아닙니다. 대용량 원문은 바이트를 읽는 비용과 메모리 사용도 확인합니다.
덮어쓰기를 허용할지는 전달 계약에 맞추기
샘플은 개정마다 새 객체를 전달한다고 가정합니다. 그래서 cloudFiles.allowOverwrites를 false로 지정했습니다. 현재 구현에는 변경 원문을 다시 읽도록 덮어쓰기를 허용하는 경로도 있습니다.
덮어쓰기 재수집을 켜도 모든 중간 개정을 보존한다고 가정할 수 없습니다. 같은 입력을 다시 받을 가능성도 고려해야 합니다. 정확한 동작은 Auto Loader FAQ를 참고합니다.
모든 개정을 남겨야 한다면 생산 측에서 개정별 원문을 구분해 전달합니다. 수집 옵션과 업무 이력 보존은 함께 설계할 문제입니다.
500개는 실행 전체의 한도가 아닙니다
예제의 500개는 마이크로배치 한 묶음의 파일 수 제한입니다. AvailableNow 실행은 시작 시점의 가용 입력을 여러 묶음으로 처리할 수 있습니다. 대기 파일이 1,200개라고 실행을 반드시 세 번 시작할 필요는 없습니다.
체크포인트는 이어서 읽을 위치를 관리합니다. 기존 파일 포함 옵션을 바꾸는 것만으로 과거 입력이 다시 처리되지는 않습니다. 초기화 조건과 옵션의 범위는 Auto Loader 옵션을 확인합니다.
5. 실행이 시작됐는지부터 확인해 봅니다 ⏱️
파일 도착 트리거는 실행 시점을 정합니다. Auto Loader는 실행 안에서 처리할 입력을 읽습니다. 두 기능을 분리해서 봐야 “아직 시작 안 됨”과 “처리 중”을 구분할 수 있습니다.
| 설정 | 이 사례의 기본값 | 의미 |
|---|---|---|
| 최소 트리거 간격 | 300초 | 너무 잦은 실행 생성을 제한 |
| 마지막 변경 이후 대기 | 60초 | 연속 도착 자료가 모일 시간을 확보 |
| 수집 방식 | 가용 입력 처리 후 종료 | 상시 실행과 구분 |
300초는 5분마다 반드시 실행한다는 뜻이 아닙니다. 연속 도착은 마지막 변경 이후 대기 시간에 영향을 줍니다. 검색 반영 시간의 보장값도 아닙니다. 파일 도착 트리거 안내
같은 객체의 덮어쓰기가 새 실행을 반드시 만든다고 가정하지 않습니다. 시작 조건과 재수집 동작을 각각 확인합니다. 이 사례의 승인 입력도 수신 처리상의 상태이며, 별도 보안 연동 여부는 따로 확인합니다.
화면 1. 전달 시각에 대응하는 실행 찾기
실행 목록에서 시작 시각과 상태를 확인합니다. 자료 도착 이후의 실행이 없다면 트리거와 접근 조건부터 봅니다. 실행이 있다면 상세 화면에서 입력 범위를 좁힙니다.
오래 걸리는 실행과 바로 실패한 실행은 원인이 다를 수 있습니다. 실행 시간과 오류 코드를 함께 확인합니다. 작업 이름과 수치는 공식 문서의 예시입니다.
Job 성공이 모든 문서의 검색 준비를 뜻하지는 않습니다. 문서 정보 대기와 검색 반영 대기는 업무 상태에서도 확인합니다.
화면 1. 공식 실행 목록 예시이며 이 프로젝트의 운영 화면은 아닙니다. 출처: Lakeflow Jobs 모니터링. 문서 재확인일: 2026-11-16.
6. 재전송·개정·정보 수정을 나누어 보기 🔎
원문 해시는 바이트가 같은지 비교하는 데 유용합니다. 하지만 제목이나 분류가 바뀌어도 바이트는 같을 수 있습니다. PDF 생성 정보만 달라져 바이트가 바뀌는 경우도 있습니다.
따라서 바이트 변경은 재검토 신호로 봅니다. 업무적 개정의 의미는 별도 규칙으로 판단합니다. 다음 예제는 원문 변화와 업무 정보 변화를 구분합니다.
|
from hashlib import sha256 |
|---|
여러 항목이 바뀌면 위쪽 조건을 우선하는 최소 예제입니다. 실제로는 변경 항목도 남기고, 업무 개정 번호와 이용 조건을 비교 범위에 포함합니다. 입력 형식은 앞 단계에서 검증했다고 가정합니다.
| 변화 | 재사용을 검토할 결과 | 새로 확인할 결과 |
|---|---|---|
| 같은 자료 재전송 | 검증된 원문·본문 | 동일 개정과 결과 유효성 |
| 제목만 수정 | 제목과 무관한 본문 변환 | 검색 표시 정보와 모델 입력 |
| 본문 개정 | 영향 없는 공통 설정 | 본문·분할·임베딩·검색 |
| 적용 대상 변경 | 영향 없는 본문 결과 | 검색 범위와 유효 상태 |
| 명시적 철회 | 보존할 이력 | 검색 제외와 반영 결과 |
제목을 임베딩 입력에 붙이는 설계라면 제목 수정도 재계산 사유가 됩니다. 무엇을 다시 만들지는 변경 이름보다 실제 입력 의존성으로 결정합니다.
7. 원문과 대장의 도착 순서가 달라도 연결하기 🔗
원문이 먼저 오면 문서 정보를 기다릴 수 있습니다. 대장이 먼저 오면 원문 도착을 다시 확인할 기회가 필요합니다. 처음 연결되지 않았다는 이유만으로 영구 실패로 처리하지 않습니다.

그림 5. 두 입력이 갖춰지면 연결을 검증하고 등록합니다. 대기 시간의 초과 기준과 알림 대상은 업무별로 정합니다.
| 현재 상황 | 설명할 상태 |
|---|---|
| 원문만 있음 | 문서 정보 대기 |
| 대장만 있음 | 원문 대기 |
| 대장의 필수 정보가 잘못됨 | 대장 수정 필요 |
| 두 입력과 연결 검증이 완료됨 | 등록 가능 |
대장이 늦게 도착하면 대기하던 원문을 다시 연결해야 합니다. 현재 사례에는 같은 원문을 가리키면서 정보 변경을 알리는 도착 신호가 있습니다. 등록 정보를 저장한 다음 후속 신호를 전달하는 순서가 중요합니다.
신호만 먼저 도착하면 후속 작업이 불완전한 정보를 읽을 수 있습니다. 정보 저장 후 신호 전달이 실패했다면 해당 지점부터 복구할 수 있어야 합니다.
📌 대장이 이번 전달 묶음인지 전체 목록인지도 정합니다. 이 글은 묶음별 대장을 가정합니다. 이전 대장의 정보를 무조건 섞으면 잘못된 원문과 연결될 수 있습니다.
8. CDF는 테이블에서 바뀐 행을 전달합니다 🔄
수신 정보나 문서 상태를 Delta 테이블에 저장할 수 있습니다. 그 변경을 다른 처리에서 읽고 싶을 때 CDF가 유용합니다. 파일 발견과 테이블 변경은 서로 다른 관찰 지점입니다.
| 구분 | Auto Loader | CDF |
|---|---|---|
| 관찰 대상 | 저장소 파일 | 테이블 행의 변화 |
| 질문 | 무엇을 아직 읽지 않았나 | 어느 버전에서 무엇이 바뀌었나 |
| 재개 기준 | 파일 처리 진행 상태 | 테이블 변경 처리 진행 상태 |
CDF는 삽입, 수정 전후 값, 삭제를 구분하는 메타데이터를 제공합니다. 수정 전후 행을 모두 현재 문서로 반영하지 않도록 변경 유형을 읽습니다. 기능과 조건은 Databricks CDF 설명을 참고합니다.
SQL로 제목 수정 전후를 관찰하기
다음은 별도 실습 스키마에 새 Delta 테이블을 만드는 예제입니다. 카탈로그와 스키마를 선택한 뒤, 같은 이름의 테이블이 없는 곳에서 실행합니다. 기존 테이블을 자동으로 지우거나 교체하지 않습니다.
예제는 테이블 속성으로 활성화하는 기존 방식의 CDF를 사용합니다. 자동 CDF를 지원하는 환경은 적용 조건이 다르므로 구분해서 확인합니다.
|
CREATE TABLE document_registry_demo ( |
|---|
결과에는 신규 등록과 제목 수정 전후 값이 나타납니다. 테이블 커밋 버전과 문서의 업무 개정 번호는 다른 정보입니다. 제목 수정만으로 업무 개정 번호를 올릴지는 별도 정책입니다.
모든 행 변경을 원문 재처리로 해석하지 않기
완료 시각을 기록한 것도 행 변경입니다. 이를 새 입력으로 해석하면 자신이 남긴 상태 때문에 재처리를 반복할 수 있습니다. 후속 작업의 입력에 영향을 주는 변경인지 판단합니다.
| 행의 변화 | 후속 판단 |
|---|---|
| 원문 지문 변경 | 원문과 정제 결과 재검토 |
| 제목·분류 변경 | 표시 정보와 모델 입력 영향 확인 |
| 완료 시각만 변경 | 원문 재처리 사유로 쓰지 않음 |
| 유효 상태 비활성화 | 검색 제외 요청 확인 |
| 행 삭제 | 업무 철회인지 저장 관리인지 계약 확인 |
전후 값을 비교할 때는 같은 식별자와 커밋 범위의 짝을 맞춥니다. 여러 변경을 합친 묶음에서 임의의 이전 행과 비교하지 않습니다. CDF는 영구 이력 저장소가 아니므로 재개 가능한 보존 범위도 확인합니다.
9. 다시 실행해도 업무 문서가 늘어나지 않도록 ♻️
체크포인트는 스트림 진행 위치를 추적합니다. 업무상 같은 문서인지 판단하는 대장은 아닙니다. 특히 사용자 정의 배치 처리에서는 같은 입력을 다시 받을 수 있습니다.
foreachBatch는 기본적으로 한 번 이상 쓰기를 보장합니다. 반복 적용에도 결과가 같도록 키와 갱신 조건을 정합니다. 보장 범위는 사용자 정의 배치 처리 안내를 참고합니다.
메모리 예제로 재전송과 개정 충돌 확인하기
샘플은 정수 개정 번호가 순서를 나타낸다고 가정합니다. 동일 개정의 재전송은 유지하고, 같은 개정에 다른 내용이 오면 충돌로 봅니다. 실제 저장소의 동시 실행과 트랜잭션을 구현한 코드는 아닙니다.
|
def apply_revision(current_documents, incoming): |
|---|
업무 정보만 바뀌는 경우는 앞의 변경 분류와 연결해 별도로 갱신합니다. 실제 지문에는 샘플 문자열 대신 수집 시 계산한 값을 사용합니다. 등록 정보와 후속 신호가 따로 저장된다면 부분 완료도 복구 대상으로 남깁니다.
철회는 목록에서 안 보이는 것과 다릅니다
파일 누락은 접근 문제나 전송 시점 차이일 수 있습니다. 이번 사례는 누락만으로 삭제를 추론하지 않고 명시적인 요청을 구분합니다. 철회 시 문서의 유효 상태와 검색 제외, 원문 보존을 각각 확인합니다.
검색에서 제외됐다고 보관 원문까지 삭제된 것은 아닙니다. 이미 만들어진 답변이나 캐시의 처리 범위도 서비스 정책으로 정합니다. 수집 기능 하나가 이 모든 동작을 자동으로 해결하지는 않습니다.
10. 지연을 파일 수와 업무 상태로 나누어 보기 📊
화면 2. 실행 안에서 시간이 쓰이는 곳 찾기
지원되는 환경에서는 실행 상세와 Spark UI를 연결해 확인합니다. 공식 화면에는 Jobs, Stages, Structured Streaming 탭이 보입니다. 메뉴는 컴퓨팅 종류와 권한, 제품 버전에 따라 달라질 수 있습니다.
대기 파일 수와 대기 바이트를 함께 봅니다. 파일 수가 같아도 대형 문서가 몰리면 처리 시간이 달라집니다. 배치 시간에서는 발견·읽기·계산·저장 중 느린 구간을 찾습니다.
문서 정보 대기와 검색 반영 대기는 업무 상태를 집계해야 알 수 있습니다. 파일 처리량과 검색 가능한 문서 수를 같은 지표로 표시하지 않습니다.
화면 2. 공식 Spark UI 진입 화면으로, 스트리밍 지표 자체의 캡처는 아닙니다. 출처: Spark UI 디버깅 안내. 문서 재확인일: 2026-11-16.
| 관찰 항목 | 확인할 질문 |
|---|---|
| 대기 파일 수 | 입력 증가가 처리 속도보다 빠른가 |
| 대기 바이트 | 대형 문서가 몰렸는가 |
| 배치 처리 시간 | 어느 처리 구간이 느린가 |
| 문서 정보 대기 수 | 대장이 늦게 도착하는가 |
| 검색 반영 대기 수 | 수집 이후 단계에서 지연되는가 |
스트림 지표는 Auto Loader 모니터링 문서를 참고합니다. 업무 상태를 집계할 때는 현재 개정에 연결된 결과인지 확인합니다. 이전 개정의 성공을 새 개정의 성공으로 합산하면 최신성 문제가 숨겨집니다.
11. 한 문서의 생애주기로 검증합니다 🧪
정상 파일 한 건의 성공만으로 검증을 마치지 않습니다. 같은 문서를 다시 보내고, 정보를 고치고, 개정하고, 철회해 봅니다. 문서 식별은 유지되면서 필요한 변화가 반영되어야 합니다.
| 시험 입력 | 기대하는 결과 |
|---|---|
| 원문 먼저, 대장 나중 | 대기 이유를 남기고 도착 후 연결 |
| 같은 자료 재전송 | 업무 중복 없이 결과 유효성 확인 |
| 제목만 수정 | 표시 정보와 계산 영향 확인 |
| 원문 개정 | 현재 개정과 검색 근거 일치 |
| 이전 개정 지연 도착 | 최신 결과를 무조건 덮어쓰지 않음 |
| 명시적 철회 | 상태 변경과 검색 제외 확인 |
| 파일 일시 누락 | 철회로 자동 해석하지 않음 |
등록 저장 뒤, 신호 전달 전, 검색 반영 전에 실패하는 경우도 시험합니다. 재개 후 누락과 중복을 찾을 수 있는 이력이 남아야 합니다. 체크포인트 삭제를 첫 해결책으로 삼지 않습니다.
보낸 자료와 받은 자료가 각각 100건이어도 대상은 다를 수 있습니다. 식별자와 개정, 수신 결과를 먼저 대응시킨 뒤 집계합니다. 재전송과 철회를 건수에 포함하는 기준도 함께 정합니다.
✅ 사용자 안내는 현재 남아 있는 일을 설명합니다. “다시 올려 주세요”보다 “원문은 접수됐고 문서 번호 연결을 기다립니다”가 구체적입니다. 이 차이가 담당자의 불필요한 재작업을 줄이는 데 도움이 됩니다.
12. 결론: 수신 사실을 최신 검색 근거로 연결하기 🌱
좋은 수집은 파일 도착을 업무에서 사용할 수 있는 문서 상태로 연결합니다. Auto Loader의 진행 추적에 안정적인 식별과 개정 구분을 더합니다. 명시적 철회와 다시 처리할 범위도 함께 관리합니다.
CDF를 사용해도 변경의 업무 의미는 별도로 정의해야 합니다. 파일 도착과 테이블 변경, 검색 반영은 서로 다른 완료 조건입니다. 각 조건을 연결하면 운영자와 문서 담당자가 같은 상태를 보고 이야기할 수 있습니다.
이용자는 지금 적용할 근거를 찾고 원문으로 돌아가 검토할 수 있어야 합니다. 그 연결을 유지하는 수집 설계가 AI Ready Data의 기반이 됩니다. 🤝
참조 출처 📚
- Auto Loader 개요 — 파일 증분 수집
- Auto Loader FAQ — 덮어쓰기와 중복 처리
- Spark API 옵션 — 수집·스트리밍 설정
- 파일 도착 트리거 — 시작 조건과 대기 시간
- CDF 안내 — 변경 유형, 설정, 보존 범위
- 사용자 정의 배치 처리 — 재실행과 쓰기 보장
- Auto Loader 모니터링 — 대기량과 처리 지표
- Lakeflow Jobs 모니터링 — 화면 1 출처
- Spark UI 디버깅 — 화면 2 출처
태그 🏷️
#Databricks #DBX #AutoLoader #CDF #AIReadyData #문서관리 #증분수집 #개정관리