pydantable + Moltres SQL engine

The moltres-core distribution provides :class:~moltres_core.engine.MoltresPydantableEngine, an implementation of the zero-dependency ExecutionEngine protocol from the pydantable-protocol package (a direct dependency of moltres-core). For backward compatibility, moltres_core also exposes that module as moltres_core.embedded_protocol.

Install

From a checkout of this repository:

pip install -e ./moltres-core
pip install pydantable   # and pydantable-native / meta per pydantable docs

The main moltres package lists moltres-core as a dependency; install it first when working from a monorepo checkout:

pip install -e ./moltres-core
pip install -e .

Usage sketch

  1. Build a SQLAlchemy table (or use MetaData tables) that matches your pydantic schema column names.

  2. Wrap it in :class:~moltres_core.SqlRootData.

  3. Pass a :class:~moltres_core.engine.MoltresPydantableEngine as engine= to :class:pydantable.DataFrame, or call engine methods directly.

from pydantic import BaseModel
from sqlalchemy import Column, Integer, MetaData, String, Table, create_engine, insert

from pydantable import DataFrame
from moltres_core import EngineConfig, MoltresPydantableEngine, SqlRootData
from moltres_core.sql import ConnectionManager


class User(BaseModel):
    id: int
    name: str


eng = create_engine("sqlite:///:memory:")
md = MetaData()
users = Table("users", md, Column("id", Integer), Column("name", String(32)))
md.create_all(eng)

cfg = EngineConfig(engine=eng)
m_engine = MoltresPydantableEngine(ConnectionManager(cfg), cfg)
sql_root = SqlRootData(users)

df = DataFrame[User]._from_plan(
    root_data=sql_root,
    root_schema_type=User,
    current_schema_type=User,
    rust_plan=m_engine.make_plan({"id": int, "name": str}),
    engine=m_engine,
)

Use .select(), .sort(), .head() / .slice(), and .group_by().agg(...) for operations that map to SQL or the small in-memory executor. Expressions in .filter() / .with_columns() still require the native Rust expression runtime or a future SQL expression bridge; those paths raise UnsupportedEngineOperationError today.

Tests

  • tests/test_moltres_core_engine_surface.py — protocol surface + SQL execution.

  • tests/test_pydantable_moltres_integration.py — pydantable DataFrame wiring (aliases pydantable_protocol to the embedded module when needed in dev).

Relationship to moltres

  • moltres-core — SQL connection helpers, query execution, pydantable engine.

  • moltres — full DataFrame API, SQL compilation, integrations; depends on moltres-core and re-exports MoltresPydantableEngine, SqlPlan, and SqlRootData.