Getting started

A short path from zero to a first model on DuckDB 2.0.0+. The usual path is a community install; clone and build only if you are developing duckboost or need a custom binary.

NoteDuckDB 1.x

DuckDB 1.x cannot load this extension. Use a DuckDB 2.0.0 (or newer) CLI, Python, R, or other client. Listing: duckboost on Community Extensions.

1. Install and load

In any DuckDB 2.0.0+ session:

INSTALL duckboost FROM community;
LOAD duckboost;

Confirm the backends this binary can train or import:

SELECT backend, training_supported, notes
FROM duckboost_backends()
ORDER BY backend;
LOAD duckboost;
SELECT backend, training_supported, notes
FROM duckboost_backends()
ORDER BY backend;
┌───────────┬────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│  backend  │ training_supported │                                                notes                                                 │
├───────────┼────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ catboost  │ false              │ import save_model JSON via duckboost_import; native train requires dump import (no public C API)     │
│ lightgbm  │ false              │ import save_model text via duckboost_import; native train requires DUCKBOOST_WITH_LIGHTGBM           │
│ reference │ true               │ in-process native histogram GBDT (backend aliases: native, reference; train/predict/evaluate/to_sql) │
│ xgboost   │ false              │ import dump_model JSON via duckboost_import; native train requires DUCKBOOST_WITH_XGBOOST            │
└───────────┴────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────┘

training_supported is true only for backends this binary can train in-process. Community builds enable the native histogram trainer (pass backend = 'native' in train options; model JSON may still say "reference"). XGBoost, LightGBM, and CatBoost stay import-only unless you linked the vendor libraries — see the README build notes.

2. First model

Train a small body-mass regression on the Palmer penguins data. Named features, an explicit target, and training RMSE show the usual loop: table → feature list → duckboost_train → metric.

The SQL below loads the public CSV over HTTPS (httpfs autoloads on released DuckDB). Each block on this site starts a new in-memory database.

LOAD duckboost;

CREATE TABLE penguins AS
SELECT
  body_mass_g::DOUBLE AS body_mass_g,
  [bill_length_mm, bill_depth_mm, flipper_length_mm, (sex = 'male')::DOUBLE] AS features
FROM read_csv('https://raw.githubusercontent.com/allisonhorst/palmerpenguins/master/inst/extdata/penguins.csv', nullstr = 'NA')
WHERE body_mass_g IS NOT NULL
  AND bill_length_mm IS NOT NULL
  AND sex IS NOT NULL;

CREATE TABLE models AS
SELECT duckboost_train(
  body_mass_g, features,
  MAP {
    'backend': 'native',
    'n_estimators': '40',
    'max_depth': '3',
    'learning_rate': '0.15',
    'feature_names': 'bill_length_mm,bill_depth_mm,flipper_length_mm,male'
  }
) AS model
FROM penguins;

SELECT round(duckboost_evaluate_agg(
  model, body_mass_g, features, MAP {'metric': 'rmse'}
), 1) AS rmse_g
FROM models, penguins;
┌────────┐
│ rmse_g │
├────────┤
│ 224.4  │
└────────┘

A few predictions next to the measured mass:

LOAD duckboost;

CREATE TABLE penguins AS
SELECT
  body_mass_g::DOUBLE AS body_mass_g,
  [bill_length_mm, bill_depth_mm, flipper_length_mm, (sex = 'male')::DOUBLE] AS features
FROM read_csv('https://raw.githubusercontent.com/allisonhorst/palmerpenguins/master/inst/extdata/penguins.csv', nullstr = 'NA')
WHERE body_mass_g IS NOT NULL
  AND bill_length_mm IS NOT NULL
  AND sex IS NOT NULL;

CREATE TABLE models AS
SELECT duckboost_train(
  body_mass_g, features,
  MAP {
    'backend': 'native',
    'n_estimators': '40',
    'max_depth': '3',
    'learning_rate': '0.15',
    'feature_names': 'bill_length_mm,bill_depth_mm,flipper_length_mm,male'
  }
) AS model
FROM penguins;

SELECT
  round(body_mass_g, 0) AS body_mass_g,
  round(duckboost_predict(model, features), 0) AS pred_g
FROM models, penguins
ORDER BY body_mass_g
LIMIT 5;
┌─────────────┬────────┐
│ body_mass_g │ pred_g │
├─────────────┼────────┤
│ 2700.0      │ 3140.0 │
│ 2850.0      │ 2955.0 │
│ 2850.0      │ 3195.0 │
│ 2900.0      │ 3026.0 │
│ 2900.0      │ 3272.0 │
└─────────────┴────────┘

Build from source (optional)

Use this path when contributing to duckboost, debugging, or building with optional vendor trainers.

Prerequisites

  • git
  • A C++17 compiler (clang or gcc)
  • cmake and make (optional: ninja)

On macOS, Xcode Command Line Tools plus Homebrew cmake is enough. On Ubuntu/Debian, build-essential and cmake cover it.

Clone and build

git clone --recurse-submodules https://github.com/JavOrraca/duckboost.git
cd duckboost
make

If you already cloned without submodules:

git submodule update --init --recursive
make

make produces:

  • ./build/release/duckdb — CLI with duckboost statically linked
  • ./build/release/extension/duckboost/duckboost.duckdb_extension — loadable extension file

Optional: GEN=ninja make if Ninja is installed. make test runs the SQL tests under test/sql/.

Open the shell

./build/release/duckdb -unsigned
LOAD duckboost;

From a checkout, you can also load penguins offline with read_csv('data/penguins.csv', nullstr = 'NA') instead of the HTTPS URL.

To load the .duckdb_extension into a different DuckDB 2.0.0 shell (not this repo’s binary), build that shell from the same duckdb submodule commit:

LOAD '/path/to/duckboost/build/release/extension/duckboost/duckboost.duckdb_extension';

Next steps