DuckDBWasmDataSource

DuckDBWasmDataSource is the recommended SqlDataSource implementation for browser applications, to load full CSV / JSON data in memory. It runs DuckDB compiled to WebAssembly directly in the browser - no server required.

It supports native Arrow ingestion for batch insertion, making loadData() and loadDataFromURL() fast even for large datasets.

Outline

class DuckDBWasmDataSource extends SqlDataSource {
  constructor(wasmDb: duckdb.AsyncDuckDB, wasmConn: duckdb.AsyncDuckDBConnection);
  static create(bundles: DuckDBWasmBundles): Promise<DuckDBWasmDataSource>;
  execute(sql: string): Promise<Record<string, any>[]>;
  protected insertArrowTable(table: arrow.Table, name: string): Promise<void>;
  release(): Promise<void>;
}

interface DuckDBWasmBundles {
  mvp: { mainModule: string; mainWorker: string };
  eh?: { mainModule: string; mainWorker: string };
}

Creating an instance

import { DuckDBWasmDataSource } from "grid";

const ds = await DuckDBWasmDataSource.create();

create() is async because it downloads and instantiates the DuckDB WASM binary. Default WASM bundles are included with the package - you don't need to configure them.

Custom WASM bundles

If you self-host the WASM files or need a specific build, pass custom bundle paths:

const ds = await DuckDBWasmDataSource.create({
  mvp: {
    mainModule: "/wasm/duckdb-mvp.wasm",
    mainWorker: "/wasm/duckdb-browser-mvp.worker.js",
  },
  eh: {
    mainModule: "/wasm/duckdb-eh.wasm",
    mainWorker: "/wasm/duckdb-browser-eh.worker.js",
  },
});

The eh (exception handling) bundle is optional but faster in browsers that support WASM exception handling. DuckDB's selectBundle picks the best available bundle automatically.

WASM bundle selection

DuckDB WASM ships three bundle tiers: MVP (minimal, single-threaded), EH (adds WASM exception handling, single-threaded), and COI (cross-origin isolated, multithreaded via SharedArrayBuffer).

The COI bundle requires Cross-Origin-Embedder-Policy and Cross-Origin-Opener-Policy headers, which can conflict with other resources on the page. The library defaults to MVP and EH bundles only, which run single-threaded and need no special headers. This is the right middle ground between performance and deployment simplicity.

Loading and querying data

Once created, use the inherited loadData() and loadDataFromURL() methods from SqlDataSource:

// load from a URL
await ds.loadDataFromURL({
  url: "/data/sales.json",
  type: "json",
  schema: [
    { name: "city", type: "dimension" },
    { name: "revenue", type: "measure", subtype: "decimal" },
  ],
});

// query with SQL
const rows = await ds.execute(`SELECT city, SUM(revenue) as total FROM ${ds.table} GROUP BY city`);

A single DuckDBWasmDataSource can power multiple grids (e.g. a pivot table and a flat table on the same page). Use addRef() and release() to manage the shared lifecycle:

const ds = await DuckDBWasmDataSource.create();
await ds.loadDataFromURL({ url: "/data/sales.json", type: "json" });

// second consumer
ds.addRef();

// when a consumer is done
await ds.release();

// when the last consumer releases, the WASM instance and connection are cleaned up
await ds.release();

Cleanup

When release() is called and the reference count reaches zero, the underlying WASM connection is closed and the DuckDB WASM instance is terminated, freeing memory.

API Reference

Extends SqlDataSource.

The recommended SqlDataSource implementation for browser applications, to load full CSV / JSON data in memory.

Runs DuckDB compiled to WebAssembly directly in the browser - no server required. Supports native Arrow ingestion for batch insertion, making loadData() and loadDataFromURL() fast even for large datasets.

Prop

Type

executefunction

Execute a SQL string against the DuckDB WASM engine and return the result rows.

Type

(sql: string) => Promise<Record<string, any>[]>

Parameters

sql -

A SQL query string.

Returns

Result rows as key-value records.

releasefunction

Decrement the reference count. When it reaches zero, the WASM connection is closed and the DuckDB WASM instance is terminated, freeing memory.

Type

() => Promise<void>

Static methods

Prop

Type

createfunction

Create a new DuckDBWasmDataSource instance. Downloads and instantiates the DuckDB WASM binary.

Type

(bundles?: DuckDBWasmBundles) => Promise<DuckDBWasmDataSource>

Parameters

bundles -

Optional custom WASM bundle paths. Default bundles are included with the package.

DuckDBDataSource (Node.js)

DuckDBDataSource is the Node.js equivalent, backed by native DuckDB. It has the same API but uses native bindings instead of WASM. It is primarily used for server-side execution and unit testing.

import { DuckDBDataSource } from "grid";

const ds = DuckDBDataSource.create(); // synchronous, no WASM to download
await ds.loadDataFromURL({ url: "https://example.com/sales.json", type: "json" });

DuckDBWasmDataSource

On this page