Downloads 681this week

GitHub stars 25

Extension descriptor (YAML)

GPU-accelerated plain DuckDB SQL on Apple Silicon Metal and NVIDIA CUDA - GROUP BY, joins, filters and top-k run on the GPU when measured faster, with the same answers. First SQL execution engine that targets Apple Silicon GPUs.

Installing and Loading

INSTALL gpudb FROM community;
LOAD gpudb;

Example

LOAD gpudb;

-- which processor will run, and what this build can do
SELECT gpu_build_info();

-- make a (key, value) pair resident on the GPU once ...
CREATE TABLE sales AS
  SELECT (range % 1000)::BIGINT AS store, (range * 7 % 10007)::BIGINT AS amount
  FROM range(10000000);
SELECT gpu_upload_pair('sales_by_store', store, amount) FROM sales;

-- ... then ask as often as you like: GROUP BY, HAVING and top-k run on the device
-- top 5 stores by sum(amount): (store, sum, count)
SELECT * FROM gpu_groupby_sum_resident_topk('sales_by_store', 5, 'desc');

-- backend, rows, wall time and kernel time of the last call
SELECT gpu_last_stats();

About gpudb

Plain DuckDB SQL on the GPU

gpudb is DuckDB plus a GPU. You write the SQL you already write. A statement is answered by the GPU when that has been measured to be faster for its shape and size on your machine, and by DuckDB — untouched, at its usual speed — otherwise. Rows, column names and column types are identical either way.

Two rules hold everywhere and are enforced by the test gates the project ships:

1. Never slower than DuckDB. Every rewritten shape is timed against native; a shape that loses is left to DuckDB, and the losing measurements stay published.
2. Never a different answer. Integer and DECIMAL aggregates are bit-exact (128-bit sums on the device). Anything DuckDB itself computes order-dependently — sum(DOUBLE) — is never rewritten.

Three ways in

The first two put plain SQL on the device and need the Python package as well as this extension, because DuckDB's stable C API has no hook that sees a statement before it is planned: pip install duckdb-gpudb. On Apple Silicon (macOS 15 or later) and x86-64 Linux (glibc 2.34 or newer) that wheel carries a matching extension binary inside it, which is the quickest way to plain SQL on the GPU; elsewhere it uses the extension DuckDB has installed from this registry. The third needs no wrapper: loaded in any DuckDB client, this extension gives the explicit gpu_* functions.

1. The gpudb shell — a SQL shell whose footer says, under every result, where the statement ran and why.

$ gpudb my.duckdb
gpudb> SELECT l_partkey, sum(l_quantity) AS qty FROM lineitem
       GROUP BY l_partkey ORDER BY qty DESC LIMIT 5;
...
GPU (topk: the resident GROUP BY)

2. Python — gpudb.connect() — the same decision, for applications and notebooks.

import gpudb
con = gpudb.connect("my.duckdb")        # same surface as duckdb.connect()
con.sql("SELECT l_partkey, sum(l_quantity) AS qty FROM lineitem "
        "GROUP BY l_partkey ORDER BY qty DESC LIMIT 5")
con.last_rewrite()                      # what ran where, and why

Tables become resident in the background, in short segments taken only while the connection is idle. A memory budget decides what stays on the device by measured value; what does not fit simply runs on DuckDB.

3. Explicit gpu_* functions — any DuckDB client, including the CLI. This is the only route that needs no wrapper, because DuckDB's stable C API has no hook that sees a statement before it is planned. gpu_upload / gpu_upload_pair make columns resident once; gpu_sum_resident, gpu_groupby_sum_resident (_having, _topk), gpu_topk_resident, gpu_inner_join and the exact gpu_groupby_exact_* family read them from GPU memory. gpu_last_stats() reports which processor ran and for how long.

What runs on the device

sum(DOUBLE) stays on DuckDB by design: DuckDB's own result depends on the order the values are added, so there is no single answer for a GPU to match. The explicit gpu_sum functions remain available for it, with a stated 1e-9 relative tolerance.

Measured (TPC-H, every row compared with native DuckDB)

Release build of 2026-09-20, default memory budget, N=5. A statement reaches the GPU through execute() or through sql() — two different code paths, timed separately:

Plain SQL runs on the GPU by default on both backends. One row is below 1.0x and is printed rather than dropped: TPC-H Q11 at SF10 on Metal, a 6-7 ms statement measuring 1.06x through execute() and 0.92x through sql(), which straddles parity - the per-process measured rule is what declines such a statement where it loses. Nothing on CUDA is below 1.0x in these runs: Q1 first measured 0.96x and 0.98x there on the release build, the cause was found (a few-group key was being answered by sorting the whole column), CUDA got a direct grouped reduce for such keys, and Q1 now measures 1.99x and 2.07x.

The remaining queries are declined on purpose (correlated subqueries, or shapes where DuckDB was measured faster) and run on DuckDB unchanged. Every measurement, including the shapes where the GPU loses, is in BENCHMARK.md; every trade-off is in KNOWN_ISSUES.md; the dated engineering journal is docs/RESEARCH_NOTES.md.

Platforms

The extension is written in C++ and touches DuckDB through its stable C API only (the C_STRUCT ABI): it links no libduckdb, includes no DuckDB C++ headers and does no plan surgery.

Guides: the gpudb shell https://github.com/singhpratech/duckdbgpumetaldbram/blob/main/docs/USING_THE_SHELL.md , gpudb.connect() https://github.com/singhpratech/duckdbgpumetaldbram/blob/main/docs/USING_PYTHON.md , installing both pieces https://github.com/singhpratech/duckdbgpumetaldbram/blob/main/docs/INSTALL.md

Source, benchmarks and issues: https://github.com/singhpratech/duckdbgpumetaldbram

Added Functions

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings

This extension does not add any settings.