Query a million rows in the browser with DuckDB-Wasm

In this tutorial, you will back a Handsontable DataGrid with DuckDB-Wasm, the in-process SQL database compiled to WebAssembly. DuckDB holds a million rows in a Web Worker, and the grid holds one page at a time. Every page, sort, filter, and edit runs as SQL in the browser, with no server, no API, and no account.

Open in the demo runner

The grid above generates a million orders in DuckDB when it loads. Sort a column, filter Region or Qty, or page to the end. The status bar shows how many rows match and how long the last query took. The demo loads the DuckDB engine from jsDelivr, while this recipe serves it from your own app with Vite.

Overview

Difficulty: Intermediate
Time: ~30 minutes
Stack: React, Vite, Handsontable dataProvider, @handsontable/react-wrapper, @duckdb/duckdb-wasm 1.32

The dataProvider plugin turns Handsontable into a grid backed by a remote source. You supply four async functions — one that fetches a page of rows, and three that create, update, and delete rows — and the plugin drives pagination, sorting, and filtering through them. The other server-side recipes point those functions at an HTTP API. This one points them at a database that runs in the same browser tab.

That fits a common case: someone has a large Parquet or CSV export and no API in front of it. DuckDB reads the file in the browser, and the grid gives them sorting, filtering, and editing over all of it.

What you’ll build

An orders grid over 1,000,000 generated rows:

A DuckDB-Wasm database in a Web Worker, seeded in SQL with no download.
Page-by-page loading with a stable order, so no row is repeated or skipped between pages.
Sorting and filtering in SQL, with each Handsontable filter condition mapped to a parameterized SQL predicate.
Cell edits, new rows, and deletions written to DuckDB, with a multi-row edit committed in one transaction.
A status bar that shows how many rows match and how long the last query took.
A Load Parquet or CSV button that replaces the data with your own file, and an Export Parquet button that downloads the table, edits included.

On a recent laptop, the million rows are generated in under a second, and a sorted page returns in tens of milliseconds.

Before you begin

Requirement	Version
`handsontable`	18.1 or later
`@handsontable/react-wrapper`	18.1 or later
`@duckdb/duckdb-wasm`	1.32.0
React + Vite	any current version

Scaffold a Vite + React + TypeScript app if you do not have one, then add the packages:

1
npm create vite@latest orders-app -- --template react-ts
2
cd orders-app
3
npm install handsontable @handsontable/react-wrapper
4
npm install --save-exact @duckdb/duckdb-wasm@1.32.0

Pin @duckdb/duckdb-wasm to an exact version. The package publishes development builds under its latest tag, so a bare npm install @duckdb/duckdb-wasm can install a pre-release build. Run npm view @duckdb/duckdb-wasm dist-tags to see what each tag points to.

The recipe has seven files in src/:

File	Purpose
`duckdb.ts`	Starts DuckDB in a Web Worker and runs statements one at a time
`seed.ts`	Generates the table, loads a user’s file, and exports Parquet
`schema.ts`	The columns that SQL is allowed to reference
`filterToSql.ts`	Turns Handsontable filter conditions into a SQL `WHERE` clause
`ordersProvider.ts`	The four `dataProvider` functions
`OrdersGrid.tsx`	The grid component
`App.tsx`	Seeds the data, shows the status bar, and renders the grid

Start DuckDB in a Web Worker

Create src/duckdb.ts:

1
import * as duckdb from '@duckdb/duckdb-wasm';
2
import mvpWasm from '@duckdb/duckdb-wasm/dist/duckdb-mvp.wasm?url';
3
import mvpWorker from '@duckdb/duckdb-wasm/dist/duckdb-browser-mvp.worker.js?url';
4
import ehWasm from '@duckdb/duckdb-wasm/dist/duckdb-eh.wasm?url';
5
import ehWorker from '@duckdb/duckdb-wasm/dist/duckdb-browser-eh.worker.js?url';
6

7
// Vite serves these files from node_modules, so the app needs no CDN at runtime.
8
const BUNDLES: duckdb.DuckDBBundles = {
9
  mvp: { mainModule: mvpWasm, mainWorker: mvpWorker },
10
  eh: { mainModule: ehWasm, mainWorker: ehWorker },
11
};
12

13
interface Database {
14
  db: duckdb.AsyncDuckDB;
15
  conn: duckdb.AsyncDuckDBConnection;
16
}
17

18
let databasePromise: Promise<Database> | null = null;
19

20
// Starts DuckDB in a Web Worker once and shares one connection across the app.
21
export function getDatabase(): Promise<Database> {
22
  databasePromise ??= (async () => {
23
    const bundle = await duckdb.selectBundle(BUNDLES);
24
    const worker = new Worker(bundle.mainWorker!);
25
    const db = new duckdb.AsyncDuckDB(new duckdb.VoidLogger(), worker);
26

27
    await db.instantiate(bundle.mainModule, bundle.pthreadWorker);
28
    // COUNT(*) and nextval() return BIGINT. Cast to JS numbers so the grid never sees a BigInt.
29
    await db.open({ query: { castBigIntToDouble: true } });
30

31
    return { db, conn: await db.connect() };
32
  })();
33

34
  return databasePromise;
35
}
36

37
// The grid can start a fetch while a mutation's refetch is still pending. Running every
38
// statement through one queue keeps them from interleaving on the shared connection.
39
let queue: Promise<unknown> = Promise.resolve();
40

41
export function exclusive<T>(task: (database: Database) => Promise<T>): Promise<T> {
42
  const run = queue.then(async () => task(await getDatabase()));
43

44
  queue = run.catch(() => undefined);
45

46
  return run;
47
}
48

49
// Runs a parameterized statement and returns plain objects. The statement is always closed.
50
export async function query<T = Record<string, unknown>>(
51
  conn: duckdb.AsyncDuckDBConnection,
52
  sql: string,
53
  params: unknown[] = [],
54
): Promise<T[]> {
55
  const statement = await conn.prepare(sql);
56

57
  try {
58
    const table = await statement.query(...params);
59

60
    return table.toArray().map((row) => row.toJSON() as T);
61
  } finally {
62
    await statement.close();
63
  }
64
}

What’s happening:

Vite serves the engine. The ?url imports give you URLs to the worker scripts and .wasm files inside node_modules, so the app needs no CDN at runtime. selectBundle picks the exception-handling (EH) build when the browser supports it, and falls back to the MVP build otherwise. Neither build needs cross-origin isolation headers. Only DuckDB’s multithreaded build does.
The worker keeps the page responsive. Every query runs off the main thread, so scrolling and typing in the grid never wait on DuckDB.
castBigIntToDouble keeps BigInt out of the grid. COUNT(*) and sequence values are BIGINT in DuckDB, which Apache Arrow returns as JavaScript BigInt. The cast turns them into ordinary numbers in one place.
exclusive runs one statement at a time. The plugin can start a fetch while the refetch that follows a mutation is still pending. Queuing every call keeps a transaction from interleaving with an unrelated query on the shared connection.
query closes every prepared statement. A prepared statement holds memory in the worker until you close it, so the finally block closes it whether the query succeeds or fails.

Generate a million rows

Create src/seed.ts. The first function builds the orders table. The other two come into play in Step 7.

1
import { exclusive } from './duckdb';
2

3
export const ROW_COUNT = 1_000_000;
4

5
// Builds the demo table entirely in SQL: no download, works offline. hash() makes the
6
// values look random but stay the same on every load.
7
const SEED_SQL = `
8
  CREATE OR REPLACE TABLE orders AS
9
  SELECT
10
    (i + 1)::INTEGER AS id,
11
    'ORD-' || lpad((i + 1)::VARCHAR, 7, '0') AS order_no,
12
    (['Bluefin Logistics', 'Cobalt Health', 'Driftwood Retail', 'Ember Energy', 'Fjord Foods',
13
      'Granite Bank', 'Harbor Insurance', 'Ironleaf Pharma', 'Juniper Telecom', 'Kestrel Aerospace']
14
    )[1 + (hash(i * 3 + 1) % 10)::INTEGER] AS customer,
15
    (['North America', 'EMEA', 'APAC', 'LATAM'])[1 + (hash(i * 5 + 2) % 4)::INTEGER] AS region,
16
    (['Laptop', 'Monitor', 'Dock', 'Keyboard', 'Headset', 'Server rack', 'Switch', 'License'])
17
      [1 + (hash(i * 7 + 3) % 8)::INTEGER] AS product,
18
    (1 + hash(i * 11 + 4) % 500)::INTEGER AS quantity,
19
    round(5 + (hash(i * 13 + 5) % 199500) / 100.0, 2)::DOUBLE AS unit_price,
20
    (['Pending', 'Approved', 'Shipped', 'Delivered', 'Cancelled'])
21
      [1 + (hash(i * 17 + 6) % 5)::INTEGER] AS status,
22
    (DATE '2024-01-01' + (hash(i * 19 + 7) % 1035)::INTEGER) AS order_date
23
  FROM range(${ROW_COUNT}) AS t(i);
24

25
  CREATE OR REPLACE SEQUENCE orders_id_seq START ${ROW_COUNT + 1};
26
`;
27

28
export function seedOrders(): Promise<void> {
29
  return exclusive(async ({ conn }) => {
30
    await conn.query(SEED_SQL);
31
  });
32
}
33

34
// Replaces the table with a user's Parquet or CSV file. The file never leaves the browser.
35
// The casts enforce the demo schema, and the grid's edits and deletes match rows by id, so
36
// every id must be present and unique. The file loads into a staging table first: a file that
37
// fails either check is rejected with a clear error and the current table is left as it was.
38
export function loadFile(file: File): Promise<number> {
39
  const isParquet = file.name.toLowerCase().endsWith('.parquet');
40
  // A fixed internal name keeps the user's file name out of the SQL text.
41
  const internalName = isParquet ? 'upload.parquet' : 'upload.csv';
42
  const reader = isParquet ? `read_parquet('${internalName}')` : `read_csv_auto('${internalName}')`;
43

44
  return exclusive(async ({ db, conn }) => {
45
    await db.registerFileBuffer(internalName, new Uint8Array(await file.arrayBuffer()));
46

47
    try {
48
      await conn.query(`
49
        CREATE OR REPLACE TEMP TABLE orders_upload AS
50
        SELECT id::INTEGER AS id, order_no::VARCHAR AS order_no, customer::VARCHAR AS customer,
51
               region::VARCHAR AS region, product::VARCHAR AS product, quantity::INTEGER AS quantity,
52
               unit_price::DOUBLE AS unit_price, status::VARCHAR AS status, order_date::DATE AS order_date
53
        FROM ${reader}`);
54

55
      const check = await conn.query(`
56
        SELECT count(*) AS total, count(*) - count(id) AS missing_ids,
57
               count(id) - count(DISTINCT id) AS duplicate_ids, coalesce(max(id), 0) AS max_id
58
        FROM orders_upload`);
59
      const { total, missing_ids: missingIds, duplicate_ids: duplicateIds, max_id: maxId } = check
60
        .toArray()[0].toJSON() as { total: number; missing_ids: number; duplicate_ids: number; max_id: number };
61

62
      if (missingIds > 0 || duplicateIds > 0) {
63
        throw new Error(`every row needs a unique id (${missingIds} missing, ${duplicateIds} duplicated)`);
64
      }
65

66
      await conn.query('CREATE OR REPLACE TABLE orders AS SELECT * FROM orders_upload');
67
      await conn.query(`CREATE OR REPLACE SEQUENCE orders_id_seq START ${Math.trunc(maxId) + 1}`);
68

69
      return total;
70
    } finally {
71
      await conn.query('DROP TABLE IF EXISTS orders_upload');
72
      await db.dropFile(internalName);
73
    }
74
  });
75
}
76

77
// Writes the current table, edits included, to a Parquet file the user can download.
78
export function exportParquet(): Promise<Blob> {
79
  return exclusive(async ({ db, conn }) => {
80
    await conn.query("COPY orders TO 'orders.parquet' (FORMAT parquet)");
81

82
    try {
83
      return new Blob([new Uint8Array(await db.copyFileToBuffer('orders.parquet'))], { type: 'application/vnd.apache.parquet' });
84
    } finally {
85
      await db.dropFile('orders.parquet');
86
    }
87
  });
88
}

What’s happening:

range(1_000_000) produces a million row numbers, and each column derives its value from hash() of that number. The values look random but stay the same on every load, so a screenshot or a bug report is reproducible. Nothing is downloaded, so the demo works offline.

CREATE OR REPLACE SEQUENCE starts the id sequence after the last generated row. New rows take their id from it, which matters in Step 5.

Declare the columns SQL can reference

Create src/schema.ts:

1
export type ColumnKind = 'text' | 'numeric' | 'date';
2

3
export interface ColumnDef {
4
  kind: ColumnKind;
5
  // SQL used in SELECT and WHERE. Dates are compared as YYYY-MM-DD text, the same
6
  // string the grid shows, so text filter conditions behave the way users expect.
7
  expr: string;
8
  // SQL used in ORDER BY. Dates sort on the real DATE column.
9
  sortExpr: string;
10
  editable: boolean;
11
}
12

13
// The only columns the SQL builders accept. Column names can't be bound as parameters,
14
// so every prop that reaches SQL is checked against this map first.
15
export const COLUMNS: Record<string, ColumnDef> = {
16
  id: { kind: 'numeric', expr: 'id', sortExpr: 'id', editable: false },
17
  order_no: { kind: 'text', expr: 'order_no', sortExpr: 'order_no', editable: false },
18
  customer: { kind: 'text', expr: 'customer', sortExpr: 'customer', editable: true },
19
  region: { kind: 'text', expr: 'region', sortExpr: 'region', editable: true },
20
  product: { kind: 'text', expr: 'product', sortExpr: 'product', editable: true },
21
  quantity: { kind: 'numeric', expr: 'quantity', sortExpr: 'quantity', editable: true },
22
  unit_price: { kind: 'numeric', expr: 'unit_price', sortExpr: 'unit_price', editable: true },
23
  status: { kind: 'text', expr: 'status', sortExpr: 'status', editable: true },
24
  order_date: {
25
    kind: 'date',
26
    expr: "strftime(order_date, '%Y-%m-%d')",
27
    sortExpr: 'order_date',
28
    editable: true,
29
  },
30
};
31

32
export const SELECT_LIST = Object.entries(COLUMNS)
33
  .map(([prop, { expr }]) => (expr === prop ? prop : `${expr} AS ${prop}`))
34
  .join(', ');
35

36
export function getColumn(prop: string): ColumnDef {
37
  const column = Object.hasOwn(COLUMNS, prop) ? COLUMNS[prop] : undefined;
38

39
  if (!column) {
40
    throw new Error(`Unknown column: ${prop}`);
41
  }
42

43
  return column;
44
}

What’s happening:

Filter values are bound as SQL parameters, but column names cannot be. The sort column and filter columns come from the grid as the prop of a column, so getColumn checks every prop against this map before it reaches SQL. A prop that is not in the map throws an error instead of becoming part of a query.

Each column also records how it appears in SQL. order_date is a DATE in the table, but the grid filters it as YYYY-MM-DD text, the same string it displays. Sorting still uses the real DATE column.

Map filter conditions to SQL

When the Filters plugin runs with dataProvider, every fetch receives the current filter state as filters. Each entry describes one column: its prop, a list of conditions (each a name and args), and an operation that combines them.

Handsontable condition	Text column	Numeric column
`eq`	`lower(col) = lower(?)`	`col = ?`
`neq`	`col IS NULL OR lower(col) <> lower(?)`	`col IS NULL OR col <> ?`
`contains`	`contains(lower(col), lower(?))`	-
`not_contains`	`col IS NULL OR NOT contains(lower(col), lower(?))`	-
`begins_with`	`starts_with(lower(col), lower(?))`	-
`ends_with`	`ends_with(lower(col), lower(?))`	-
`gt`, `gte`, `lt`, `lte`	-	`col > ?`, `col >= ?`, `col < ?`, `col <= ?`
`between`	-	`col BETWEEN ? AND ?`
`not_between`	-	`col < ? OR col > ?`
`empty`	`col IS NULL OR col = ''`	`col IS NULL`
`not_empty`	`col IS NOT NULL AND col <> ''`	`col IS NOT NULL`

The operation takes one of three values:

`operation`	Meaning	SQL
`conjunction`	All conditions match.	`a AND b`
`disjunction`	Any condition matches.	`a OR b`
`disjunctionWithExtraCondition`	Any of the first conditions matches, and the last one also matches.	`(a OR b) AND c`

Put the mapping in src/filterToSql.ts:

1
import type { DataProviderQueryParameters } from 'handsontable/plugins/dataProvider';
2
import { getColumn, type ColumnDef } from './schema';
3

4
type FilterColumn = NonNullable<DataProviderQueryParameters['filters']>[number];
5
type FilterCondition = FilterColumn['conditions'][number];
6

7
interface SqlFragment {
8
  sql: string;
9
  params: unknown[];
10
}
11

12
// Filter values arrive from the UI as strings. Numeric columns need numbers.
13
function toNumber(value: unknown): number | null {
14
  const number = Number(value);
15

16
  return value === '' || value === null || Number.isNaN(number) ? null : number;
17
}
18

19
// One Handsontable condition -> one SQL predicate with bound parameters.
20
// Text comparisons are case-insensitive, matching Handsontable's own conditions.
21
function conditionToSql(column: ColumnDef, condition: FilterCondition): SqlFragment | null {
22
  const { name, args } = condition;
23
  const e = column.expr;
24

25
  if (!name || name === 'none') {
26
    return null;
27
  }
28

29
  if (name === 'empty') {
30
    return { sql: column.kind === 'numeric' ? `${e} IS NULL` : `(${e} IS NULL OR ${e} = '')`, params: [] };
31
  }
32

33
  if (name === 'not_empty') {
34
    return { sql: column.kind === 'numeric' ? `${e} IS NOT NULL` : `(${e} IS NOT NULL AND ${e} <> '')`, params: [] };
35
  }
36

37
  if (column.kind === 'numeric') {
38
    const values = args.map(toNumber);
39
    const [a, b] = values;
40

41
    if (values.some((value) => value === null)) {
42
      console.warn(`[dataProvider] Ignoring "${name}": not a number`, args);
43

44
      return null;
45
    }
46

47
    switch (name) {
48
      case 'eq': return { sql: `${e} = ?`, params: [a] };
49
      case 'neq': return { sql: `(${e} IS NULL OR ${e} <> ?)`, params: [a] };
50
      case 'gt': return { sql: `${e} > ?`, params: [a] };
51
      case 'gte': return { sql: `${e} >= ?`, params: [a] };
52
      case 'lt': return { sql: `${e} < ?`, params: [a] };
53
      case 'lte': return { sql: `${e} <= ?`, params: [a] };
54
      // Handsontable accepts the two bounds in either order.
55
      case 'between':
56
        return { sql: `${e} BETWEEN ? AND ?`, params: [Math.min(a!, b!), Math.max(a!, b!)] };
57
      case 'not_between':
58
        return { sql: `(${e} < ? OR ${e} > ?)`, params: [Math.min(a!, b!), Math.max(a!, b!)] };
59
    }
60
  } else {
61
    const value = String(args[0] ?? '');
62

63
    switch (name) {
64
      case 'eq': return { sql: `lower(${e}) = lower(?)`, params: [value] };
65
      case 'neq': return { sql: `(${e} IS NULL OR lower(${e}) <> lower(?))`, params: [value] };
66
      case 'contains': return { sql: `contains(lower(${e}), lower(?))`, params: [value] };
67
      case 'not_contains': return { sql: `(${e} IS NULL OR NOT contains(lower(${e}), lower(?)))`, params: [value] };
68
      case 'begins_with': return { sql: `starts_with(lower(${e}), lower(?))`, params: [value] };
69
      case 'ends_with': return { sql: `ends_with(lower(${e}), lower(?))`, params: [value] };
70
    }
71
  }
72

73
  console.warn(`[dataProvider] Unsupported filter condition "${name}" on a ${column.kind} column, skipping`);
74

75
  return null;
76
}
77

78
function join(fragments: SqlFragment[], operator: 'AND' | 'OR'): SqlFragment | null {
79
  if (fragments.length === 0) {
80
    return null;
81
  }
82

83
  return {
84
    sql: `(${fragments.map((fragment) => fragment.sql).join(` ${operator} `)})`,
85
    params: fragments.flatMap((fragment) => fragment.params),
86
  };
87
}
88

89
function columnToSql(filter: FilterColumn): SqlFragment | null {
90
  const column = getColumn(filter.prop);
91
  const toFragments = (conditions: FilterCondition[]) => conditions
92
    .map((condition) => conditionToSql(column, condition))
93
    .filter((fragment): fragment is SqlFragment => fragment !== null);
94

95
  switch (filter.operation) {
96
    case 'disjunction':
97
      return join(toFragments(filter.conditions), 'OR');
98
    case 'disjunctionWithExtraCondition': {
99
      // (a OR b OR ...) AND last: the shape Handsontable's Filters plugin produces.
100
      // Split the conditions before mapping them, so a skipped last condition can't
101
      // promote one of the OR conditions to the AND side.
102
      const either = join(toFragments(filter.conditions.slice(0, -1)), 'OR');
103
      const extra = join(toFragments(filter.conditions.slice(-1)), 'AND');
104

105
      return join([either, extra].filter((fragment): fragment is SqlFragment => fragment !== null), 'AND');
106
    }
107
    default:
108
      return join(toFragments(filter.conditions), 'AND');
109
  }
110
}
111

112
// Builds the WHERE clause for every filtered column. Columns are always ANDed together.
113
export function filtersToWhere(filters: DataProviderQueryParameters['filters']): SqlFragment {
114
  const clause = join(
115
    (filters ?? [])
116
      .map(columnToSql)
117
      .filter((fragment): fragment is SqlFragment => fragment !== null),
118
    'AND',
119
  );
120

121
  return clause ? { sql: `WHERE ${clause.sql}`, params: clause.params } : { sql: '', params: [] };
122
}

What’s happening:

Case-insensitive text matching. Handsontable’s own eq, contains, and begins_with conditions ignore case, so the SQL compares lower() values. contains(), starts_with(), and ends_with() take the search text as a plain string, so a % or _ that a user types matches literally and needs no escaping.
Numbers arrive as strings. The filter inputs return text, so numeric arguments are converted with Number() before binding. A value that is not a number skips the condition instead of matching nothing.
Every operation is handled. A column filter with Or selected arrives as disjunction. The Filters plugin also produces disjunctionWithExtraCondition, so a mapping that treats every non-disjunction value as AND returns the wrong rows.
Unsupported conditions are skipped. A condition with no mapping logs a warning and is left out, so an unmapped filter never breaks a fetch.

Write the dataProvider functions

Create src/ordersProvider.ts. It builds each query from the schema.ts and filterToSql.ts helpers and exports the four functions the grid needs:

1
import type {
2
  DataProviderFetchOptions,
3
  DataProviderFetchResult,
4
  DataProviderQueryParameters,
5
  RowsCreatePayload,
6
  RowUpdatePayload,
7
} from 'handsontable/plugins/dataProvider';
8
import { exclusive, query } from './duckdb';
9
import { filtersToWhere } from './filterToSql';
10
import { getColumn, SELECT_LIST } from './schema';
11

12
export interface FetchStats {
13
  totalRows: number;
14
  ms: number;
15
}
16

17
// The App subscribes to this to show how long each fetch took.
18
let reportStats: (stats: FetchStats) => void = () => {};
19

20
export function onFetchStats(listener: (stats: FetchStats) => void) {
21
  reportStats = listener;
22
}
23

24
export async function fetchRows(
25
  { page, pageSize, sort, filters }: DataProviderQueryParameters,
26
  { signal }: DataProviderFetchOptions,
27
): Promise<DataProviderFetchResult> {
28
  const where = filtersToWhere(filters);
29
  const direction = sort?.order === 'desc' ? 'DESC' : 'ASC';
30
  // LIMIT/OFFSET needs a total order or pages can repeat or skip rows. With no sort,
31
  // newest rows come first; with a sort, id breaks ties (a region has ~250k rows).
32
  const orderBy = sort
33
    ? `${getColumn(sort.prop).sortExpr} ${direction}, id ${direction}`
34
    : 'id DESC';
35
  const limit = Math.max(1, Math.trunc(pageSize));
36
  const offset = Math.max(0, Math.trunc(page) - 1) * limit;
37

38
  const { rows, totalRows, ms } = await exclusive(async ({ conn }) => {
39
    const started = performance.now();
40
    const pageRows = await query(
41
      conn,
42
      `SELECT ${SELECT_LIST} FROM orders ${where.sql} ORDER BY ${orderBy} LIMIT ${limit} OFFSET ${offset}`,
43
      where.params,
44
    );
45
    const [{ total }] = await query<{ total: number }>(
46
      conn,
47
      `SELECT count(*) AS total FROM orders ${where.sql}`,
48
      where.params,
49
    );
50

51
    return { rows: pageRows, totalRows: total, ms: performance.now() - started };
52
  });
53

54
  // DuckDB-Wasm can't cancel a prepared query, so a superseded result is simply dropped.
55
  if (signal.aborted) {
56
    return { rows: [], totalRows: 0 };
57
  }
58

59
  reportStats({ totalRows, ms });
60

61
  return { rows, totalRows };
62
}
63

64
// DuckDB-Wasm binds JS numbers as DOUBLE, so integer-only arguments need an explicit cast.
65
export function onRowsCreate({ rowsAmount }: RowsCreatePayload): Promise<unknown[]> {
66
  return exclusive(({ conn }) => query(
67
    conn,
68
    `INSERT INTO orders
69
       SELECT id, 'ORD-' || lpad(id::VARCHAR, 7, '0'), 'New customer', 'North America',
70
              'Laptop', 1, 0, 'Pending', current_date
71
       FROM (SELECT nextval('orders_id_seq') AS id FROM range(CAST(? AS BIGINT)))
72
     RETURNING id`,
73
    [rowsAmount],
74
  ));
75
}
76

77
function toSqlValue(prop: string, value: unknown): unknown {
78
  const column = getColumn(prop);
79

80
  if (!column.editable) {
81
    throw new Error(`${prop} is read-only`);
82
  }
83

84
  if (column.kind === 'numeric') {
85
    const number = Number(value);
86

87
    if (value === '' || value === null || Number.isNaN(number)) {
88
      throw new Error(`${prop} must be a number`);
89
    }
90

91
    return number;
92
  }
93

94
  return value === null || value === undefined ? null : String(value);
95
}
96

97
// All edits from one user action (a paste can touch hundreds of rows) commit in one transaction.
98
export function onRowsUpdate(rows: RowUpdatePayload[]): Promise<void> {
99
  return exclusive(async ({ conn }) => {
100
    await conn.query('BEGIN TRANSACTION');
101

102
    try {
103
      for (const { id, changes } of rows) {
104
        const props = Object.keys(changes);
105
        const assignments = props.map((prop) => (getColumn(prop).kind === 'date'
106
          ? `${prop} = CAST(? AS DATE)`
107
          : `${prop} = ?`));
108
        const values = props.map((prop) => toSqlValue(prop, changes[prop]));
109

110
        if (props.length > 0) {
111
          await query(conn, `UPDATE orders SET ${assignments.join(', ')} WHERE id = ?`, [...values, Number(id)]);
112
        }
113
      }
114

115
      await conn.query('COMMIT');
116
    } catch (error) {
117
      await conn.query('ROLLBACK');
118
      throw error;
119
    }
120
  });
121
}
122

123
export function onRowsRemove(rowIds: unknown[]): Promise<void> {
124
  const ids = rowIds.map(Number).filter(Number.isInteger);
125

126
  return exclusive(async ({ conn }) => {
127
    if (ids.length > 0) {
128
      await query(conn, `DELETE FROM orders WHERE id IN (${ids.map(() => '?').join(', ')})`, ids);
129
    }
130
  });
131
}

What’s happening:

fetchRows always orders the rows completely. LIMIT and OFFSET without a total order can return rows in a different order on each call, so a row can appear on two pages or on none. With no sort, the newest rows come first. With a sort, id breaks ties: a million orders across four regions means about 250,000 rows share each region value.
The count uses the same WHERE clause. The second query counts every row that matches the filters, which drives the pagination bar.
A superseded fetch is dropped, not canceled. DuckDB-Wasm cannot cancel a prepared statement from an AbortSignal. When the user pages or sorts before a query finishes, fetchRows checks signal.aborted after the query and returns an empty result, which the plugin discards.
The grid refetches after every mutation. After onRowsCreate, onRowsUpdate, or onRowsRemove succeeds, the plugin calls fetchRows again, and that refetch is what updates the grid. New rows take the next id from the sequence, so they appear at the top of page 1.
One user action, one transaction. A paste can change hundreds of rows at once, and they all arrive in a single onRowsUpdate call. The function commits them together, and rolls all of them back if any value is invalid. The plugin then reverts the cells and shows the error.
JavaScript numbers bind as DOUBLE. range() accepts only BIGINT, so onRowsCreate casts its argument. Apply the same cast anywhere a function needs an integer type.

Build the grid component

Create src/OrdersGrid.tsx:

1
import { forwardRef, memo } from 'react';
2
import { HotTable, type HotTableRef } from '@handsontable/react-wrapper';
3
import type { GridSettings } from 'handsontable/settings';
4
import { registerAllModules } from 'handsontable/registry';
5
import 'handsontable/styles/handsontable.min.css';
6
import 'handsontable/styles/ht-theme-main.min.css';
7

8
import { fetchRows, onRowsCreate, onRowsRemove, onRowsUpdate } from './ordersProvider';
9

10
registerAllModules();
11

12
// Defined once at module level. The wrapper passes changed props to updateSettings(), and a
13
// new dataProvider object makes the plugin refetch. Inline literals would refetch on every
14
// parent render, and since each fetch updates the parent's stats, the grid would never settle.
15
const DATA_PROVIDER: GridSettings['dataProvider'] = {
16
  rowId: 'id',
17
  fetchRows,
18
  onRowsCreate,
19
  onRowsUpdate,
20
  onRowsRemove,
21
};
22

23
const COL_HEADERS = ['ID', 'Order', 'Customer', 'Region', 'Product', 'Qty', 'Unit price', 'Status', 'Order date'];
24

25
const COLUMNS: GridSettings['columns'] = [
26
  { data: 'id', type: 'numeric', readOnly: true },
27
  { data: 'order_no', type: 'text', readOnly: true, width: 130 },
28
  { data: 'customer', type: 'text', width: 170 },
29
  { data: 'region', type: 'text', width: 130 },
30
  { data: 'product', type: 'text', width: 120 },
31
  { data: 'quantity', type: 'numeric', width: 80 },
32
  { data: 'unit_price', type: 'numeric', numericFormat: { style: 'currency', currency: 'USD' }, width: 110 },
33
  { data: 'status', type: 'text', width: 110 },
34
  { data: 'order_date', type: 'text', width: 110 },
35
];
36

37
const HIDDEN_COLUMNS = { columns: [0] };
38
const PAGINATION = { pageSize: 50 };
39
const DROPDOWN_MENU = ['filter_by_condition', 'filter_operators', 'filter_by_condition2', 'filter_action_bar'];
40
const CONTEXT_MENU = ['row_above', 'row_below', 'remove_row'];
41

42
// memo keeps parent re-renders (the stats bar updates after every fetch) away from HotTable.
43
const OrdersGrid = memo(forwardRef<HotTableRef>((_, ref) => (
44
  <HotTable
45
    // licenseKey="your-license-key" // get a key at https://handsontable.com/pricing/
46
    ref={ref}
47
    themeName="ht-theme-main"
48
    dataProvider={DATA_PROVIDER}
49
    colHeaders={COL_HEADERS}
50
    columns={COLUMNS}
51
    hiddenColumns={HIDDEN_COLUMNS}
52
    // Counts hidden columns too: id (hidden), order_no and customer.
53
    fixedColumnsStart={3}
54
    pagination={PAGINATION}
55
    // Single-column, server-driven sort. multiColumnSorting would disable dataProvider.
56
    columnSorting={true}
57
    filters={true}
58
    dropdownMenu={DROPDOWN_MENU}
59
    notification={true}
60
    emptyDataState={true}
61
    contextMenu={CONTEXT_MENU}
62
    rowHeaders={true}
63
    height={620}
64
    stretchH="all"
65
  />
66
)));
67

68
export default OrdersGrid;

What’s happening:

Every prop is defined once, outside the component. The React wrapper passes changed props to updateSettings(), and a new dataProvider object makes the plugin fetch again. If you write the config inline, every parent render triggers a refetch. In this app, every fetch updates the parent’s status bar, so the grid would refetch forever and never leave its loading state. Module-level constants and memo keep the grid out of that loop.
columnSorting, not multiColumnSorting. The dataProvider plugin sends one sort column to fetchRows, and it does not enable when multiColumnSorting is on.
No filter by value. In server mode, the Filter by value checklist could only list the values on the loaded page, so dropdownMenu leaves it out. The condition filters from Step 4 run against all million rows.
fixedColumnsStart counts hidden columns. The frozen span starts at the hidden id column, so fixedColumnsStart={3} freezes the two visible columns, order_no and customer. With {2}, only order_no would stay in place.
notification shows errors as toasts. A failed fetch or a rejected edit, such as an invalid date, appears as a toast with DuckDB’s error message.

Load and export Parquet or CSV

Replace src/App.tsx:

1
import { useEffect, useRef, useState, type ChangeEvent } from 'react';
2
import type { HotTableRef } from '@handsontable/react-wrapper';
3

4
import OrdersGrid from './OrdersGrid';
5
import { onFetchStats, type FetchStats } from './ordersProvider';
6
import { exportParquet, loadFile, ROW_COUNT, seedOrders } from './seed';
7

8
type Status =
9
  | { state: 'loading' }
10
  | { state: 'ready'; seedMs: number }
11
  | { state: 'error'; message: string };
12

13
const format = new Intl.NumberFormat('en-US');
14

15
// StrictMode runs effects twice in development; seed only once per page load.
16
let seeding: Promise<number> | null = null;
17

18
function seedOnce(): Promise<number> {
19
  seeding ??= (async () => {
20
    const started = performance.now();
21

22
    await seedOrders();
23

24
    return performance.now() - started;
25
  })();
26

27
  return seeding;
28
}
29

30
export default function App() {
31
  const gridRef = useRef<HotTableRef>(null);
32
  const fileInputRef = useRef<HTMLInputElement>(null);
33
  const [status, setStatus] = useState<Status>({ state: 'loading' });
34
  const [stats, setStats] = useState<FetchStats | null>(null);
35
  const [message, setMessage] = useState('');
36

37
  useEffect(() => {
38
    onFetchStats(setStats);
39
    seedOnce()
40
      .then((seedMs) => setStatus({ state: 'ready', seedMs }))
41
      .catch((error: Error) => setStatus({ state: 'error', message: error.message }));
42
  }, []);
43

44
  async function handleFile(event: ChangeEvent<HTMLInputElement>) {
45
    const file = event.target.files?.[0];
46

47
    event.target.value = '';
48

49
    if (!file) {
50
      return;
51
    }
52

53
    setMessage(`Loading ${file.name}…`);
54

55
    try {
56
      const total = await loadFile(file);
57

58
      setMessage(`Loaded ${format.format(total)} rows from ${file.name}`);
59
      await gridRef.current?.hotInstance?.getPlugin('dataProvider').fetchData({ page: 1 });
60
    } catch (error) {
61
      setMessage(`Couldn't load ${file.name}: ${(error as Error).message}`);
62
    }
63
  }
64

65
  async function handleExport() {
66
    try {
67
      const url = URL.createObjectURL(await exportParquet());
68
      const link = Object.assign(document.createElement('a'), { href: url, download: 'orders.parquet' });
69

70
      link.click();
71
      // Revoke after the click is handled, so the browser has started the download.
72
      setTimeout(() => URL.revokeObjectURL(url), 0);
73
    } catch (error) {
74
      setMessage(`Couldn't export: ${(error as Error).message}`);
75
    }
76
  }
77

78
  return (
79
    <main>
80
      <header>
81
        <h1>{format.format(ROW_COUNT)} rows, no backend</h1>
82
        <p>
83
          Handsontable's <code>dataProvider</code> sends every page, sort, filter and edit to
84
          DuckDB-Wasm running in a Web Worker. The grid only ever holds one page.
85
        </p>
86
      </header>
87

88
      <section className="toolbar" aria-live="polite">
89
        {status.state === 'loading' && <span>Generating {format.format(ROW_COUNT)} rows in DuckDB…</span>}
90
        {status.state === 'error' && <span className="error">DuckDB failed to start: {status.message}</span>}
91
        {status.state === 'ready' && (
92
          <>
93
            <span className="stat">Seeded in <strong>{Math.round(status.seedMs)} ms</strong></span>
94
            {stats && (
95
              <>
96
                <span className="stat">Matching rows <strong>{format.format(stats.totalRows)}</strong></span>
97
                <span className="stat">Last query <strong>{stats.ms.toFixed(1)} ms</strong></span>
98
              </>
99
            )}
100
            <span className="spacer" />
101
            {/* A native button stays in the tab order and opens the hidden file input. */}
102
            <button type="button" className="button" onClick={() => fileInputRef.current?.click()}>
103
              Load Parquet or CSV
104
            </button>
105
            <input ref={fileInputRef} type="file" accept=".parquet,.csv" onChange={handleFile} hidden />
106
            <button type="button" className="button" onClick={handleExport}>Export Parquet</button>
107
          </>
108
        )}
109
      </section>
110

111
      {message && <p className="message">{message}</p>}
112

113
      {status.state === 'ready' && <OrdersGrid ref={gridRef} />}
114
    </main>
115
  );
116
}

What’s happening:

The grid mounts after the data exists. App seeds the table first, then renders OrdersGrid, so the first fetch never queries a missing table. seedOnce keeps React’s development double mount from generating the table twice.
A user’s file stays in the browser. loadFile from Step 2 registers the file with DuckDB under a fixed internal name, so the user’s file name never appears in SQL. It reads Parquet with read_parquet and CSV with read_csv_auto, and casts every column to the demo schema. The rows land in a temporary table first, and loadFile rejects the file if any id is missing or repeated, because edits and deletes match rows by id: two rows with the same id would change or disappear together. A file that fails a check, or lacks a column, shows the error, and the current table stays as it was. App then calls fetchData({ page: 1 }) on the plugin to show the new data.
Export writes the current table. exportParquet runs COPY orders TO 'orders.parquet' inside DuckDB’s virtual file system and hands the bytes to the browser as a download, edits included.
The file picker is a real button. A hidden <input type="file"> is not in the tab order, so a native <button> opens it through a ref. Keyboard users can reach and press Load Parquet or CSV like any other button.
The status bar reads each fetch. onFetchStats reports the matching row count and the query time. Updating App state is safe here because OrdersGrid does not re-render with it.

Run npm run dev and open the app. Sort a column, filter by region, or page to the end to see the query time for each change.

How it works — complete flow

App starts DuckDB in a worker and runs the seed SQL. When the table exists, it renders OrdersGrid.
Handsontable calls fetchRows with { page: 1, pageSize: 50 }. DuckDB returns the 50 newest orders and the total count, and the grid renders the page.
The user clicks the Qty header. Handsontable calls fetchRows with sort: { prop: 'quantity', order: 'asc' }, and DuckDB runs ORDER BY quantity ASC, id ASC.
The user filters Region to contain emea. filtersToWhere builds WHERE (contains(lower(region), lower(?))) and binds 'emea'. The status bar shows the new match count.
The user edits a cell. Handsontable calls onRowsUpdate with [{ id, changes }]. The update commits in a transaction, and the plugin refetches the page.
The user inserts a row from the context menu. onRowsCreate takes the next id from the sequence, and the refetch shows the new row at the top of page 1.
The user deletes rows. onRowsRemove receives their id values and runs one DELETE ... WHERE id IN (...).

Known limitations

The data lives in the tab. DuckDB keeps the table in the worker’s memory, and a reload regenerates it. Use Export Parquet to keep edits. For automatic persistence, DuckDB-Wasm can also store a database file in the browser’s Origin Private File System (OPFS).
The engine is a large download. The EH .wasm file is about 34 MB, or about 8 MB compressed. Serve it with compression and long-term caching, and show a loading state while it starts.
Memory grows with the data. The million generated rows fit comfortably in a desktop browser. Larger files are limited by the memory the browser gives the tab.
Uploaded files must match the schema. loadFile expects the demo columns. To support any file, read its columns with DESCRIBE and build the grid’s columns and the schema.ts map from them.
A development warning in React StrictMode. StrictMode mounts the grid, unmounts it, and mounts it again. With Handsontable 18.1.2, the discarded first instance logs Data fetch failed: TypeError: Cannot read properties of undefined (reading 'runHooks'). The second instance loads normally, and production builds do not double-mount.

What you learned

How to run DuckDB-Wasm in a Web Worker and serve its files with Vite, with no CDN and no cross-origin isolation headers.
How dataProvider drives pagination, sorting, filtering, and CRUD through four functions, whatever the data source.
Why LIMIT and OFFSET need a tiebreaker column to return stable pages.
How to map all three filter operations, including disjunctionWithExtraCondition, to SQL.
Why grid props must stay referentially stable when a parent re-renders on every fetch.
How to load a user’s Parquet or CSV file in the browser and export the table back to Parquet.

Next steps

Server-side data overview — the full dataProvider API, lifecycle hooks, and options that do not work in server-side mode.
Fetching data — the query parameters, beforeDataProviderFetch, and abort behavior.
CRUD operations — the mutation lifecycle, optimistic updates, and programmatic CRUD.
Server-side data with Supabase — the same four functions against a hosted Postgres database.
DuckDB-Wasm documentation — data ingestion, extensions, and OPFS persistence.