Concepts

How OndatraSQL works — the mental model

OndatraSQL runs your data pipeline.

You write SQL files. Run one command. Your data is materialized.

The Mental Model

Think of OndatraSQL as a program that runs your data.

• Files = models
• ondatrasql run = execution
• Output = tables in DuckLake

You don’t configure pipelines. You run them.

What Happens When You Run

ondatrasql run

OndatraSQL:

1. Finds all models
2. Builds a dependency graph
3. Detects what changed
4. Runs only what’s needed
5. Writes results to DuckLake

Done.

Example

raw.events → staging.sessions → mart.daily_traffic

You don’t define this graph. It’s extracted from your SQL.

The Runtime Model

Everything is built into one system:

• Dependency graph → automatic
• Change detection → automatic
• Incremental loading → automatic
• Schema evolution → automatic
• Validation → automatic

No config files. No orchestration layer.

Data Flow

1. Data is collected or loaded
2. Stored durably on disk
3. Loaded into DuckDB
4. Transformed via SQL
5. Written to DuckLake

If anything fails, nothing is lost.

Change Detection

Every model gets a run type:

You don’t write incremental logic. It’s built in.

Safety

• Constraints block bad data before it’s written
• Audits catch regressions after
• Failures roll back automatically via time-travel

Every run is reproducible.

What OndatraSQL Is Not

OndatraSQL runs on a single machine. It is not:

• A distributed system
• A streaming platform
• A cloud warehouse
• An orchestrator

You don’t orchestrate data pipelines. You run them.