# PQL — Predictive SQL for DuckDB

> PQL is an open-source DuckDB extension that adds TRAIN MODEL and PREDICT to SQL. It trains on the tables you already have and builds features from your foreign keys. No export, no pipeline, no second system. MIT licensed.

Source: https://guepard.run/pql

---

PQL · Predictive SQL [32,560 downloads](https://duckdb.org/community_extensions/extensions/pql)

# One line of SQL. A real prediction model.

**PQL adds TRAIN MODEL and PREDICT to DuckDB.** Your agents answer “what happens next?” in the SQL they already speak. No pipeline, no export, no second system.

`INSTALL pql FROM community; LOAD pql;`

[View on GitHub →](https://github.com/Guepard-Corp/duckdb-pql) [DuckDB community extension](https://duckdb.org/community_extensions/extensions/pql)

- Open source, MIT licensed

- Runs inside DuckDB, in-process

- Trains in seconds on a laptop CPU

```
TRAIN MODEL lapse
  PREDICT EXISTS(transactions)
  FOR customers AT last_seen_at
  HORIZON 30 DAYS;

-- seconds later: score, baseline

PREDICT EXISTS(transactions)
  FOR customers USING MODEL lapse;
```

What it is

## The usual path moves your data. PQL moves the model.

Today: the data leaves

- 8 steps

- 3 tools

- 2 teams

- weeks

**Your database** tables, keys, history

**Export** a copy leaves

**Feature pipeline** hand-written

**Training stack** Python, GPU

**Serving layer** must stay in sync

With PQL: the model comes to the data

- 1 statement

- seconds

**Your database** DuckDB, with the PQL extension loaded nothing is exported, nothing is copied

**your tables** as they are

**TRAIN MODEL** features built from the keys

**PREDICT** one row per entity

Who it is for

## Built for everyone already in the database. Humans and agents.

If you own the database

### The database developer

One SQL statement, same tables, same permissions. Nothing to deploy.

If you build the models

### The data scientist

A first defensible model in seconds, not weeks. Leakage handled by construction.

If you are an agent

### The AI agent

Trains, scores and predicts on its own, in the SQL it already writes. No Python and no training stack to hand it.

Where it applies

## An entity, its events, and a question about its future.

SaaS renewals, e-commerce reorders, missed payments, support tickets: the shape is always the same.

### Restaurants and hospitality

#### Which regulars are about to stop coming?

```
TRAIN MODEL lapse
  PREDICT EXISTS(transactions)
  FOR customers AT last_seen_at
  HORIZON 30 DAYS;
```

### Tracking, logistics and fleet

#### Will this shipment hit an exception in the next three days?

```
TRAIN MODEL risk
  PREDICT EXISTS(scan_events
  WHERE scan_events.type = 'exception')
  FOR shipments AT dispatched_at
  HORIZON 3 DAYS;
```

[More examples in the tutorial](https://github.com/Guepard-Corp/duckdb-pql/blob/main/docs/tutorial.md)

Leakage, handled by construction

## Why a forecast cannot cheat.

PQL splits time at each row's AT value. Features come only from before it, and the engine counts the label after it.

**everything the model may look at** history from every related table

anchor: this row's AT time

**what it is asked to predict** the HORIZON window

later rows, never seen

time

Proof on RelBench

## The same accuracy class, from one statement.

RelBench is the Stanford benchmark for relational prediction.

rel-f1 task | PQL | Gradient boosting Boosting hand-built features | Graph neural net GNN RelBench RDL, GPU |

Qualify top-3 next month? AUROC | 0.809 | 0.842 | 0.809 |

Fail to finish a race? AUROC | 0.707 | 0.701 | 0.741 |

Finishing position? MAE, lower is better | 4.123 | 4.403 | 4.259 |

Hardware, training time | Laptop CPU
3 to 15 s | Laptop CPU
about 1 s | NVIDIA L4 GPU
17 to 78 s |

One win, one tie, one loss against each, without moving a row.

Written by hand

**PQL**

1 statement

**Gradient boosting**

126 lines of feature SQL

**Graph neural net**

~120 lines of model code

## Try it in two minutes.

Load the extension in any DuckDB shell and train your first model on the tables you already have.

`INSTALL pql FROM community; LOAD pql;`

[View on GitHub →](https://github.com/Guepard-Corp/duckdb-pql) [DuckDB community extension](https://duckdb.org/community_extensions/extensions/pql) [Read the tutorial](https://github.com/Guepard-Corp/duckdb-pql/blob/main/docs/tutorial.md)

[32,560 downloads](https://duckdb.org/community_extensions/extensions/pql)

## Frequently Asked Questions

PQL (Predictive SQL) is an open-source DuckDB extension that adds TRAIN MODEL and PREDICT to SQL. It trains a model on the tables you already have, builds features from your foreign keys, and returns predictions as rows, like any query.

TRAIN reports a score on rows the model never saw, next to a baseline: the answer you would get with no model at all. If the model does not beat the baseline, you see it immediately.

Single-series and seasonal forecasting, such as total daily revenue for one branch. A dedicated time-series model does better there. PQL is built for questions about many entities with related, timestamped events.

Not today, by design. Models live for the session. TRAIN and PREDICT run in the same job, in seconds, so every prediction is on fresh data. Persistence is on the roadmap for cases that need a frozen model.

Yes. PQL is MIT licensed and developed in the open at github.com/Guepard-Corp/duckdb-pql.
