Predict with RelFM

RelFM is a foundation model for relational data that predicts in-context from the labeled rows you provide. It requires a Graph, a PropertyTransformer, and a labeled context split, but no training step: there’s no fit(), load(), or register_model() call. You can predict directly without managing a training, checkpointing, or model-registration lifecycle.

RelFM’s workflow

RelFM has a single workflow:

• Construct it with context — the labeled rows used directly as in-context examples.
• Call .predictions(domain=...) directly. There’s no separate training step to call first.
• Optionally provide validation if you want to call .score().

RelFM supports:

• "binary_classification", "multiclass_classification", and "regression".
• It currently does not support link prediction or multilabel classification.

Graph requirements:

The Graph passed to RelFM cannot contain a self-referential foreign key—a concept whose foreign key points back to itself. RelFM’s feature generation walks the foreign-key graph depth-first, and self-referential foreign keys are currently unsupported because the walk has no base case for revisiting a table. This restriction is expected to be lifted in an upcoming release.

Construct and predict

Given the same Train/Validation/Test splits and Graph/PropertyTransformer setup as in Solve a classification problem:

from relationalai.semantics.reasoners.predictive import RelFM

relfm = RelFM(
    database="MYDB", schema="MYSCHEMA",
    graph=graph, property_transformer=pt,
    source_concept=Students,
    context=Train, validation=Validation,
    task_type="binary_classification",
    eval_metric="roc_auc",
)

Students.predictions = relfm.predictions(domain=Test)

database/schema are where predictions get materialized in Snowflake. The prediction relationship exposes .probs/.predicted_labels for classification, or .predicted_value for regression (or one column per quantile_levels when regression_output="distribution"). See Make predictions for how to query it.

Set constructor parameters

Temporal splits

Parameter	Description	Default
has_time_column	Set to True when context/validation/domain use the at keyword for temporal splits. See Define a learning task for the full explanation.	False
use_current_time	Whether the prediction date’s own data is included (<=) or excluded (<).	True

Job control

Parameter	Description	Default
test_batch_size	Batch size used during inference.	256
stream_logs	Stream job logs to stdout.	True
dataset_alias	A user-chosen alias for the dataset, used to name the tables RelFM exports to database/schema. When omitted, it’s built from your Snowflake user and role. RelFM doesn’t create an experiment.	None
parallel_reasoners_init	Initialize the Predictive and Logic reasoners in parallel.	True
random_state	Seed for ensemble generation and context sampling.	42

Tune in-context prediction

Parameter	Description	Default
n_estimators	Ensemble size. Higher improves quality at the cost of slower inference.	8
sample_size	Max rows of context sampled as in-context examples. None uses all rows.	None
sampling_strategy	How to draw the context sample: "stratified", "most_recent", "mixed", "random", or "balanced".	"stratified"
dfs_max_depth	The maximum number of hops across related tables, following the Graph’s foreign keys, to include when generating features. Values range from 1 to 3.	2
device	"cpu" or "cuda".	"cpu"
norm_methods	Feature normalization applied before inference: "none", "power" (Yeo-Johnson), "quantile", "quantile_rtdl", or "robust". Pass a list to use different methods across ensemble members. None uses ["none", "power"].	None
clamp_min	Regression only. Lower bound on predictions (as a percentile).	0
clamp_max	Regression only. Upper bound on predictions (as a percentile).	100
regression_output	Regression only. "point" returns a single estimate; "distribution" also returns the quantiles in quantile_levels.	"point"
quantile_levels	Regression only. Quantile levels to output when regression_output="distribution".	None (uses [0.1, 0.5, 0.9])

Score and inspect the dataset

.score(domain=...) evaluates RelFM against a labeled split — pass one explicitly, or omit domain to score against the validation split from the constructor. It computes every metric available for the task type, not just the configured eval_metric.

To inspect the schema RelFM derived from your Graph (tables, columns, and foreign keys after feature preparation), call .display_dataset_diagram() in a notebook, or .save_dataset_diagram(path) to write it to a file. Both require the Graphviz dot command-line tool and only work after predictions() or score() has run at least once.

relfm.predictions(domain=Test)
relfm.display_dataset_diagram(show_dtypes=True)