DuckDB-Wasm이란? CSV를 서버에 올리지 않고 분석하는 구조

자료가 있는 기기 안에서 분석하는 방식을 비유한 AI 생성 이미지입니다.

CSV 분석 사이트에 파일을 끌어다 놓으면 표가 바로 나타납니다. 이때 SQL이 내 브라우저에서 실행됐는지, 파일이 서버에 업로드됐는지는 화면만 보고 알 수 없습니다. “WebAssembly 사용”과 “원본 파일 미전송”도 같은 문장이 아닙니다.

DuckDB-Wasm은 DuckDB 분석 엔진을 WebAssembly로 브라우저에서 실행할 수 있게 합니다. 덕분에 로컬 파일을 브라우저 안에서 읽고 SQL로 집계하는 웹앱을 만들 수 있지만, 실제 웹앱이 원격 URL이나 분석 API를 함께 호출할 가능성까지 없애주지는 않습니다.

브라우저 안에 분석 엔진을 올리는 구조

DuckDB-Wasm 공식 소개는 DuckDB를 WebAssembly로 컴파일해 브라우저에서 실행하고, 웹 워커를 이용해 메인 UI와 분석 작업을 분리하는 구성을 설명합니다.

사용자가 고른 CSV
  └─ 브라우저 File API
      └─ DuckDB-Wasm Worker
          ├─ CSV 파싱
          ├─ SQL 필터·그룹·조인
          └─ 결과 테이블
                └─ 화면 또는 로컬 다운로드

이 구조로 구현하면 원본 CSV를 별도 분석 서버에 보내지 않고도 집계할 수 있습니다. 서버가 필요 없는 것이 아니라 그 분석 경로에서 서버 업로드를 생략할 수 있다는 뜻입니다. 웹앱의 HTML·JavaScript·Wasm 파일은 처음에 서버나 CDN에서 내려받을 수 있고, 원격 데이터 URL을 읽는 기능도 따로 존재합니다.

작은 CSV에서는 무엇을 할 수 있나

공개 행사 목록을 예로 들어보겠습니다.

city,category,visitors
Seoul,conference,120
Busan,meetup,45
Seoul,meetup,80
Busan,conference,

브라우저에 이 파일을 등록했다면 SQL은 일반적인 분석 흐름과 같습니다.

SELECT
  city,
  COUNT(*) AS event_count,
  SUM(COALESCE(visitors, 0)) AS known_visitors
FROM events
GROUP BY city
ORDER BY event_count DESC, city;

예상 결과는 Seoul 2건·200명, Busan 2건·45명입니다. 여기서 COALESCE를 빼면 빈 방문자 값이 합계에서 어떻게 처리되는지 결과가 달라질 수 있습니다. 도구를 평가할 때 “쿼리가 실행됐다”보다 입력 행 수, 빈 값, 문자 인코딩, 집계 결과를 아는 작은 fixture가 유용한 이유입니다.

이 예시는 DuckDB-Wasm의 실제 성능 측정이 아니라 SQL 의미를 대조하기 위한 합성 데이터입니다.

데이터 입력 경로부터 구분합니다

DuckDB-Wasm 데이터 입력 문서는 브라우저 파일과 URL 등 여러 데이터 경로를 다룹니다. 같은 DuckDB-Wasm이라도 입력 경로에 따라 네트워크와 보안 경계가 달라집니다.

입력 경로	데이터가 시작하는 곳	확인할 네트워크 경계
사용자가 선택한 로컬 파일	내 기기	웹앱이 별도 업로드 요청을 만드는지
원격 URL	외부 서버	브라우저가 어느 도메인에서 무엇을 받는지
앱에 포함된 샘플	웹앱 배포 파일	샘플과 사용자 파일을 구분하는지
사용자가 붙여넣은 텍스트	클립보드·입력창	분석·오류 수집 요청에 원문이 포함되는지
결과 내보내기	브라우저 계산 결과	다운로드인지 서버 저장인지

현재 DuckDB-Wasm 입력 문서의 API 흐름을 축약하면 로컬 파일과 원격 파일은 이렇게 갈립니다.

const conn = await db.connect();

// 사용자가 고른 로컬 File 객체
await db.registerFileHandle('local.csv', pickedFile);
await conn.insertCSVFromPath('local.csv', {name: 'events'});

// 원격 파일 URL: 브라우저가 네트워크 요청을 만듦
await db.registerFileURL('remote.parquet', 'https://origin/data.parquet');
const result = await conn.query("SELECT * FROM 'remote.parquet' LIMIT 10");

await conn.close();

registerFileHandle은 파일 선택 경로를, registerFileURL은 원격 요청 경로를 드러냅니다. 실제 CSV 옵션, Parquet 확장, CORS와 브라우저 정책은 파일 형식과 런타임 설정에 따라 달라지므로 그대로 복사하기보다 현재 문서와 타입을 확인해야 합니다. 연결을 닫는 것도 사용이 끝난 뒤 메모리를 회수하기 위한 별도 단계입니다.

“클라이언트 측 처리”라는 소개 문구만으로 이 표를 채울 수는 없습니다. 실제 구현, 개인정보 처리 안내, 개발자 도구의 네트워크 기록을 함께 봐야 합니다.

공개 샘플로 파일 전송을 점검하는 순서

민감한 CSV를 넣기 전에 공개 가능한 샘플로 한 세션을 관찰합니다.

1. 새 브라우저 프로필이나 시크릿 창에서 도구를 엽니다.
2. 개발자 도구의 Network 탭을 열고 기록을 지웁니다.
3. 페이지 초기 로딩 요청과 파일 선택 이후 요청을 구분합니다.
4. 공개 샘플 CSV를 선택합니다.
5. 미리보기, SQL 실행, 필터, 결과 내보내기를 각각 수행합니다.
6. 새로 생긴 요청의 도메인, 메서드, 크기, 요청 본문을 확인합니다.
7. 앱을 새로고침하거나 탭을 닫은 뒤 자료가 남는지 확인합니다.

결과는 단정 대신 관찰로 적습니다.

관찰 환경: 브라우저·버전 / 날짜
입력: 공개 샘플 4행 CSV
관찰한 단계: 선택, 쿼리, CSV 내보내기
새 네트워크 요청: 도메인과 요청 종류
요청 본문에서 원문 발견 여부:
탭 재실행 뒤 데이터 잔존 여부:
확인하지 못한 경로: 오류, 로그인, 대용량, 다른 브라우저

한 세션에서 업로드 요청을 찾지 못했다고 서비스의 모든 코드 경로가 영원히 전송하지 않는다고 결론 내릴 수는 없습니다. 분석 오류, 로그인, 협업 저장, 원격 측정, 업데이트된 코드에서는 다른 요청이 생길 수 있습니다. 민감 자료라면 배포 코드를 자체 호스팅하거나 네트워크를 차단한 환경에서 검증하는 등 더 강한 근거가 필요합니다.

브라우저에 남는 것도 확인합니다

서버 전송이 없더라도 데이터가 브라우저 저장소에 남을 수 있습니다. IndexedDB, 캐시, 다운로드 파일, 자동 복구 기능의 존재는 제품마다 다릅니다. 공용 컴퓨터에서는 탭을 닫았다는 사실만으로 자료 삭제를 가정하지 마세요.

확인할 항목은 네 가지입니다.

축	질문
계산	SQL 엔진과 파싱이 어느 프로세스에서 실행되는가
전송	원본·일부 행·쿼리·오류가 외부 요청에 포함되는가
저장	브라우저 저장소·서버 계정·다운로드에 무엇이 남는가
접근	같은 기기의 다른 사용자나 사이트가 결과에 접근할 수 있는가

개인정보 보호 판단은 이 네 축을 모두 확인한 뒤 내려야 합니다.

큰 파일에서는 메모리와 작업 방식을 따로 봅니다

브라우저에서 실행된다는 사실은 무제한 크기나 일정한 속도를 보장하지 않습니다. CSV 파싱, 정렬, 조인, 그룹 집계는 파일 크기와 열 형식, 질의에 따라 메모리 사용량이 달라집니다. 기기 RAM이 충분해도 브라우저와 탭이 사용할 수 있는 자원에는 제약이 있을 수 있습니다.

도입 시험은 세 단계로 나누는 편이 좋습니다.

1. 의미 확인: 정답을 아는 작은 fixture로 행 수와 집계를 대조합니다.
2. 형식 확인: 실제와 같은 인코딩, 구분자, 날짜, null, 긴 문자열을 넣습니다.
3. 규모 확인: 공개 가능한 데이터로 실제와 비슷한 파일 크기와 질의를 시험합니다.

각 단계에서 로드 시간, 쿼리 시간, 최고 메모리, 실패 메시지, 취소 가능 여부를 기록합니다. 이 글은 직접 벤치마크를 수행하지 않았으므로 최대 행 수나 처리 속도를 제시하지 않습니다.

언제 DuckDB-Wasm을 검토할 만한가

• 사용자가 가진 CSV·Parquet를 브라우저에서 즉시 탐색해야 할 때
• 서버 업로드를 줄이는 것이 제품 요구사항일 때
• SQL 집계 결과만 내려받으면 되는 일회성 도구일 때
• 정적 사이트나 교육용 SQL 실습처럼 서버 상태를 최소화하려 할 때

반대로 중앙 권한 관리, 공유 상태, 정기 배치, 장시간 작업, 서버 데이터와의 조인, 감사와 재현이 핵심이면 서버 측 분석이 더 단순할 수 있습니다. 브라우저 실행을 선택하면 배포되는 코드, 브라우저 호환성, 사용자의 기기 성능도 운영 범위에 들어옵니다.

정리

DuckDB-Wasm은 브라우저 안에서 DuckDB SQL을 실행할 수 있게 합니다. 로컬 파일을 브라우저에서 직접 읽도록 구현하면 원본을 분석 서버에 올리는 단계를 생략할 수 있습니다. 그러나 Wasm이라는 기술 이름은 웹앱 전체의 미전송·미보관 인증서가 아닙니다.

도구를 고를 때 계산 위치, 입력 경로, 네트워크 전송, 브라우저·서버 보관을 나눠 확인하세요. 먼저 정답을 아는 공개 샘플로 SQL 의미와 네트워크를 점검하고, 실제와 비슷한 공개 가능한 크기로 성능 시험을 넓히는 순서가 안전합니다.

자료 확인일과 한계

자료 확인일은 2026년 9월 7일입니다. DuckDB-Wasm 공식 소개와 현재 데이터 입력 문서를 기준으로 작성했습니다.

특정 웹 서비스의 파일 미전송, 개인정보 보호, 브라우저별 호환성, 최대 파일 크기와 성능을 직접 검증한 글은 아닙니다. SQL 예시와 네트워크 점검 절차는 공개 샘플로 확인할 수 있는 편집적 제안입니다.