Skip to content
stanford-starPublic

Repository files navigation

PluRel

Synthetic Data unlocks Scaling Laws for Relational Foundation Models

Project Page arXiv Model: rt-plurel Dataset: plurel PyPI License: Apache-2.0

Scaling Law Plot

Models pretrained on PluRel data lead public relational benchmarks (at the time of submission):
🥇 RT-PluRel, a Relational Transformer pretrained on PluRel synthetic data, is #1 on the combined system + model leaderboard on RelArena-α (repro).
🥇 RT-J, warm-started from RT-PluRel, is the #1 in-context model on the RelBench leaderboard (repro).

Latest Updates

  • [11/2026] 🚧 PluRel v2 is under active development toward a v2-alpha release.
  • [10/2026] 🥇 RT-PluRel takes the top spot on RelArena-α. Checkpoints are on Hugging Face.
  • [07/2026] Released v1.1.0 on PyPI with the latest features and performance improvements.
  • [04/2026] PluRel is accepted to ICML 2026!

Overview

PluRel generates synthetic relational databases from structural causal models. Each table is a small causal graph, and foreign keys pass causal effects from one table to another. A random prior can draw thousands of different databases in the relbench format. The PluRel paper pretrains models on these databases.

You can also write your own tables and databases, start from real rows, and draw as many datasets from them as you need.

PluRel

Note

Pretraining models on PluRel data (preprocessing, checkpoints, inference with Relational Transformer) is covered in examples/relational_transformer/.

Installation

PluRel needs Python 3.12 or newer.

Important

PluRel v2 is under active development toward a v2-alpha release. It is not on PyPI yet, and its API may still change. Install it from main, or pin a commit to reproduce a run. pip install plurel gives version 1.1.0, which has the earlier API.

pip install "git+https://github.com/stanford-star/plurel.git"

Quickstart

Generate a random database, as the paper does. The seed picks the database's tables, keys and causal mechanisms. prior.rows picks how many rows each table gets:

from plurel import SchemaPrior, create_database, split_timestamps, write_database

prior = SchemaPrior()
database = prior.realize(seed=0)                              # tables, keys and mechanisms
frames = database.sample(prior.rows(database, seed=0), seed=0)  # a dict of DataFrames
db = create_database(database, frames)                        # the relbench form
write_database(db, "~/.cache/relbench/quickstart", name="quickstart", overwrite=True,
               **dict(zip(("val_timestamp", "test_timestamp"), split_timestamps(db))))

To generate many databases in parallel, run the script below. Each database is saved to ~/.cache/relbench/plurel-<seed>:

python scripts/synthetic_gen.py --seed_offset 0 --num_dbs 1000 --num_proc 16

You can also write a table yourself. Each column says what it holds and what causes it:

from plurel import Categorical, LogNormal, Numeric, PrimaryKey, Table, Uniform

customers = Table({
    "id": PrimaryKey(),
    "age": Numeric(Uniform(18, 80), round=1),
    "segment": Categorical({"bronze": 0.6, "silver": 0.3, "gold": 0.1}, causes={"age": 1.0}),
    "spend": Numeric(LogNormal(3, 0.5), causes={"age": 0.8, "segment": {"gold": 1.5}}),
})
print(customers.explain())
frame = customers.sample(500, seed=0)

And you can write a whole database and save it for relbench:

from plurel import ForeignKey, Numeric, PrimaryKey, Schema, Summary, Table, Uniform, create_database, write_database

schema = Schema({
    "teams": Table({"id": PrimaryKey(), "size": Numeric(causes={Summary("staff", "team_id"): 1.0}, noise=0)}),
    "staff": Table({"id": PrimaryKey(), "team_id": ForeignKey("teams"), "pay": Numeric(Uniform(40, 120))}),
})
frames = schema.sample({"teams": 5, "staff": 60}, seed=0)
write_database(create_database(schema, frames), "~/.cache/relbench/teams", name="teams", overwrite=True)

See examples/ for more. It has short concept scripts that each explain one idea, and domain recipes for retail orders, clinic visits and student enrollments.

Build a table

A Table is a dict of columns:

Column Holds
PrimaryKey() Row positions, or the given values
Numeric(marginal, causes, noise, missing, clip, round, zeros) Numbers following marginal, any distribution such as Normal(50, 10), Uniform(18, 80), LogNormal(3, 0.5) or Poisson(4)
Categorical(levels, causes, noise, missing, ordered, scores) String levels, as a sequence of equally common levels or a dict of level to share
Timestamp(start, end, causes, noise, missing) Times between start and end. Without them, the sum of the causes, in epoch seconds
Hidden(causes, noise) A cause that other columns read but no column records
Derived(function) A number computed from other columns, which the function's parameters name

causes maps each cause to its effect on the column:

Cause and effect Means
"age": 0.8 A weight. Higher age means a higher value here, and a negative weight means a lower one
"age": (0.8, "tanh") A weight and a transform: tanh, square, step, relu, abs, sin, exp, log or any function
"segment": {"gold": 1.5} An effect per level of a categorical cause
("age", "tenure"): 0.8 A weight on the product of two causes
Recorded("price"): 2.0 A weight on what price records, in its units

Each column adds up the effects of its causes, plus some noise (0.5 by default).

  • With a marginal, the rows are then sorted by that sum and given the marginal's values in that order. So the column follows its marginal exactly.
  • A Numeric without a marginal records the sum itself.

Either way, a weight says how closely a column follows its causes. It does not say how many units the column moves. With one cause and the default noise, weights of 0.25, 0.5, 1 and 2 give rank correlations of about 0.4, 0.7, 0.9 and 0.97. To work in real units, read a cause with Recorded, or use Derived. 02_latent_and_recorded.py shows both.

sample_with_latents(rows, seed=...) also returns the hidden values behind every column. With held={"x": values} it fixes the hidden values of x. This is an intervention, and the columns that read x change to match.

More options for a column:

  • round=1 gives whole numbers, and round=0.01 gives cents.
  • clip=(lo, hi) keeps values between lo and hi.
  • zeros=0.2 sets 20% of rows to 0.
  • missing=0.1 blanks 10% of rows. Columns that read a blanked column still see its value.

11_missing_and_unmatched.py covers blanks and fills.

Link tables into a database

A ForeignKey points at a row of another table. A cause written as "key.column" reads a column of that row. time_column names the column that orders a table's events. A table with a key into a table of events must have its own time_column. That way, no key points at a row that a cut in time removes:

from plurel import Categorical, ForeignKey, LogNormal, Numeric, PrimaryKey, Schema, Table, Timestamp, Uniform

customers = Table({
    "id": PrimaryKey(),
    "segment": Categorical({"bronze": 0.6, "silver": 0.3, "gold": 0.1}),
    "spend": Numeric(LogNormal(3, 0.5), causes={"segment": {"gold": 1.5}}),
})
orders = Table(
    {
        "id": PrimaryKey(),
        "customer_id": ForeignKey("customers"),
        "time": Timestamp("2020-01-01", "2024-01-01"),
        "amount": Numeric(LogNormal(), causes={"customer_id.spend": 1.0}),
    },
    time_column="time",
)
schema = Schema({"customers": customers, "orders": orders})
frames = schema.sample({"customers": 500, "orders": 5000}, seed=0)

By default, each row picks its parent at random. A key's options change that:

Option Says
link How rows pick parents: RandomLink(), HSBMLink(popularity=Pareto(2.5)) for a few popular parents, or TreeLink(roots=0.05) for a hierarchy within one table
match={"region": "region"} Child and parent columns that must agree
prefer={Recorded("beds"): 0.05} Parents with more beds are picked more often
counts=Counts(4.0, causes=..., least=1, most=8) How many rows point at each parent, which sets the child table's size
unique=True or unique="student_id" No parent repeated, across the table or per group
unmatched="null" A row with no parent left gets an empty key, instead of an error
nullable=0.02, fill=0.0 2% of rows get an empty key at random. Columns reading through an empty key see fill

Summary("staff", "team_id") reads the rows that point back at a row. It gives their count, or, with a column, their sum, mean, max or min. Every summary except a count or a sum needs a fill for rows that nothing points at. A summary of a Recorded column skips blanks.

When a key has counts, its table needs no row count of its own:

from plurel import Counts

school = Schema({
    "students": Table({"id": PrimaryKey(), "year": Numeric(Uniform(1, 4), round=1)}),
    "courses": Table({"id": PrimaryKey(), "level": Categorical(("intro", "advanced"))}),
    "enrollments": Table({
        "student_id": ForeignKey("students", counts=Counts(3.0, causes={"year": 0.5}, most=5)),
        "level": Categorical(("intro", "advanced"), causes={"student_id.year": 1.0}),
        "course_id": ForeignKey("courses", match={"level": "level"}, unique="student_id", unmatched="null", fill=0.0),
    }),
})
frames = school.sample({"students": 200, "courses": 30}, seed=0)

10_relational_schema.py and 15_edge_cases.py show which options work together, and how counts and summaries behave at the edges. 12_temporal_data.py covers the order of events.

Start from real rows

Table.from_frame keeps the rows of a real table exactly. extra adds generated columns to it. Generated tables can point at its real keys and read its columns:

import pandas as pd

real = pd.DataFrame({"customer_id": ["C1", "C2", "C3", "C4"], "age": [34, 51, 29, 62]})
people = Table.from_frame(
    real,
    primary_key="customer_id",
    extra={"churned": Categorical({"no": 0.8, "yes": 0.2}, causes={"age": -1.0})},
    target="churned",
)
purchases = Table({"id": PrimaryKey(), "customer_id": ForeignKey("people"), "amount": Numeric(LogNormal())})
frames = Schema({"people": people, "purchases": purchases}).sample({"purchases": 200}, seed=0)
assert frames["people"][["customer_id", "age"]].equals(real)

This adds to the real rows. It does not learn to draw new rows like them. See 08_semi_synthetic_table.py and 09_semi_synthetic_relations.py.

Author many tables from one description

Any weight, effect, noise or marginal can be a range. The table then describes a family of tables, and generating data takes two steps, each with its own seed:

  1. realize(seed) picks one table from the family. It draws a value for every range, then fits the categorical columns to a trial draw. This seed is the mechanism seed.
  2. sample(rows, seed=...) draws a dataset from that table. This seed is the data seed. Sampling never changes the table.
from plurel import MEDIUM, STRONG, Range, Scaled

family = Table({
    "wait_days": Numeric(Scaled("duration", 0, 60), round=1),
    "outcome": Categorical({"declined": 0.7, "accepted": 0.3}, causes={"wait_days": -STRONG}),
    "cost": Numeric(Scaled("amount", 0, 5000), causes={"wait_days": Range(0.2, 1.0)}, noise=MEDIUM),
})
generator = family.realize(seed=1)                  # one mechanism
first, second = generator.sample(1000, seed=10), generator.sample(1000, seed=11)
others = [family.realize(seed).sample(1000, seed=10) for seed in range(3)]  # three mechanisms
Drawable Draws
Range(low, high), WEAK, STRONG, LOW, MEDIUM, HIGH A number for a weight or a noise level. WEAK and STRONG are weights, and LOW, MEDIUM and HIGH are noise levels
Scaled(units, low, high, shape=None) A marginal on the range, shaped for count, amount, duration, ratio, score, percent or signed values
Shares(levels) A categorical column's shares
Noise(kind, std) Noise: gaussian, laplace, student_t, skewed or gumbel
ByLevel(column, {level: (low, high)}) A marginal with its own range per level of a categorical column

Schema.realize does the same for a database. A table with no ranges and no categorical scores can be sampled directly. A table with scores must be realized first, to fit them. 03_realization.py through 07_calibration_sizes.py explain what realizing does and when it matters.

Random tables and databases

TablePrior and SchemaPrior draw whole tables and databases at random. Every setting is a Range or a Choices, and their docstrings list them all. By default, a database has 2 to 20 tables. Tables that others point at have 500 to 1,000 rows, and event tables have 10,000 to 30,000:

from plurel import IntegersRange, LogIntegersRange, SchemaPrior, TablePrior

table = TablePrior(column_count=IntegersRange(8, 8)).realize(seed=0, time=True)
frame = table.sample(1000, seed=0)

prior = SchemaPrior(table_count=IntegersRange(3, 5), entity_row_count=LogIntegersRange(1000, 2000))
database = prior.realize(seed=0)
frames = database.sample(prior.rows(database, seed=0), seed=0)

Each drawn table has its own causal mechanism. The figure shows eight tables from TablePrior. For each one, two numeric values that feed into a categorical column vary over a grid, and the table's other inputs stay at typical values. Each cell shows the class the column takes most often there. The figure comes from decision_boundaries.py:

Decision boundaries of eight tables drawn by TablePrior

Every generated database keeps its keys valid when cut at any point in time. examples/analysis/ and examples/reference/ measure how diverse the prior's databases are, how hard their columns are to predict, and how one compares with a real database.

Save and inspect

  • create_database puts the frames in relbench form. It sorts event tables by time and turns keys into row positions.
  • write_database saves the database, and read_database loads it back. A database with events needs split timestamps, which split_timestamps(db) gives. A database without events needs none.
  • describe() gives a table or schema as plain data, ready for JSON, including every drawn weight and fitted cut. explain() gives the same as readable text.
from plurel import create_database, read_database, split_timestamps, write_database

db = create_database(schema, schema.sample({"customers": 500, "orders": 5000}, seed=0))
val, test = split_timestamps(db)
path = write_database(db, "~/.cache/relbench/shop", name="shop", val_timestamp=val, test_timestamp=test, overwrite=True)
loaded = read_database(path)
print(schema.explain())

13_static_export.py shows a database without events.

Reproducibility

The same seeds and row counts give the same frames, byte for byte, on the same platform and type of processor. On a different platform or processor, the last digits of some numbers can differ. COMPATIBILITY.md says exactly what repeats, and CHANGELOG.md lists the changes that alter draws.

Each draw is one whole dataset, so sample(200, seed=0).head(100) is not the same as sample(100, seed=0). To build a larger dataset, draw several parts, each with its own seed (04_sampling.py).

Latency and memory

Making one random database from the default prior takes about a third of a second and a few hundred megabytes of memory. That covers drawing it, sampling its rows, saving them to parquet and reading them back. So a corpus of thousands of databases fits on a laptop. The numbers below come from 100 tables and 100 databases, measured with plurel at commit 287fef8 on an Apple M4 and on GitHub's ubuntu-latest runner:

Median 90th percentile Largest
database: rows 29,054 102,220 211,318
database: seconds, M4 / Linux 0.29 / 0.44 0.98 / 1.4 4.1 / 4.4
database: peak memory, M4 / Linux 264 / 290 MiB 422 / 393 MiB 776 / 702 MiB
table: seconds, M4 / Linux 0.13 / 0.14 0.31 / 0.35 0.59 / 0.64

benchmarks/ has the harness and the full reports.

Development

Set up the environment with pixi:

pixi install
pixi run pre-commit install
pixi run test        # the suite
pixi run lint        # ruff check and format check
pixi run typecheck   # pyright over the public API
pixi run examples    # every README block, and each quickstart on its own
pixi run recipes     # every script in examples/, small, each in its own process
pixi run bench       # generation time and memory, see benchmarks/README.md
pixi run fingerprints  # rewrite test/fingerprints.json, for a change that moves draws on purpose

CI runs these on every pull request to main and v2, on Linux and macOS. The v1 generator, the paper-exact code, remains at the v1.1.0 and v1.0.0 tags.

Citation

If you find this work useful, please cite our paper:

@inproceedings{kothapalli2026plurel,
    title={{PluRel:} Synthetic Data unlocks Scaling Laws for Relational Foundation Models},
    author={Vignesh Kothapalli and Rishabh Ranjan and Valter Hudovernik and Vijay Prakash Dwivedi and Johannes Hoffart and Carlos Guestrin and Jure Leskovec},
    booktitle={Forty-third International Conference on Machine Learning},
    year={2026}
}

Releases

Packages

Contributors

Languages