In this example, we walk through an example relational learning task with TabPFN-Rel, released alongside RelArena-⍺. Read our full report “Advancing Open and Reproducible Relational Learning: RelArena-α, TabPFN-Rel and RPI” here, and check out the relarena repo here
Most real data does not live in one table. A shop has sellers, customers,
orders, order items, products, and reviews, wired together by foreign keys —
and the interesting questions run across those tables and forward in time:
which of the sellers active today will stop selling in the next 30 days?
Nothing in that database answers it directly. There is no churn column, and no
feature matrix. Supervised learning needs both, and normally that means weeks of
bespoke joins and window aggregations.
TabPFN-Rel lets you declare them instead. You write two small YAML files — one
describing your tables, one asking your question as a SQL query — and the harness
builds the labels, aggregates each entity’s history across the foreign-key graph
with Deep Feature Synthesis (DFS), keeps the future out of the features, and runs
TabPFN on the result.
This cookbook does that end to end on the raw Olist Brazilian
E-Commerce CSVs, in a
few minutes on CPU.
📃 Read the full report on RelArena, TabPFN-Rel and RPI here
The shape of the problem
One idea does most of the work here: the anchor time. A prediction is always made as of some momentt. The model sees the database truncated at t, and the
label comes from the window after it.
t.
Two consequences worth holding onto. First, there are many anchors: the same
question is asked at 30-day intervals stepping back through history, so one seller
contributes many training rows. Second, the splits are cuts in time, not random
samples — you pick the two dates where train ends and test begins.
RelArena follows the RelBench protocol for final prediction. We explicitly select
test_timestamp in a prediction query. The feature database remains frozen at
that cutoff. A later query timestamp emits a warning and does not expose database
rows written after test_timestamp.
Setup
TabPFN-Rel is available as a standalone package on PyPI. It includes the Relational Predictive Interface (RPI) through itsrelarena-core dependency;
the relarena benchmark package is only needed for the baseline comparison below.
Use Python 3.11 or 3.12.
The api extra runs featurization locally and uses the hosted TabPFN API for
model fitting and prediction. No local GPU is needed.
The TabPFN token
Because the fit runs on the hosted API, you need a Prior Labs token. Grab one from platform.priorlabs.ai and add it as the Colab secretTABPFN_TOKEN (You can add a secret via the key icon on the right sidebar). Locally you can skip this — tabpfn-client opens a browser on the
first fit and caches the token.
This cell runs before every other import because tabpfn-client reads the token
once, at import time.
The database
Olist is a real Brazilian marketplace; the public dataset covers roughly 100k orders from 2016–2018 and downloads anonymously, no Kaggle account needed. Seven of its CSVs matter here, and the foreign keys between them are what TabPFN-Rel walks:Giving order_items a real event time
Event tables need a trustworthy timestamp, because that is the column the harness
censors on. orders and order_reviews have one; order_items only has a shipping
deadline. The cell below joins each item’s purchase time on from its order.
This is the only table that needs any code — everything else is read straight from
the raw CSVs.
The Database Schema
Now the first YAML: where each table lives, what its key is, which column carries its event time, and which foreign keys point where. That is the graph DFS will walk. The one judgement call iscolumns, an allow-list of the fields that become
features. orders carries delivery dates and a status that are only filled in
after the purchase — keeping them would hand the model facts that do not exist at
prediction time, so they are left out. Time censoring is automatic; deciding which
columns were backfilled is on you.
The Task File
The second YAML is the question. It names the entity you predict over, the target, the 30-day window, and the two dates that cut train from validation from test — then computes the label in SQL. Prediction entities and the anchor time are supplied separately in aPredictiveQuery. The feature database remains frozen at
test_timestamp, even when a query requests a later anchor.
That query is the heart of it, and it reads as two windows around each anchor time:
the WHERE EXISTS at the bottom looks backwards to keep only sellers who were
active in the previous 30 days, and the NOT EXISTS at the top looks forwards
and fires when no order arrives in the next 30. Churn only means something for
sellers who had started, which is why both are needed.
The rules for writing your own — which columns to emit, what timestamp_df is, how
{timedelta} gets substituted — are in the predictive-task
guide.
Check the labels before spending compute
Loading the spec validates both files. APredictiveContext holds the database
and training task. The calls below load each split and display its labels.
Inspect these labels before running featurization.
seller_id is internal — RelArena reindexes keys, and predict maps
them back.
Fit and predict
TabPFNRel(model="client") uses hosted TabPFN 3.5 inference. Its fit() method accepts a
training context, and predict() accepts a query with explicit entities and a
timestamp. Use model="local" with the local package extra for local inference.
"client" and "local" always select the latest recipe. To pin a recipe, pass
its dated selector, such as model="client-2026-09-28". The current recipes run
one validated configuration, so n_trials=0 is all they need.
For this historical evaluation, select sellers with observed test-window labels.
Only their IDs enter the prediction query; their outcomes are used for evaluation.
The feature database is frozen at test_timestamp, so rows from the forward
30-day label window are not visible to the model.
Featurization runs locally. The optional caching example below reuses these
features across fits and predictions.
Optional: Caching to reuse relational features
Depending on the strength of your CPU, TabPFN-Rel can spend a significant part of its runtime constructing relational features with deep feature synthesis (DFS), rather than running the model. Pass a localcache_dir to fit() to persist those features. Missing entries
are computed and stored as the query runs; later identical operations reuse
them. Nothing in the cache is uploaded.
This can be helpful in many scenarios, like:
- You might want to refit on the same database later, for example after a runtime restart with the cache on a mounted drive. The refit reuses the stored features.
- If you use the local version of
tabpfn-rel, then you might want to run the cache pre-computation on a beefy CPU node for large datasets, while running the actual predictions oftabpfn-relusing a good GPU.
data_version identifies the exact database snapshot behind the cache keys.
Keep it stable while the CSV contents are unchanged, and bump it whenever the
row content changes. In Colab, ./relarena-cache lasts for the current runtime.
To retain it across runtime restarts, use a directory on a mounted Google Drive.
For more details, see the
predictive-interface caching documentation.
The caching API is optional and experimental.
First, configure the cache and fit the model. fit() computes and stores the
relational features it needs for training.
predict(), as you can see in the cell below:
Note: The speed-up is only calculated correctly the first time you run this cell. Delete/Rename/Change the cache directory in the cell above to rerun the measurements.
Does it beat simple baselines?
The Olist database contains the complete 30-day label window after its historical test timestamp,2018-06-15. We can therefore materialize the
held-out churn outcomes and compare the existing TabPFN-Rel predictions with
two learning-free baselines on the same sellers.
constant-globalpredicts the global churn rate observed during training.constant-per-entityuses each seller’s own history when available and falls back to the global rate otherwise.
preds, the prediction query, and the training context already exist from
the previous section.
The two baselines are supplied by relarena. The next cell installs that
package and calls discover_models() to register its models in this running
notebook. The earlier TabPFN-Rel sections do not require it.
Where to go next
Your own database. None of this is Olist-specific — a schema file and one label query is the whole setup. The two things to get right are a real event-time column on every event table, and acolumns allow-list that excludes anything backfilled
after the fact.
If a fit hangs, the fan-out is too wide: DFS cost grows with how many
tables an entity links out to. Prune the schema or use a lower featurization depth.
Regression works identically — set task_type: regression and return a numeric
target (“how much will this seller sell”) instead of a 0/1 one.
- RelArena predictive-task guide — label queries, split timestamps, leakage
- The Olist example in the TabPFN-Rel repo — the same task as a plain script
- TabPFN and tabpfn-client