DuckDB Wasm 클라이언트

DuckDB-Wasm은 DuckDB를 WebAssembly로 컴파일한 버전이에요. 브라우저가 거의 네이티브 속도로 실행할 수 있는 휴대용 바이너리 포맷이라, 서버 없이도 브라우저 안에서 온전한 DuckDB 엔진을 돌릴 수 있답니다. 함께 알아볼까요?

출처: 문서

본문

설치: DuckDB Wasm 클라이언트를 사용하려면 duckdb-wasm GitHub 저장소를 방문하세요.

DuckDB WebAssembly 클라이언트의 최신 안정 버전은 {% if site.current_duckdb_wasm_version != "" %}{{ site.current_duckdb_wasm_version }}{% else %}{{ site.lts_duckdb_wasm_version }}{% endif %}이에요.

DuckDB-Wasm은 DuckDB를 WebAssembly로 컴파일한 버전이에요. WebAssembly는 브라우저가 거의 네이티브 속도로 실행할 수 있는 휴대용 바이너리 포맷이에요. 이 덕분에 완전한 DuckDB 엔진이 쿼리를 보낼 서버도, 사용자의 머신을 떠나는 데이터도 없이, 어떤 기기의 어떤 브라우저 안에서든 완전히 실행될 수 있어요.

다양한 요구에 맞는 계층형 API를 제공해요:

이 페이지는 설치와 기본 사용법을 다루고, 이 섹션의 다른 페이지들은 클라이언트 인스턴스화, 데이터 가져오기, 쿼리 실행, 확장 로드, 배포를 다뤄요.

직접 해보기 (Try It Yourself)

아래 셸은 브라우저에서 실행되는 완전한 DuckDB 엔진이에요 — SQL 쿼리를 입력하고 바로 여기에서 실행해 보세요:

{% include iframe.html src="https://shell.duckdb.org" %}

참고 위 셸은 그 자체로 DuckDB-Wasm으로 빌드된 거예요. 위에 나열한 계층형 API 중 하나인 @duckdb/duckdb-wasm-shell 패키지로, 이 페이지가 설명하는 것과 동일한 DuckDB-Wasm 라이브러리 위에서 동작해요. 입력하는 모든 쿼리는 서버 왕복 없이 WebAssembly에서 클라이언트 측에서 실행돼요. 그래서 여러분의 애플리케이션이 DuckDB-Wasm을 임베드했을 때 얻을 수 있는 것의 실시간 데모인 셈이에요.

설치 (Installation)

DuckDB-Wasm은 npm에 @duckdb/duckdb-wasm으로 게시돼요. 패키지 매니저로 설치하세요:

npm install @duckdb/duckdb-wasm

이것은 현재 안정 릴리스(latest 태그)를 설치해요. 대신 가장 최신의, 릴리스되지 않은 빌드를 시험해 보려면 npm install @duckdb/duckdb-wasm@next로 next 태그를 설치하세요. next는 main 브랜치를 추적하며 프로덕션보다는 테스트용으로 설계되었어요.

또는 아무것도 설치하지 않고 jsDelivr 같은 CDN에서 사전 빌드된 번들을 직접 로드할 수도 있어요. 번들 선택 옵션은 [Instantiate]({% link docs/current/clients/wasm/instantiation.md %})를 참고하세요. 설정 없이 대화식으로 시험해 보려면 DuckDB-Wasm Web shell을 사용하세요.

기본 API 사용법 (Basic API Usage)

아래 예시는 CDN 번들에서 DuckDB-Wasm을 인스턴스화하고, 연결을 열고, 쿼리를 실행하고, 결과를 읽어요. [Instantiate]({% link docs/current/clients/wasm/instantiation.md %})는 webpack, Vite, 셀프 호스팅 파일 같은 번들 로드의 다른 방법들을 다뤄요.

외부에서 호스팅되는 DuckDB-Wasm API Reference에서 모든 클래스와 메서드에 대한 자세한 내용을 참고하세요. [DuckDB-Wasm 출시 블로그 포스트]({% post_url 2021-10-29-duckdb-wasm %})도 좋은 소개예요.

import * as duckdb from '@duckdb/duckdb-wasm';

// jsDelivr 번들에서 DuckDB-Wasm 인스턴스화
const bundle = await duckdb.selectBundle(duckdb.getJsDelivrBundles());
const worker = new Worker(bundle.mainWorker!);
const db = new duckdb.AsyncDuckDB(new duckdb.ConsoleLogger(), worker);
await db.instantiate(bundle.mainModule, bundle.pthreadWorker);

// 연결을 열고 쿼리 실행
const conn = await db.connect();
const result = await conn.query('SELECT 42 AS answer');
console.log(result.toArray()[0].answer); // prints 42

// 리소스 해제
await conn.close();
await db.terminate();
await worker.terminate();

DuckDB-Wasm은 어떻게 동작하나요? (How DuckDB-Wasm Works)

DuckDB-Wasm은 데이터 가져오기와 쿼리 결과 모두에서 Apache Arrow를 데이터 프로토콜로 사용해요. Arrow는 데이터베이스 친화적인 컬럼형 포맷으로, apache-arrow npm 패키지가 브라우저에서 구현해 줘요. 덕분에 DuckDB-Wasm은 JavaScript에서 SQL 타입 로직을 다시 구현하지 않아도 데이터를 효율적으로 교환하고 다른 JavaScript 데이터 도구와 상호운용할 수 있어요.

DuckDB-Wasm은 로컬 파일, 원격 HTTP(S) 서버, 인메모리 버퍼를 균일하게 취급하는 가상 파일시스템 위에 구축돼 있어요.

DuckDB가 Parquet 같은 파일 포맷을 이해하기 때문에, 전체 파일을 다운로드하는 대신 쿼리가 필요한 바이트만 읽어요: SELECT count(*) FROM 'file.parquet'는 파일 메타데이터만으로 답할 수 있고, 선택적 필터나 LIMIT … OFFSET 절로 전체 행 그룹을 건너뛸 수 있어요. 이 덕분에 원격 서버에 호스팅된 대형 Parquet 파일을 브라우저에서 직접 쿼리하는 것이 실용적이에요.

참고 이 부분 읽기 동작은 어떤 httpfs 경로가 요청을 처리하느냐에 따라 달라요. JavaScript httpfs 구현은 필요한 바이트 범위만 가져오지만, 내장 httpfs 확장으로 읽으면 현재는 전체 파일을 다운로드할 수도 있어요 (duckdb-wasm issue #2153 참고).

제한 사항 (Limitations)

기본적으로 WebAssembly 클라이언트는 단일 스레드만 사용해요. 멀티스레딩은 사용 가능하지만 아직 실험적이에요.
WebAssembly 클라이언트는 사용 가능한 메모리 양이 제한돼 있어요. WebAssembly는 사용 가능한 메모리를 4 GB로 제한하고 브라우저가 더 엄격한 제한을 부과할 수도 있어요.

이 제한에 부딪혔을 때의 해결 방법은 [Troubleshoot]({% link docs/current/clients/wasm/troubleshoot.md %})를 참고하세요.

더 읽을거리 (Further Reading)

[Instantiate]({% link docs/current/clients/wasm/instantiation.md %}) — jsDelivr, webpack, Vite, 정적 서빙 파일을 위한 번들 선택 패턴.
[Import Data]({% link docs/current/clients/wasm/data_ingestion.md %}) — 파일 등록 및 Apache Arrow, CSV, JSON, Parquet 데이터 삽입.
[Run Queries]({% link docs/current/clients/wasm/query.md %}) — 구체화 및 스트리밍 쿼리, 준비된 문, 결과 내보내기.
[Load Extensions]({% link docs/current/clients/wasm/extensions.md %}) — 확장 로드가 네이티브 DuckDB와 어떻게 다른지와 사용 가능한 확장.
[Deploy]({% link docs/current/clients/wasm/deploying_duckdb_wasm.md %}) — 배포가 서빙하는 구성 요소와 관련 보안 고려 사항.
[Troubleshoot]({% link docs/current/clients/wasm/troubleshoot.md %}) — CORS 에러, 메모리 제한, 스레딩을 포함한 일반적인 이슈와 해결 방법.
[Clients Overview]({% link docs/current/clients/overview.md %}) — DuckDB가 Wasm과 함께 제공하는 다른 클라이언트 API.

DuckDB Wasm 클라이언트