Sirius

Sirius is a GPU-Native Composable Analytics Engine. It plugs into existing databases via the standard Substrait query format, requiring no query rewrites or major system changes. Sirius currently supports DuckDB and Starrocks (coming soon), other systems marked with * are on our roadmap. Built on NVIDIA CUDA-X libraries including cuDF, cuVS, and cuCascade, Sirius delivers high-performance GPU-accelerated analytics.

Concurrent queries

Use separate connections to one DuckDB DatabaseInstance and set startup sirius.max_concurrent_queries (default 1). See the concurrent-query guide for admission, maintenance, cancellation, memory pressure and qualification scope.

Performance

TPC-H hot runs on AWS, 22 queries · best Sirius g7e size vs DuckDB on m9g.16xlarge · cost per run, log scales · lower left is better.

For the legacy Sirius implementation used for the ClickBench results, see the legacy-dev archive (pinned at f79a6f42).

Requirements

• Linux on amd64/x86_64 or arm64/aarch64 with glibc >= 2.28.
• NVIDIA Turing or newer, with compute capability 7.5+.
• CUDA 13.x (driver 580.65.06 or newer) or CUDA 12.x (driver 525.60.13 or newer).
• io_uring enabled at runtime (CONFIG_IO_URING, kernel.io_uring_disabled=0 recommended). Containers must allow io_uring_setup, io_uring_enter, and io_uring_register.
• Local Parquet files should be on a filesystem/block device that supports direct I/O (O_DIRECT).

Build Requirements

• Git (to clone the repo)
• Pixi (install instructions here)

Installing a Prebuilt Sirius Release

Getting started? Download one of our prebuilt extensions instead of building from source:

• stable: a maintainer-selected build, promoted manually
• latest: tracks the newest successful build on main automatically, possible to encounter breaking changes

Both include full install instructions in the release notes: installing a matching DuckDB version, downloading the right binary for your platform, and a sample query to try it with.

Building and Running Sirius

For full build instructions, alternate build types, pre-commit setup, and testing, see DEVELOPMENT.md.

Quick start:

git clone --no-recurse-submodules https://github.com/sirius-db/sirius.git
cd sirius
git submodule update --init --depth=1 --jobs 5 duckdb substrait cucascade sirius-duckdb/duckdb sirius-duckdb/extension-ci-tools
pixi run make TEST_BUILD_TARGET=
pixi run duckdb

Alternatively, load the extension into an existing DuckDB shell:

LOAD 'sirius-duckdb/build/release/extension/sirius/sirius.duckdb_extension';

Either way, all DuckDB queries are automatically intercepted by the optimizer hook and run on GPU — no query rewrites required. Queries with unsupported operators fall back silently to CPU.

-- Load the TPC-H extension and generate data (scale factor 10 = ~10 GB)
INSTALL tpch;
LOAD tpch;
CALL dbgen(sf=10);

-- Plain SQL runs on GPU automatically
SELECT l_returnflag, sum(l_quantity)
FROM lineitem
GROUP BY l_returnflag
ORDER BY l_returnflag;

-- TPC-H data is exported as Parquet for use in later examples
COPY lineitem TO '/path/to/lineitem.parquet' (FORMAT PARQUET);

-- Disable transparent GPU execution for this connection
SET gpu_execution = false;
-- ... or for every connection of this database instance without a session value
SET GLOBAL gpu_execution = false;

Execution is out-of-core with tiered memory management (GPU/host/disk), automatic data partitioning, and spilling, and works with both Parquet and DuckDB-native storage. See gpu_execution for build, configuration, and testing details.

Python API

Use Sirius through DuckDB's Python API: load the extension, execute SQL, and fetch results. Supported queries run on the GPU automatically, just as they do in the DuckDB shell.

The v2 extension requires the exact DuckDB revision pinned in this repository. Use the built CLI above. The default environment's DuckDB 1.5 Python package cannot load this extension; Python use requires a package built from the matching revision.

Save this example as example.py in the repository root and replace /path/to/lineitem.parquet with your TPC-H Parquet file. allow_unsigned_extensions allows loading the locally built extension.

import duckdb

con = duckdb.connect(":memory:", config={"allow_unsigned_extensions": "true"})
con.execute("""
    CREATE VIEW lineitem AS
    SELECT * FROM read_parquet('/path/to/lineitem.parquet')
""")

con.execute("LOAD 'sirius-duckdb/build/release/extension/sirius/sirius.duckdb_extension'")
rows = con.execute("""
    SELECT l_returnflag, SUM(l_quantity) AS total_quantity
    FROM lineitem
    GROUP BY l_returnflag
    ORDER BY l_returnflag
""").fetchall()

print(rows)
con.close()

Run it from the repository root:

pixi run python example.py

For an example using TPC-H data from Parquet files or a DuckDB database, see the Python benchmark script.

The Python benchmark and power/throughput runners require a Python DuckDB client built from the pinned v2 revision; the default environment's 1.5 client cannot load this extension. The CLI-based scripts use the built v2 host.

Pinning Tables for Hot Runs

Sirius reads table data from storage on every query. For the best hot-run performance, pin frequently queried tables: pin_table materializes a table's columns into memory once, and subsequent queries over that source are served straight from the pinned copy, skipping file I/O and decode entirely. Queries don't change — pinned tables are matched automatically.

-- Pin a parquet file (or glob) into GPU memory; omit cols to pin all columns
CALL pin_table('/path/to/lineitem.parquet', name = 'lineitem', tier = 'gpu',
               cols = ['l_orderkey', 'l_quantity', 'l_extendedprice', 'l_shipdate']);

-- Pin a DuckDB base table
CALL pin_table(format = 'duckdb', name = 'my_table', tier = 'gpu');

-- Served from the pinned copy — no file I/O
SELECT sum(l_extendedprice * l_quantity)
FROM read_parquet('/path/to/lineitem.parquet')
WHERE l_shipdate >= DATE '1994-01-01';

-- Release the pinned memory
CALL unpin_table('lineitem');

tier = 'gpu' pins columns in GPU memory for the fastest scans; tier = 'host' pins them in pinned host memory instead, for tables larger than GPU memory.

Deletes and committed inserts on pinned DuckDB tables are reconciled per query. UPDATE, MERGE ... UPDATE, and INSERT ... ON CONFLICT DO UPDATE are rejected while the target table is pinned; run CALL unpin_table(...) before updating it. An explicit CHECKPOINT while a pin is live makes that pin ineligible to serve: subsequent queries fall back or error until the table is unpinned and pinned again.

Compression with Simpatico

Sirius can use Simpatico to compress pinned data in GPU or host memory. After loading Sirius, set both compression options before calling pin_table. This example runs from the repository root and uses the bundled TPC-H SF1000 compression plans:

SET pin_table_compression = true;
SET pin_table_input_compression_plan_dir = 'src/compression/simpatico_codegen/plans/tpch_sf1000';

CALL pin_table('/path/to/lineitem.parquet', name = 'lineitem', tier = 'gpu',
               cols = ['l_returnflag', 'l_quantity']);

-- Normal SQL reads the compressed pinned data automatically
SELECT l_returnflag, SUM(l_quantity) AS total_quantity
FROM read_parquet('/path/to/lineitem.parquet')
GROUP BY l_returnflag
ORDER BY l_returnflag;

CALL unpin_table('lineitem');

Use tier = 'host' to pin compressed data in host memory. For other datasets, point the plan directory at plans matching your table schemas. A plan file must match the pinned table's name (for example, lineitem.txt) and contain one column plan per full-table column in schema order. Tables without a matching plan, small batches, and batches with insufficient compression savings remain uncompressed. To change whether an existing pin is compressed, unpin and pin it again. Restart the process when changing a previously loaded compression plan.

From Python, execute the same SQL with con.execute(...) after loading the extension and before querying. See the compressed pinning guide for plan selection and tuning.

Configuration

Sirius loads its settings from a YAML config file, searched in this order:

1. Path in the SIRIUS_CONFIG_FILE environment variable
2. ./sirius.yaml (current working directory)
3. ~/.sirius/sirius.yaml

If no config file is found, built-in defaults apply (95% GPU memory, 8 GiB pinned host memory per NUMA node). See the Configuration reference for all options: memory tiers, thread pools, operator parameters, and runtime SET variables. An example config is provided at test/cpp/integration/integration.yaml.

Logging

Sirius uses spdlog for logging messages during query execution. Default log directory is log (relative to the current working directory) and default log level is info.

Log directory and level can be initialized via environment variables before loading the extension:

export SIRIUS_LOG_DIR=/path/to/logs
export SIRIUS_LOG_LEVEL=trace

Both can also be configured at runtime via DuckDB's SET command:

SET sirius_log_dir = '/path/to/logs';
SET sirius_log_level = 'trace';
SET sirius_log_flush_seconds = 1;

Tracing

Note: Tracing is experimental and the telemetry schema may change.

Sirius instruments query execution with Quent, emitting per-query traces of operator and pipeline activity that Quent can render as an interactive browser timeline. Enable it in your YAML config file,

sirius:
  telemetry:
    enable_quent: true
    output_directory: telemetry_data

run queries, then visualize:

pixi run quent   # serves Quent UI at http://localhost:8080

See the Quent Telemetry guide for the full setup details: enabling the exporter, per-query labeling, generating telemetry (using a TPC-H helper), and visualization.

Limitations

Sirius is under active development. Notable current limitations include:

• Data Type Coverage: Sirius currently supports commonly used data types including INTEGER, BIGINT, FLOAT, DOUBLE, VARCHAR, DATE, TIMESTAMP, and DECIMAL. We are actively working on supporting additional data types—such as nested types.

• Operator Coverage: At present, Sirius supports FILTER, PROJECTION, JOIN (Hash/Nested Loop/Delim), GROUP-BY, ORDER-BY, AGGREGATION, TOP-N, LIMIT, and CTE. We are working on adding more advanced operators such as WINDOW functions and ASOF JOIN.

• DuckDB v2 regex rewrites: Whole-input backreference replacements, including the ClickBench Q28 URL pattern, are rewritten to regexp_extract(..., 'k') and currently require CPU fallback instead of using the GPU regex implementation. Tracked in #2146.

For a full list of current limitations and ongoing work, please refer to our GitHub issues page. Unsupported types and operators fall back to DuckDB CPU execution when fallback is enabled.

Contributors and Partners

Future Roadmap

Sirius is still under major development and we are working on adding more features to Sirius, such as multi-node, more operators, data types, accelerating more engines, and many more.

Sirius always welcomes new contributors! If you are interested, check our website, reach out to our email, or join our slack channel.

Let's kickstart the GPU eras for Data Analytics!