
DuckDB-Wasmは、WebAssemblyを活用してブラウザ内でほぼネイティブなパフォーマンスで分析SQLワークロードを可能にします。このガイドでは、Next.jsへの統合について詳しく説明し、数メガバイトのParquetファイルをクライアント側でクエリする方法、Web Workerの管理、バックエンドの計算なしでインタラクティブなダッシュボードを構築する方法に焦点を当てます。
DuckDB-Wasmによるクライアントサイド分析は、データ処理のパラダイムを根本的に変えます。SQL実行のために生データをバックエンドに送信する代わりに、データはローカルに保持され、SQLエンジンはブラウザ内で実行されます。このアーキテクチャには、ネットワーク遅延の削減、バックエンド計算コストの排除、データプライバシーの強化など、いくつかの利点があります。
主要なコンポーネントは次のとおりです。
DuckDB操作専用のWeb Workerを確立します。これは、特に大規模なデータセットや複雑なクエリを扱う際に、UIの応答性を維持するために不可欠です。
まず、必要なパッケージをインストールします。
npm install @duckdb/duckdb-wasm @duckdb/duckdb-wasm-shell react-chartjs-2 chart.js
npm install -D worker-loader # For Next.js custom webpack config
Next.jsは、Web Workerを処理するためにカスタムのWebpack設定を必要とします。next.config.mjsを作成します。
// next.config.mjs
import { fileURLToPath } from 'url';
import { dirname } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
/** @type {import('next').NextConfig} */
const nextConfig = {
webpack: (config, { isServer, webpack }) => {
// DuckDB-Wasm requires specific asset handling
config.experiments = { ...config.experiments,
asyncWebAssembly: true,
topLevelAwait: true,
layers: true
};
// Configure worker-loader for our DuckDB worker
config.module.rules.unshift({
test: /\.worker\.ts$/,
loader: 'worker-loader',
options: {
filename: 'static/[hash].worker.js', // Output worker to static directory
publicPath: '/_next/', // Ensure correct public path for worker
},
});
// DuckDB-Wasm specific configuration for WASM files
config.module.rules.push({
test: /\.wasm$/,
type: 'asset/resource',
generator: {
filename: 'static/wasm/[name].[hash][ext]',
},
});
// Ensure DuckDB-Wasm can find its worker files
config.plugins.push(
new webpack.DefinePlugin({
'process.env.DUCKDB_RUNTIME_URL': JSON.stringify('https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.28.0/dist/duckdb-mvp.wasm'),
'process.env.DUCKDB_RUNTIME_WORKER_URL': JSON.stringify('https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.28.0/dist/duckdb-browser-mvp.worker.js'),
})
);
return config;
},
};
export default nextConfig;
src/workers/duckdb.worker.tsを作成します。このワーカーはDuckDBを初期化し、メッセージパッシングAPIを公開します。
// src/workers/duckdb.worker.ts
import * as duckdb from '@duckdb/duckdb-wasm';
import { AsyncDuckDB, DuckDBDataProtocol, ConsoleLogger } from '@duckdb/duckdb-wasm';
// Define the DuckDB-Wasm bundle
const DUCKDB_BUNDLES = {
mvp: {
mainModule: 'https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.28.0/dist/duckdb-mvp.wasm',
mainWorker: 'https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.28.0/dist/duckdb-browser-mvp.worker.js',
},
eh: {
mainModule: 'https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.28.0/dist/duckdb-eh.wasm',
mainWorker: 'https://cdn.jsdelivr.net/npm/@duckdb/duckdb-wasm@1.28.0/dist/duckdb-browser-eh.worker.js',
},
};
let db: AsyncDuckDB | null = null;
let conn: duckdb.AsyncDuckDBConnection | null = null;
// Function to initialize DuckDB
async function initializeDuckDB() {
if (db) return; // Already initialized
const bundle = await duckdb.selectBundle(DUCKDB_BUNDLES);
const worker = new Worker(bundle.mainWorker!);
// Use the custom logger to see DuckDB logs in the worker console
db = new AsyncDuckDB(new ConsoleLogger(), worker);
await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
conn = await db.connect();
console.log('DuckDB-Wasm initialized in worker.');
}
// Handle messages from the main thread
self.onmessage = async (event: MessageEvent) => {
const { id, type, payload } = event.data;
try {
if (type === 'INIT') {
await initializeDuckDB();
self.postMessage({ id, type: 'INIT_SUCCESS' });
} else if (type === 'QUERY') {
if (!conn) throw new Error('DuckDB not initialized.');
const { query, params } = payload;
console.log(`Executing query: ${query}`);
// Example: Register a Parquet file if needed
// For this example, we assume the Parquet file is already accessible via HTTP
// or registered in a previous step.
// If you need to register a file from a URL:
// await db.registerFileURL('my_data.parquet', payload.parquetUrl, DuckDBDataProtocol.HTTP, false);
const result = await conn.query(query, params);
self.postMessage({ id, type: 'QUERY_SUCCESS', payload: result.toArray() });
} else if (type === 'REGISTER_PARQUET_URL') {
if (!db) throw new Error('DuckDB not initialized.');
const { name, url } = payload;
await db.registerFileURL(name, url, DuckDBDataProtocol.HTTP, false);
console.log(`Registered Parquet file: ${name} from ${url}`);
self.postMessage({ id, type: 'REGISTER_PARQUET_URL_SUCCESS' });
} else {
throw new Error(`Unknown message type: ${type}`);
}
} catch (error: any) {
console.error('DuckDB Worker Error:', error);
self.postMessage({ id, type: 'ERROR', payload: error.message });
}
};
ワーカー通信を抽象化するためにsrc/hooks/useDuckDB.tsを作成します。
// src/hooks/useDuckDB.ts
import { useEffect, useState, useRef, useCallback } from 'react';
import { v4 as uuidv4 } from 'uuid';
// Define message types for communication
interface WorkerMessage {
id: string;
type: string;
payload?: any;
}
interface QueryResult {
[key: string]: any;
}
export function useDuckDB() {
const [isReady, setIsReady] = useState(false);
const [error, setError] = useState<string | null>(null);
const workerRef = useRef<Worker | null>(null);
const messageCallbacks = useRef<Map<string, (result: any) => void>>(new Map());
useEffect(() => {
// Dynamically import the worker to avoid issues with Next.js SSR
// This assumes your worker is built by webpack and accessible via a URL
// The `worker-loader` plugin handles this.
workerRef.current = new Worker(new URL('../workers/duckdb.worker.ts', import.meta.url));
const worker = workerRef.current;
worker.onmessage = (event: MessageEvent<WorkerMessage>) => {
const { id, type, payload } = event.data;
if (type === 'INIT_SUCCESS') {
setIsReady(true);
} else if (type === 'ERROR') {
setError(payload);
const callback = messageCallbacks.current.get(id);
if (callback) {
callback(new Error(payload)); // Propagate error to specific call
messageCallbacks.current.delete(id);
}
} else {
const callback = messageCallbacks.current.get(id);
if (callback) {
callback(payload);
messageCallbacks.current.delete(id);
}
}
};
worker.onerror = (err) => {
console.error('DuckDB Worker Error:', err);
setError('Worker encountered an error.');
};
// Initialize the worker
worker.postMessage({ id: uuidv4(), type: 'INIT' });
return () => {
worker.terminate();
workerRef.current = null;
};
}, []);
const sendWorkerMessage = useCallback((type: string, payload?: any): Promise<any> => {
return new Promise((resolve, reject) => {
if (!workerRef.current) {
return reject(new Error('DuckDB worker not initialized.'));
}
const id = uuidv4();
messageCallbacks.current.set(id, (result: any) => {
if (result instanceof Error) {
reject(result);
} else {
resolve(result);
}
});
workerRef.current.postMessage({ id, type, payload });
});
}, []);
const query = useCallback(async (sql: string, params?: any[]): Promise<QueryResult[]> => {
if (!isReady) throw new Error('DuckDB is not ready.');
return sendWorkerMessage('QUERY', { query: sql, params });
}, [isReady, sendWorkerMessage]);
const registerParquetUrl = useCallback(async (name: string, url: string): Promise<void> => {
if (!isReady) throw new Error('DuckDB is not ready.');
return sendWorkerMessage('REGISTER_PARQUET_URL', { name, url });
}, [isReady, sendWorkerMessage]);
return { isReady, error, query, registerParquetUrl };
}
大規模なParquetファイルからデータを視覚化するためのシンプルなダッシュボードを作成します。デモンストレーションのために、sales_data_10m.parquetという名前のParquetファイルが公開URL(CDNやS3バケットなど)経由で利用可能であると仮定します。このファイルには、product_category、sale_date、revenueなどの列を持つ1,000万行の販売データが含まれています。
1,000万行のサンプルParquetファイルを生成するには:
import pandas as pd
import numpy as np
from datetime import datetime, timedelta
num_rows = 10_000_000
# Generate synthetic data
data = {
'sale_id': np.arange(num_rows),
'product_category': np.random.choice(['Electronics', 'Clothing', 'Home Goods', 'Books', 'Food'], num_rows),
'revenue': np.random.uniform(10, 1000, num_rows).round(2),
'units_sold': np.random.randint(1, 10, num_rows),
'sale_date': [datetime(2023, 1, 1) + timedelta(days=np.random.randint(0, 365)) for _ in range(num_rows)],
'region': np.random.choice(['North', 'South', 'East', 'West'], num_rows),
}
df = pd.DataFrame(data)
# Save to Parquet
df.to_parquet('public/sales_data_10m.parquet', index=False)
print(f"Generated sales_data_10m.parquet with {num_rows} rows.")
このsales_data_10m.parquetファイルをNext.jsのpublicディレクトリに配置するか、CDNでホストします。
src/app/page.tsx(App Router用)またはsrc/pages/index.tsx(Pages Router用)を作成します。
// src/app/page.tsx
'use client'; // Mark as client component for Next.js App Router
import { useEffect, useState, useMemo } from 'react';
import { useDuckDB } from '../hooks/useDuckDB';
import { Bar, Line } from 'react-chartjs-2';
import {
Chart as ChartJS,
CategoryScale,
LinearScale,
BarElement,
Title,
Tooltip,
Legend,
PointElement,
LineElement,
} from 'chart.js';
// Register Chart.js components
ChartJS.register(
CategoryScale,
LinearScale,
BarElement,
Title,
Tooltip,
Legend,
PointElement,
LineElement
);
interface SalesByCategory {
product_category: string;
total_revenue: number;
}
interface DailySales {
sale_date: string; // DuckDB returns dates as strings by default
daily_revenue: number;
}
export default function Home() {
const { isReady, error, query, registerParquetUrl } = useDuckDB();
const [categoryData, setCategoryData] = useState<SalesByCategory[]>([]);
const [dailyData, setDailyData] = useState<DailySales[]>([]);
const [loading, setLoading] = useState(true);
const [totalRows, setTotalRows] = useState<number | null>(null);
const PARQUET_FILE_URL = '/sales_data_10m.parquet'; // Adjust if hosted externally
const PARQUET_FILE_NAME = 'sales_data_10m.parquet';
useEffect(() => {
const loadData = async () => {
if (isReady) {
setLoading(true);
try {
// Register the Parquet file URL with DuckDB
await registerParquetUrl(PARQUET_FILE_NAME, PARQUET_FILE_URL);
console.log('Parquet file registered.');
// Count total rows
const countResult = await query(`SELECT COUNT(*) as total_rows FROM "${PARQUET_FILE_NAME}"`);
setTotalRows(countResult[0]?.total_rows || 0);
// Query 1: Total Revenue by Product Category
const categoryResults = await query(`
SELECT
product_category,
SUM(revenue) AS total_revenue
FROM "${PARQUET_FILE_NAME}"
GROUP BY product_category
ORDER BY total_revenue DESC
`);
setCategoryData(categoryResults as SalesByCategory[]);
console.log('Category data fetched:', categoryResults);
// Query 2: Daily Revenue Trend
const dailyResults = await query(`
SELECT
STRFTIME(sale_date, '%Y-%m-%d') AS sale_date,
SUM(revenue) AS daily_revenue
FROM "${PARQUET_FILE_NAME}"
GROUP BY STRFTIME(sale_date, '%Y-%m-%d')
ORDER BY sale_date ASC
`);
setDailyData(dailyResults as DailySales[]);
console.log('Daily data fetched:', dailyResults);
} catch (err: any) {
console.error('Failed to query DuckDB:', err);
setError(err.message);
} finally {
setLoading(false);
}
}
};
loadData();
}, [isReady, query, registerParquetUrl, setError]);
const categoryChartData = useMemo(() => ({
labels: categoryData.map(d => d.product_category),
datasets: [
{
label: 'Total Revenue',
data: categoryData.map(d => d.total_revenue),
backgroundColor: 'rgba(75, 192, 192, 0.6)',
borderColor: 'rgba(75, 192, 192, 1)',
borderWidth: 1,
},
],
}), [categoryData]);
const dailyChartData = useMemo(() => ({
labels: dailyData.map(d => d.sale_date),
datasets: [
{
label: 'Daily Revenue',
data: dailyData.map(d => d.daily_revenue),
fill: false,
backgroundColor: 'rgba(153, 102, 255, 0.6)',
borderColor: 'rgba(153, 102, 255, 1)',
tension: 0.1,
},
],
}), [dailyData]);
if (error) {
return <div className="p-4 text-red-600">Error: {error}</div>;
}
if (!isReady || loading) {
return <div className="p-4">Loading DuckDB and data... This may take a moment for large files.</div>;
}
return (
<div className="container mx-auto p-4">
<h1 className="text-3xl font-bold mb-6">Client-Side Sales Dashboard (10M Rows)</h1>
<p className="mb-4">
Powered by DuckDB-Wasm. Total rows processed: <span className="font-bold">{totalRows?.toLocaleString()}</span>
</p>
<div className="grid grid-cols-1 md:grid-cols-2 gap-8">
<div className="bg-white p-6 rounded-lg shadow-md">
<h2 className="text-xl font-semibold mb-4">Revenue by Product Category</h2>
<Bar data={categoryChartData} options={{ responsive: true, maintainAspectRatio: false }} />
</div>
<div className="bg-white p-6 rounded-lg shadow-md">
<h2 className="text-xl font-semibold mb-4">Daily Revenue Trend</h2>
<Line data={dailyChartData} options={{ responsive: true, maintainAspectRatio: false }} />
</div>
</div>
</div>
);
}
この例は以下を示しています。
awaitされ、結果はメインスレッドに渡されます。registerParquetUrl関数は、リモートのParquetファイルをDuckDBからアクセス可能にします。DuckDB-WasmはHTTP Range Requestsを使用して、ファイルの必要な部分のみをフェッチし、ネットワーク使用量を最適化します。react-chartjs-2は、クエリ結果に基づいてチャートをレンダリングするために使用されます。| 機能 / 側面 | DuckDB-Wasm(クライアントサイド) | 従来のバックエンドDB(サーバーサイド) |
|---|---|---|
| データ局所性 | データはブラウザで直接処理されます。 | データはサーバーに存在し、リモートで処理されます。 |
| ネットワーク遅延 | 初期データロード後(HTTP Range Requests)は最小限。 | 各クエリで高く、ネットワーク経由のデータ転送が発生します。 |
| 計算コスト | バックエンドの計算はゼロ。クライアントのCPU/RAMを使用。 | サーバーサイドの計算コスト(CPU、RAM、I/O)。 |
| スケーラビリティ | クライアントデバイスに応じてスケーリング。クライアントリソースに制限される。 | サーバーインフラに応じてスケーリング。 |
| データ量 | 数十〜数百MB、最大GB(注意が必要)。 | 数TB〜PBを容易に処理。 |
| 初期ロード時間 | WASMモジュールのダウンロードとデータインデックス作成のため高くなる場合がある。 | 初期ページロードは低いが、データフェッチにより遅延が増加。 |
| セキュリティ/プライバシー | データはクライアントから離れない。高いプライバシー。 | データはサーバーに送信される。堅牢なサーバーサイドセキュリティが必要。 |
| オフライン機能 | サービスワーカーによるデータキャッシュで可能。 | 通常はオンライン接続が必要。 |
| 複雑さ | Web Worker管理、WASMの特殊性。 | データベース管理、コネクションプーリング、ORM。 |
| クエリ言語 | 完全なSQL(DuckDB方言)。 | 完全なSQL(特定のDB方言)。 |
DuckDB-Wasmは、ブラウザのWebAssemblyメモリ制限内で動作します。最新のブラウザでは数ギガバイトのWASMメモリが許可されていますが、過剰なデータロードはメモリ不足エラーにつながる可能性があります。
QUERY_ERRORメッセージに対して、堅牢なエラー処理を実装します。Failed to load module: No such file or directory (WASM/Workerファイル):
GET .../duckdb-mvp.wasm 404 (Not Found)のようなエラーが表示される。publicPathが誤って設定されている。next.config.mjsを再確認する。asset/resourceファイル用の.wasmルールと、worker-loaderファイル用の.worker.tsが正しく設定されていることを確認する。DUCKDB_RUNTIME_URLとDUCKDB_RUNTIME_WORKER_URLのDefinePluginエントリが、Next.jsがこれらのアセットを提供する正しいパスを指していることを確認する。ビルド後に.nextディレクトリ内の実際の出力パスを確認する。クエリ実行中のUIフリーズ:
useDuckDBフックとduckdb.worker.tsはこのために設計されている。Reactコンポーネントでduckdb-wasmを直接使用している場合は、間違っている。Out of MemoryまたはWebAssembly.Memoryの割り当てエラー:
LIMIT句、集計のためのGROUP BY、必要な列のみのSELECTを使用する。TypeError: Cannot read properties of undefined (reading 'connect'):
conn.query()などのメソッドを呼び出そうとしたときに発生する。AsyncDuckDBインスタンスまたはAsyncDuckDBConnectionが適切に初期化されていないか、クエリが試行されたときにnullである。initializeDuckDB関数が、QUERYメッセージが送信される前に正常に完了することを確認する。isReadyのuseDuckDBの状態はこれを防ぐように設計されている。isReadyがtrueになるのを待っていることを確認する。ParquetファイルでのCORS問題:
Failed to fetchまたはCORSエラーが、registerFileURLが異なるオリジンからParquetファイルにアクセスしようとしたときに発生する。Access-Control-Allow-Origin)を送信していない。Rangeヘッダーも許可する必要がある場合がある。開発チームはNext.jsでDuckDB-Wasmを使用してクライアントサイドの分析ダッシュボードを構築しています。複雑なクエリや大量のデータロードが原因で、ブラウザタブが数秒間応答しなくなることがあると報告されています。見落とされた場合、この問題の最も可能性の高い原因となるアーキテクチャ上の決定は何ですか?
A1: DuckDB-Wasmは主に、静的またはゆっくりと変化するデータセットに対する分析クエリ用に設計されています。ファイルを再登録したり、新しいデータをロードしたりすることはできますが、従来のOLTPデータベースのようなリアルタイムストリーミング更新のための組み込みメカニズムはありません。リアルタイムダッシュボードの場合、通常は新しいデータをフェッチし(場合によっては新しいParquetファイルとして)、クエリを再実行します。
A2: DuckDB-Wasmは、永続化のためにIDBBatchAtomicVFS(IndexedDBをバックエンドとするファイルシステム)を使用するように構成できます。これにより、データベースの状態と登録されたファイルをIndexedDBに保存し、ブラウザのリフレッシュや終了後も保持できます。これは、ワーカー内のAsyncDuckDBインスタンス化中に構成します。
// Example for persistence in duckdb.worker.ts
import { AsyncDuckDB, DuckDBDataProtocol, ConsoleLogger, IDBBatchAtomicVFS } from '@duckdb/duckdb-wasm';
// ... inside initializeDuckDB()
const bundle = await duckdb.selectBundle(DUCKDB_BUNDLES);
const worker = new Worker(bundle.mainWorker!);
// Initialize VFS for persistence
const vfs = new IDBBatchAtomicVFS('duckdb-data'); // 'duckdb-data' is the database name
db = new AsyncDuckDB(new ConsoleLogger(), worker);
await db.instantiate(bundle.mainModule, bundle.pthreadWorker, {
query: {
'duckdb-data': vfs, // Register the VFS
},
});
conn = await db.connect();
// Now you can use 'ATTACH 'duckdb-data';' and 'CREATE TABLE ... IN 'duckdb-data';'
// or 'COPY ... TO 'duckdb-data'/my_table.parquet (FORMAT PARQUET);'
A3: 主な制限は次のとおりです。
<input type="file">から)で使用できますか?A4: はい、もちろんです。Fileオブジェクト(ファイル入力から)をFileReaderまたはFile.arrayBuffer()を使用して読み取り、db.registerFileBuffer()を使用してDuckDB-Wasmに登録できます。
// In your worker:
// ...
else if (type === 'REGISTER_FILE_BUFFER') {
if (!db) throw new Error('DuckDB not initialized.');
const { name, buffer } = payload; // buffer would be an ArrayBuffer
await db.registerFileBuffer(name, new Uint8Array(buffer));
console.log(`Registered file buffer: ${name}`);
self.postMessage({ id, type: 'REGISTER_FILE_BUFFER_SUCCESS' });
}
// ...
// In your React component:
const handleFileChange = async (event: React.ChangeEvent<HTMLInputElement>) => {
const file = event.target.files?.[0];
if (file) {
const arrayBuffer = await file.arrayBuffer();
await sendWorkerMessage('REGISTER_FILE_BUFFER', { name: file.name, buffer: arrayBuffer });
// Now you can query the file by its name
const result = await query(`SELECT COUNT(*) FROM "${file.name}"`);
console.log('Local file count:', result);
}
};
// ... in JSX
<input type="file" onChange={handleFileChange} accept=".parquet" />
AI CLIログの整形、Cron式の作成、JWTの解析、chmod権限の計算をオフラインで実行。

モダンWebアプリにおけるduckdb-wasmの包括的なガイド。クライアントサイドOLAP、Parquetストリーミング、そして本番環境レベルのアーキテクチャとコード例による超高速ダッシュボードについて解説します。
続きを読む
App RouterでのNext.jsとPrismaの完全ガイドで、グローバルなコネクションプール枯渇の防止、型安全なクエリ、サーバーアクションミューテーション、シードスクリプトについて解説します。
続きを読む
2026年におけるClickHouseとDuckDBを、インメモリ組み込みOLAPと分散型ベクトル化ウェアハウスの観点から、本番環境レベルのアーキテクチャとコード例を交えて網羅的に解説するガイドです。
続きを読む