ReDeLEx

ReDeLEx (Relational Deep Learning Exploration) is a Python framework for the development and evaluation of Relational Deep Learning (RDL) models. It enables end-to-end experimentation with graph-based neural networks on relational databases (RDBs), building on the CTU Relational Learning Repository and fully integrating with the RelBench interface.

It provides tools to transform SQL databases into heterogeneous graph representations suitable for Graph Neural Networks (GNNs), supports both static and temporal tasks, and enables a structured comparison across classical and deep learning models.

• ✅ Supports direct SQL database connectivity (local or remote RDBMS)
• 🔗 Transforms relational schemas into heterogeneous graphs
• 🧩 Automates attribute type inference and encoding (categorical, numerical, text, time)
• 📦 Provides access to 70+ relational datasets from the CTU Repository
• 🧪 Supports benchmarking tasks including binary/multiclass classification, temporal tasks, and pretraining
• 🧠 Compatible with diverse neural architectures (e.g., GraphSAGE, Transformer-based models)
• 📊 Evaluates classical ML models (e.g., LightGBM, Propositionalization) alongside RDL models

Install ReDeLEx via pip:

pip install redelex

If you're using RelBench, the CTU datasets are automatically supported.

Using RelBench interface:

from relbench.datasets import get_dataset
import redelex

dataset = get_dataset('ctu-seznam')
db = dataset.get_db()

Using ReDeLEx directly:

from redelex import datasets as ctu_datasets

dataset = ctu_datasets.Seznam()
db = dataset.get_db()

from redelex.datasets import DBDataset

custom_dataset = DBDataset(
    dialect="mariadb",  # e.g. postgresql, sqlite, mysql
    driver="mysqlconnector",
    user="your_user",
    password="your_password",
    host="your_host",
    port=3306,
    database="your_database"
)

db = custom_dataset.get_db(upto_test_timestamp=False)

Note: For full examples of task and schema configuration, see examples in ctu_datasets.py.

ReDeLEx supports:

• Node-level prediction (static or temporal)
• Link prediction
• Pretraining tasks via value masking
• Database modification for complex task generation

Each task is backed by a training table and optionally a temporal schema.

RDL models in ReDeLEx are modular and consist of:

1. Attribute encoders for tabular data
2. Tabular models (optional, e.g. ResNet)
3. Graph Neural Network layers
4. Task-specific heads (e.g. MLP classifiers)

Supported model examples include:

• Linear SAGE
• Tabular ResNet + GraphSAGE
• DBFormer (Transformer-based)

ReDeLEx includes tools for:

• Selecting RDL-suitable datasets based on structure and size
• Comparing RDL with traditional ML and propositionalization
• Benchmarking across 70+ relational datasets from various domains

For experimental results and performance benchmarks, see the ECML PKDD 2025 paper.

• macOS & Linux

wget -qO- https://astral.sh/uv/install.sh | sh

• Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

More info: https://docs.astral.sh/uv/getting-started/installation/

Requires Python 3.12. Each command installs everything, including the compiled PyTorch Geometric extensions (pyg-lib, torch-scatter, torch-sparse).

CPU (torch 2.9.1):

uv sync

CUDA 12.8 (torch 2.9.1):

uv sync --no-group cpu --group cu128

CUDA 12.4 (old CUDA env, torch 2.4.1):

uv sync --no-group cpu --group cu124

The CUDA groups are Linux/Windows only, because the PyTorch Geometric extensions are not built for macOS against a CUDA torch; on macOS use the CPU group.

uv run pytest

Tests that download every CTU database and build every task are excluded by default; run them explicitly with:

uv run pytest -m needs_network

Restrict them to a few databases with REDELEX_SMOKE_DATASETS:

REDELEX_SMOKE_DATASETS=ctu-financial,ctu-seznam uv run pytest -m needs_network

Every pull request and every push to develop runs the offline tests, the linter and a packaging check. The smoke tests are not automatic - trigger them from the CTU smoke tests workflow in the Actions tab, which takes the same comma-separated list of databases.

uv run pre-commit install
uv run pre-commit run

Visualizations run on Graphviz, which needs to be available on your system.

• Install Graphviz https://graphviz.org/download/

If you use ReDeLEx in your work, please cite:

@misc{peleska2025redelex,
  title={REDELEX: A Framework for Relational Deep Learning Exploration},
  author={Jakub Peleška and Gustav Šír},
  year={2025},
  eprint={2506.22199},
  archivePrefix={arXiv},
  primaryClass={cs.LG},
  url={https://arxiv.org/abs/2506.22199},
}

This project has received funding from the European Union’s Horizon Europe program under the grant agreement TUPLES No. 101070149, and the Czech Science Foundation grant No. 24-11664S.