Practical overview
When it fits
Use Naru when you need a Python codebase for experimenting with neural cardinality estimation on tables, including training, evaluation, and comparisons with database-estimation baselines.
Who it is for
- Database researchers evaluating learned cardinality estimators.
- Developers working with tabular data who want to train and assess neural estimates for query optimization.
Documented uses
- Train autoregressive models on tabular datasets to estimate cardinalities.
- Evaluate trained estimators on SQL queries and compare them with included baselines.
- Load, analyze, and represent tables with pandas-based utilities.
- Register a custom CSV dataset for use in training and evaluation.
Requirements & limits
The repository is public and licensed under Apache-2.0. Its documented setup uses Conda and the project's environment.yml.
- Naru provides training and evaluation scripts rather than a hosted interface.
- Its custom-data workflow requires a loader in datasets.py and edits to the training and evaluation scripts.
- The README recommends matching architecture flags between training and evaluation for checkpoint loading.
- The README notes that Transformers may fit more complex datasets but are more computationally expensive.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Train and evaluate a model on the tiny DMV dataset
Set up Naru, train a ResMADE on the documented 100-row dmv-tiny dataset, and evaluate its checkpoint.
Before you start
- Naru repository
- Conda
- Project environment.yml
Steps
Create the environment with
conda env create -f environment.yml.Activate the
naruenvironment using the documented activation command.Train a ResMADE with the command below.
python train_model.py --epochs=100 --residualEvaluate the checkpoint with the command below.
python eval_model.py --glob='dmv-tiny*.pt' --residual
Expected outcome
The training command creates a model checkpoint, which the evaluation command uses as a cardinality estimator.
Guide limitations
- The example is specifically for the tiny 100-row dataset.
- Evaluation should use the same architecture flags as training.
Register a custom CSV dataset for training and evaluation
Connect a CSV table to Naru’s training and evaluation scripts.
Before you start
- A CSV file
- The Naru repository and its Python dataset and training/evaluation scripts
- A loader function that reads the CSV into a pandas DataFrame and returns a CsvTable
Steps
Place the CSV file under
datasets/.Define a
LoadMyDataset()function indatasets.pythat reads the file with pandas and returns aCsvTable.Extend the training and evaluation scripts to recognize the new dataset, following their existing uses of
args.dataset.
Expected outcome
The custom table is connected to the dataset-loading path used by Naru’s training and evaluation scripts.
Guide limitations
- The README instructs users to ensure the loader reads the data correctly.
- The documented steps cover dataset registration, not training or evaluation commands for the new dataset.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 18 October 2026
- Original website title
- naru-project/naru · Official homepage title · retained in its source language