Architecture

ObeliskDB separates two concerns that most systems conflate: the reasoning an agent does and the truth a platform guarantees. The whole design follows from keeping them apart.

Two planes

The reasoning plane is the model, its context window, and the harness driving its tool-use loop. It is non-deterministic, stateless between sessions except for what it is fed, and steerable by anyone who can influence its input. It is meant to be interchangeable — bring any model.

The truth plane is the durable store: the data, its schema, its version history, and the executor that admits or refuses each statement. It is persistent, authoritative, and the one component every agent action must pass through to have any effect.

Between them is a narrow interface: statements going down, results coming back. Every guarantee ObeliskDB offers is a property of what happens at that interface — which statements are admitted, how they are rewritten, what is recorded, what is refused. Because enforcement lives in the truth plane, it holds no matter which model is attached, and no matter what a poisoned data cell tells that model to do. See The guarantees.

The stack

ObeliskDB is single-node by design. Each layer is hand-built except the execution kernel.

• - Execution kernel — DuckDB. The vectorized engine that actually runs the rewritten query. Fast, in-process, memory-efficient. Everything distinctive sits above it.
• - Storage — immutable micro-partitions. Table data is written as immutable Parquet micro-partitions. A table version is a delta — files added, files removed — recorded in the catalog. Nothing is mutated in place.
• - Catalog — the version spine. A local metadata store records objects, columns, and the version chain per table. This one structure powers time travel, zero-copy cloning, streams, result caching, and branching. It is the reason git-style workflows are possible on data at all.
• - Query front door. Every statement is parsed (Snowflake dialect via sqlglot), rewritten to read the pruned set of surviving partitions, and executed on DuckDB. Governance is woven into this rewrite — masking and row policies are applied inside the scan, before results reach the caller.
• - Compute — virtual warehouses. Named warehouses with sizes and credit accounting, so cost is measured per statement rather than hidden.

How a statement flows

1. 1. Parse the SQL (Snowflake dialect). Unparseable DDL is routed by a small command layer.
2. 2. Authorize. The session's role must be permitted; masking and row policies attached to referenced objects are resolved.
3. 3. Rewrite. Table references become scans over the surviving micro-partitions (zone-map pruning drops partitions that cannot match). Policies are injected into the scan subquery. Time travel resolves the target version.
4. 4. Execute on DuckDB.
5. 5. Record. The statement, its accessed objects and their versions, its partition-scan profile, and its estimated credits are written to history — the raw material for receipts and reproducibility.

Compatibility as a feature

ObeliskDB speaks the Snowflake SQL dialect and ships drop-in Snowpark and connector APIs. That is a compatibility surface, not an identity — it means existing SQL and Python port with an import change, while the platform underneath is something different: a data plane built for agents.

Interfaces

The same governed engine is reachable four ways, and each inherits the same guarantees:

• - The control plane and classic console (web UI).
• - Obi, the built-in agent.
• - MCP, for external agents — including a governed mode. See Obi & MCP.
• - pgwire (real Postgres clients) and a Snowflake-connector emulator.