浏览器内数据分析：DuckDB-WASM 与 Apache Arrow 零拷贝实践

浏览器标签页
┌──────────────────────────────────────────────────────┐
│  主线程 (UI)                                          │
│   AsyncDuckDB ──postMessage──▶  Worker 线程            │
│                                  ┌──────────────────┐ │
│                                  │ duckdb.wasm      │ │
│                                  │ (列式执行引擎)    │ │
│                                  └──────────────────┘ │
│                                        ▲              │
│   Arrow Table ◀────零拷贝共享内存───────┘              │
│   (JS 侧消费结果)                                      │
└──────────────────────────────────────────────────────┘

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

// 选择 bundle：根据浏览器是否支持 SIMD / threads 决定
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 res = await conn.query(`SELECT region, sum(amount) FROM sales GROUP BY 1`);

关键设计：
  1. 引擎跑在 Worker，主线程只负责发指令与消费结果 → UI 不卡
  2. 查询返回 Arrow Table，而非 JSON → 避免逐行序列化
  3. 数据库实例是「进程内」的，没有网络往返，延迟只受 CPU 限制

行式（JSON / 数组对象）：{region:"A",amount:10}, {region:"B",amount:20}
  内存里交错存放，扫描某一列要跳过其他列 → 缓存不友好

列式（Arrow）：region:["A","B"]  amount:[10,20]
  同一列连续存放，扫描与聚合只碰需要的列 → 缓存友好、可 SIMD 化

Arrow Columnar Format 三个层次：
  Schema     字段名与类型（int32 / utf8 / timestamp 等）
  RecordBatch 一批行，内部按列存放，带长度与 null 位图
  Buffer     实际字节，分 validity / offsets / data 三种
字符串列不是「一堆字符串」，而是 offsets 数组 + data 字节数组。

// Rust 侧（arrow-rs）构造一个 Int32 列
use arrow::array::Int32Array;
let col = Int32Array::from(vec![1, 2, 3, 4]);
// 底层就是一段连续 i32 缓冲 + 一个 validity 位图

零拷贝成立的条件：
  1. WASM 线性内存与 JS 的 ArrayBuffer 指向同一块物理内存
  2. 结果在 WASM 侧已经是 Arrow 布局，无需重新序列化
  3. JS 侧直接在该 buffer 上建 TypedArray 视图读取
Arrow Table 的每个 Buffer 都能映射成一段 Uint8Array，逐列解读。

// 从查询结果里取出某一列的原始缓冲区（示意）
const table = res;                       // Arrow Table
const col = table.getChild('amount');
const data = col.data[0];                // 一个 Data 对象
const values = new Int32Array(
  data.values.buffer, data.values.byteOffset, data.length
);

两个必须记住的约束：
  1. WASM 内存一旦增长，所有已建视图立即失效（detached）
  2. 结果缓冲区由 WASM 侧分配，JS 视图生命周期不能超过其存活期
安全做法：在结果上调用 toArray() / slice() 拿到 JS 拥有的副本再长期持有。

// 把文件注册进 DuckDB 的虚拟文件系统，再用 SQL 读
await db.registerFileURL('sales.parquet', url,
  duckdb.DuckDBDataProtocol.HTTP, false);

await conn.query(`CREATE TABLE sales AS
  SELECT * FROM parquet_scan('sales.parquet')`);

-- Parquet 是列式存储：只读需要的列，只扫匹配的行组
SELECT region, sum(amount)
FROM parquet_scan('sales.parquet')
WHERE year = 2026          -- 谓词下推，跳过不相关的行组
GROUP BY region;

性能要点：
  只 SELECT 需要的列（列裁剪）→ 读的字节数可降一个数量级
  WHERE 尽量落在排序/分区键上（谓词下推 + 行组跳过）
  避免 SELECT * 后再在 JS 里过滤 —— 等于把优化机会全丢掉

三种并行度：
  单 Worker       引擎在独立线程跑，UI 不卡，但计算是单线程
  Pthreads        duckdb 编译为多线程 WASM，需要 COOP/COEP 响应头
  多实例并行      开多个 Worker 各跑一个实例，各自处理不同数据分片

// 多实例：把数据按分片交给多个 Worker，各自聚合后合并
const workers = Array.from({ length: 4 }, () =>
  new Worker(bundle.mainWorker));
const partials = await Promise.all(shards.map((shard, i) =>
  runOn(workers[i], shard)));
const total = partials.reduce(mergeAggregate);

启用 Pthreads 的前提是跨源隔离：
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp
代价：所有第三方资源（图片、脚本、字体）都必须带 CORP 头或走 CORS，
      否则会被浏览器拦截 —— 这是上线时最容易被忽略的坑。

内存态数据库的两个问题：
  1. 刷新页面即丢，重新下载与解析成本高
  2. 大表全放内存会撞上浏览器给 WASM 的内存上限
OPFS（Origin Private File System）提供「按源隔离的私有文件系统」，
DuckDB 可以把数据库文件与 Parquet 直接落盘到 OPFS。

// 把文件写入 OPFS，再让 DuckDB 从 OPFS 读
const root = await navigator.storage.getDirectory();
const fh = await root.getFileHandle('sales.parquet', { create: true });
await db.registerFileHandle('sales.parquet', fh,
  duckdb.DuckDBDataProtocol.FILE, true);

OPFS 的两个 API：
  createSyncAccessHandle()  只能在 Worker 里用，同步读写、性能最好
  createWritable()          主线程可用，异步、吞吐略低
配额：受 Storage API 的配额限制（通常为磁盘可用空间的百分比），
      写满会抛 QuotaExceededError，必须捕获并降级。

const table = await conn.query(sql);       // 零拷贝拿到 Arrow Table
const rows = table.toArray();              // 显式拷贝成 JS 对象数组
console.log(rows[0].region, rows[0].amount);

反模式：查询 → Arrow → JSON.stringify → 前端解析
  白白付两次序列化成本，还把列式优势丢光

正模式：查询 → Arrow → 直接喂给图表库
  多数图表库支持列式数据，或只需 toArray() 一次的浅转换

WASM 32 位地址空间硬上限 4 GiB，但浏览器实际给的更少：
  桌面 Chrome 单标签页通常可用 1~2 GiB 线性内存
  移动端 Safari 明显更紧，大表极易 OOM
超限表现：memory.grow 返回 -1 → 分配失败 → 查询报错或实例崩溃

-- 用 LIMIT/OFFSET 或按分区键分块扫描，避免一次性物化全表
SELECT region, sum(amount) FROM parquet_scan('sales.parquet')
WHERE year = 2026
GROUP BY region
LIMIT 100000;

四种降内存手段：
  1. 列裁剪 + 谓词下推，从源头减少要读的列与行
  2. 流式聚合（DuckDB 会自动做），避免中间结果全物化
  3. 按分区键分块查询，每块跑完即释放
  4. 结果直接落 OPFS，不全部留在内存

推荐形态：边缘聚合 + 服务端细算
  1. 浏览器先对本地/已下载数据做粗筛与聚合，减少回传量
  2. 只把「无法本地完成」的聚合请求发往后端
  3. 大表用 Parquet + 列裁剪，按需从 CDN 拉取分片
判据：单用户数据量 < 数百 MB 且隐私敏感 → 全前端；
      需要跨用户全量数据 → 必须后端。

必测五项：
  1. 首次可查询时间（下载 bundle + 实例化 + 首次查询）
  2. 单次查询 P50 / P99 延迟（分冷热）
  3. 峰值线性内存（决定是否会 OOM）
  4. 数据下载字节数（Parquet 列裁剪后的实际传输量）
  5. Worker 与主线程的 CPU 占用分布

[ ] bundle 按 SIMD/threads 能力选择，避免把多线程版发给不支持的浏览器
[ ] 查询走 Worker，主线程只做 UI
[ ] 结果用 Arrow Table，避免 Arrow→JSON 二次序列化
[ ] 所有 malloc / 查询失败路径有降级，OOM 不崩溃
[ ] OPFS 写入捕获 QuotaExceededError 并降级为内存态
[ ] 移动端单独压测内存上限
[ ] 明确数据不出浏览器的合规声明与验证方法