DuckDB-Wasm でブラウザ内 SQL を動かす

検証日: 2026-09-22(初版 2026-05-26)

使用バージョン: @duckdb/duckdb-wasm@1.33.1-dev45.0(DuckDB v1.5.1)

対象: ブラウザだけで分析クエリを動かしたい(サーバー不要)、Parquet を直接読みたい、ローカル CSV 解析

DuckDB(列指向の高速分析 SQL DB)を WASM(WebAssembly) ビルドでブラウザに埋め込み、サーバーなしで SQL を実行するパターン。DDL / INSERT / SELECT / Parquet 読み込み、WASM ロードの落とし穴を動く demo で確認します。

触って試す #

初回は WASM(転送時 約 6.8 MB)を fetch するため、回線によって 1〜数秒待ちます。

セットアップ(npm + 3 種類の WASM bundle) #

npm i @duckdb/duckdb-wasm

DuckDB-Wasm は環境別に 3 種類の WASM bundle(mvp / eh / coi)を持っています。ただし getJsDelivrBundles() が返すのは mvp と eh の 2 つだけで、selectBundle() はこの 2 つからブラウザの機能に合わせて選びます(Chromium では eh)。coi を使うには bundle を手動で定義します:

3 つの速度差はこの記事では測っていません(公式の説明では coi がスレッドを使える分だけ速いとされています)。

coi を使うには HTTP レスポンスに 2 つのヘッダ が必要:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Cloudflare Pages / Workers / Vercel いずれもヘッダは _headers ファイル(Pages)や Response.headers で設定可能。iframe 内に埋め込む場合は 親ページも同じヘッダ必須。jsDelivr のファイルは Cross-Origin-Resource-Policy: cross-origin を返すので、COEP を付けたページからでも読み込めます。

なぜブラウザで SQL? #

• サーバー / DB 不要:プライベートデータをアップロードせず、ローカルで分析できる
• Parquet を直接読める:CSV や JSON より高速、列志向で集約に強い
• OLAP 系クエリ最適化:GROUP BY / WINDOW / JOIN が Postgres 互換 + 高速
• AI agent との相性:LLM に SQL を書かせて即実行する UX

代替: SQL.js(SQLite を WASM 化)。OLAP / Parquet なら DuckDB のほうが速い。

最小サンプル(DuckDB-Wasm 1.33、5 ステップ) #

AsyncDuckDB を bundle に応じた worker と一緒に初期化、connect() でコネクションを取って query() を実行するだけ:

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

const bundles = duckdb.getJsDelivrBundles();
const bundle = await duckdb.selectBundle(bundles);

// CDN の URL を new Worker() に直接渡すと SecurityError になる(Worker は同一オリジンのスクリプトしか起動できない)。
// 同一オリジンの Blob から importScripts で読み込ませる
const workerUrl = URL.createObjectURL(
  new Blob([`importScripts("${bundle.mainWorker!}");`], { type: "text/javascript" }),
);
const worker = new Worker(workerUrl);
const db = new duckdb.AsyncDuckDB(new duckdb.ConsoleLogger(), worker);
await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
URL.revokeObjectURL(workerUrl);

const conn = await db.connect();
await conn.query(`
  CREATE TABLE sales (region TEXT, revenue DOUBLE);
  INSERT INTO sales VALUES ('east', 1500), ('west', 1100);
`);

const result = await conn.query("SELECT region, SUM(revenue) FROM sales GROUP BY region");
console.log(result.toArray());

Parquet / CSV を直接読む #

registerFileURL で URL を登録 → SQL から read_csv / read_parquet で直接読める:

// HTTP 経由で Parquet を直接 SQL 対象にできる
const r = await conn.query(`
  SELECT category, COUNT(*)
  FROM 'https://example.com/data.parquet'
  GROUP BY category
`);

// ローカル CSV(ユーザがアップロードした File を Blob URL 化)
const file = inputElement.files![0];
await db.registerFileHandle("upload.csv", file, duckdb.DuckDBDataProtocol.BROWSER_FILEREADER, true);
await conn.query("SELECT * FROM 'upload.csv' LIMIT 10");

バンドル戦略 #

WASM は転送時でも約 6.8 MB あるので、main bundle に同梱しない。動的 import で初回利用時にだけロード:

const init = async () => {
  const duckdb = await import("@duckdb/duckdb-wasm");
  // ...
};

jsDelivr から読み込むときに起きること(実測) #

getJsDelivrBundles() は、インストールした版に対応する jsDelivr の URL を組み立てて返すだけの関数です。何が読み込まれるかを、Node から jsDelivr に問い合わせて確かめました(1.33.1-dev45.0)。

ブラウザ側(Chromium、crossOriginIsolated = false)で確かめた挙動:

初期化の 1.6 秒は回線とキャッシュで大きく変わります(2 回目以降はブラウザのキャッシュから読まれる)。自前でホストする場合は bundles を手動で定義し、.wasm を application/wasm で、brotli を効かせて配信します。圧縮が効いていないと 34 MB をそのまま送ることになります。再現: scripts/measure/duckdb-jsdelivr-worker.mjs

主な SQL 機能 #

PostgreSQL 互換が高く、Postgres で書いた analytic クエリはほぼそのまま動く。

Parquet を URL から直読みする 3 つの前提 #

SELECT * FROM 'https://example.com/data.parquet' の 1 行で外部 Parquet を読めるのは強力だが、現実は CORS と Range request が前提:

1. Access-Control-Allow-Origin: 別ドメインの Parquet を読むなら必須。S3 / GCS / R2 は bucket の CORS 設定で許可
2. Accept-Ranges: bytes: DuckDB は Parquet の footer から先に読むため、サーバが HTTP Range request に応える必要がある。Cloudflare R2 / S3 はデフォルトで対応、自前 nginx は chunked_transfer_encoding off 等の調整が必要
3. HTTPS: crossOriginIsolated 環境では mixed content 不可

ローカル CSV を読ませる場合は registerFileHandle で File を渡すだけで OK(CORS の話は出てこない):

await db.registerFileHandle("upload.csv", file, duckdb.DuckDBDataProtocol.BROWSER_FILEREADER, true);
await conn.query("CREATE TABLE t AS SELECT * FROM 'upload.csv'");

8 つの落とし穴と直し方 #

評価 #

向く / 向かないケース #

• 向く: ブラウザ内 BI ダッシュボード、ユーザがアップロードした CSV/Parquet の分析、エディタ内 query playground
• 向かない: 数 GB のデータをクライアントで処理(memory limit)、リアルタイム書き込みの DB 用途
• 向かない: 単純な「SQLite で十分」(SQL.js のほうがバンドル軽い)

関連 Topic / 関連書籍 #

この記事と関係する tech-book.net の Topic と、それぞれの Topic に紐づく書籍:

• /roadmaps/javascript-deep-dive
• /roadmaps/typescript-mastery

tech-book.net /books/9784297144944

JavaScriptによるはじめてのアルゴリズム入門

河西 朝雄 · 技術評論社 · 2024年

JavaScriptでアルゴリズムの基礎から応用まで体系的に実装する

詳細を tech-book.net で見る →

tech-book.net /books/9784873118086

Python と JavaScriptではじめるデータビジュアライゼーション

Kyran Dale / 嶋田 健志 / 木下 哲也 · オライリー・ジャパン · 2017年

PythonとJavaScriptで実装するデータ収集から可視化までのフルパイプライン

詳細を tech-book.net で見る →

tech-book.net /books/9784839966645

React Native＋Expoではじめるスマホアプリ開発 : JavaScriptによるアプリ構築の実際

松澤 太郎 · マイナビ出版 · 2018年

ExpoでiOS/Android両対応アプリをJavaScriptで構築する

詳細を tech-book.net で見る →

tech-book.net /books/9784627857216

はじめてのWebデザイン&プログラミング : HTML、CSS、JavaScript、PHPの基本

村上 祐治 · 森北出版 · 2023年

HTML・CSS・JavaScript・PHP を横断してWebの全体像を最短で把握する

詳細を tech-book.net で見る →