# DuckDB WASM 教程：网页查询远程 Parquet，记录实际 Range 请求与读取字节

DuckDB WASM实际HTTP Range读取Parquet，类别合计匹配独立oracle，冷上下文列聚合传输少于全列对照。

## 环境

- Node.js 24+；进入 reference 后 npm install。依赖为锁定的直接版本，首次安装需要网络。
- npm run build 后再启动HTTP服务。编译bundle与WASM运行时不随包分发，build.mjs从本地npm依赖准备。

## 启动

~~~sh
cd reference
npm install
npm run build
python3 range_server.py --port 8787
~~~

## 七步操作

1. 准备Parquet分组

输入含20000行、category与amount两列及三个宽字符串列，按行组写入真实Parquet。先核对独立oracle中的各类别合计和文件总字节。

2. 启动Range服务

本地HTTP服务必须支持HEAD、Accept-Ranges、206与Content-Range，并记录真实发送字节。仅在浏览器Network里看到文件名不能证明发生了范围读取。

3. 注册HTTP懒文件

DuckDB WASM使用registerFileURL的HTTP协议注册文件，关闭整份HTTP回退并启用可靠HEAD。不要先fetch整文件成ArrayBuffer，再声称按列节省了传输。

4. 执行列聚合

在冷上下文按category聚合amount，SUM显式转为DOUBLE便于显示。实际查询结果与独立生成输入时的类别合计一致。

5. 读取全部列对照

另建冷上下文读取三个宽字符串列作为对照，避免复用先前缓存。使用同一份Parquet，只改变SQL需要的数据列。

6. 核对网络字节

比较服务器实际Range请求和发送字节，列聚合读取少于全列对照。这里报告测得的字节而非估算百分比，文件布局不同时收益也会变化。

7. 保存查询与输入

下载Parquet、oracle、查询源码与范围服务。WASM依赖在本地build准备；本文不代表所有Parquet都能少读，也不把Python DuckDB结果冒充浏览器执行。

## 目录身份

- starter：待完成的任务接口与原创输入，TODO不是已完成实现。
- reference：作者原生完成参考和实际产物。records.json/browser-result.json为本地实测记录，不是AI助手回复。
- TASK.md：可交给相应AI助手的原始任务合同。该助手账号生成会话未运行。

## 依赖与许可

原创教学代码以MIT许可提供。第三方项目、模型及浏览器遵循其自身许可。第三方依赖由本地安装获取，不包含node_modules、模型权重、WASM运行时、数据库、缓存或凭据。

## 官方依据

- https://duckdb.org/docs/current/clients/wasm/data_ingestion