Skip to main content
ByPrior Labs
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 moment t. The model sees the database truncated at t, and the label comes from the window after it.
That is what makes it a forecast rather than a lookup, and the harness enforces it — you cannot accidentally show the model a review written after 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 its relarena-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 secret TABPFN_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:
Read it from the right: a seller has many order items; each belongs to an order, which belongs to a customer and may have a review, and points at a product with a category. Those chains are the paths DFS aggregates along.

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 is columns, 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 a PredictiveQuery. 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. A PredictiveContext holds the database and training task. The calls below load each split and display its labels. Inspect these labels before running featurization.
Two things to notice: 11k training rows out of only ~3k sellers, because each seller recurs at many anchor times; and a churn rate around a quarter to a third, which is a healthy balance to model. A label that came out 99% one class would need a different approach. The integer 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 local cache_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 of tabpfn-rel using 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.
The second fit reuses the features from the first fit, so its runtime is mostly model fitting. Caching also works for 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-global predicts the global churn rate observed during training.
  • constant-per-entity uses 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.
All three models score the sellers selected by the same prediction query. The outer join below requires predictions to match the test labels exactly, including both seller IDs and timestamps.
We observe that TabPFN-Rel improves significantly over the baseline.

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 a columns 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. Let your coding agent do it. Install the TabPFN-Rel agent skill in Claude Code or Codex, point the agent at your tables and ask your question. It prepares the data, writes both YAML files and compares TabPFN-Rel with baselines.