Public API

This page documents the stable import surface for Moltres users. It is the user-facing companion to the maintainer policy in RELEASE_PROCESS.md.

Contract tests in tests/api/test_public_imports.py enforce the exports listed here.

Top-level imports (`moltres`)

from moltres import (
    connect,
    async_connect,
    col,
    lit,
    column,
    MoltresConfig,
    Database,
    AsyncDatabase,
    MoltresPydantableEngine,
    SqlPlan,
    SqlRootData,
    register_performance_hook,
    unregister_performance_hook,
    __version__,
)

`col` vs `column`

Symbol	Purpose
`col("name")`	Column expression for queries (`where`, `select`, etc.)
`column("name", "TEXT")`	DDL helper for `db.create_table()` schemas

Optional interface wrappers

PandasDataFrame, PolarsDataFrame, AsyncPandasDataFrame, AsyncPolarsDataFrame, and AsyncDatabase are loaded lazily. Accessing them without the required extra raises ImportError with an install hint (they are never None).

# pip install moltres[pandas]
from moltres import PandasDataFrame

DataFrame (`moltres.dataframe`)

from moltres.dataframe import (
    DataFrame,
    AsyncDataFrame,
    DataLoader,
    DataFrameWriter,
    ReadAccessor,
    AsyncDataLoader,
    AsyncReadAccessor,
    AsyncDataFrameWriter,
    # Interface wrappers (require extras)
    PandasDataFrame,
    PolarsDataFrame,
    AsyncPandasDataFrame,
    AsyncPolarsDataFrame,
    # GroupBy
    GroupedDataFrame,
    AsyncGroupedDataFrame,
)

Use the PySpark-style API on DataFrame returned from db.table(...).select() or db.load.* file readers.

Union semantics (PySpark difference)

Moltres	PySpark equivalent
`df.union(other)`	`union().distinct()` — distinct rows
`df.unionAll(other)`	`union()` — all rows

When migrating PySpark df1.union(df2), use df1.unionAll(df2) in Moltres.

df.show() prints rows only by default. Pass count_total=True to include a full-table row count (this runs an extra COUNT(*) query).

Expressions (`moltres.expressions`)

from moltres.expressions import col, lit, Column, sum, avg, when
from moltres.expressions import functions as F

Engine (`moltres.engine`)

Lower-level connection and execution helpers:

from moltres.engine import (
    ConnectionManager,
    QueryExecutor,
    QueryResult,
    DialectSpec,
    get_dialect,
    register_performance_hook,
    unregister_performance_hook,
)

Records and CRUD (`moltres.io.records`)

from moltres.io.records import Records, AsyncRecords, LazyRecords, AsyncLazyRecords

Prefer factories and public keyword arguments:

Records.from_list([{"id": 1}], database=db).insert_into("users")
# or
Records(data=[{"id": 1}], database=db).insert_into("users")

Records(_data=...) and Records(_database=...) are deprecated (removed in 2.0).

Database CRUD (sync and async)

Sync:

db.insert("users", rows)
db.update("users", where=col("id") == 1, set={"name": "Alice"})
db.delete("users", where=col("id") == 1)
db.merge("users", rows, on=["id"], when_matched={"name": "Bob"})

Async (AsyncDatabase — same method signatures):

async def insert_users(db, rows):
    return await db.insert("users", rows)

Reading data: choose the right API

Goal	API	Returns
Query a SQL table	`db.table("t").select().where(...)`	`DataFrame`
Load a file for querying	`db.load.csv("data.csv")`	`DataFrame`
Load a file as row dicts	`db.read.records.csv("data.csv")`	`Records` / `LazyRecords`
Polars-style file scan	`db.scan_csv("data.csv")`	`PolarsDataFrame` (optional)

Canonical paths

Lazy DataFrame from files: db.load.csv() — preferred
Eager rows from files: db.read.records.csv()
db.read.csv() etc.: deprecated for DataFrame reads; use db.load.* instead

Optional extras

Extra	Install	Enables
`pandas`	`pip install moltres[pandas]`	`PandasDataFrame`, pandas result formats
`polars`	`pip install moltres[polars]`	`PolarsDataFrame`, polars result formats
`parquet`	`pip install moltres[parquet]`	Parquet file I/O via pyarrow
`fastapi`	`pip install moltres[fastapi]`	FastAPI integration helpers
`duckdb`	`pip install moltres[duckdb]`	DuckDB SQLAlchemy dialect
`async` / `async-sqlite`	`pip install moltres[async-sqlite]`	`AsyncDatabase`, async file I/O
`sqlmodel`	`pip install moltres[sqlmodel]`	SQLModel / Pydantic model integration
`streamlit`	`pip install moltres[streamlit]`	Streamlit components
`django`	`pip install moltres[django]`	Django middleware and template tags
`airflow`	`pip install moltres[airflow]`	Airflow operators
`prefect`	`pip install moltres[prefect]`	Prefect tasks
`dbt`	`pip install moltres[dbt]`	dbt adapter helpers
`async-postgresql`	`pip install moltres[async-postgresql]`	Async PostgreSQL (`asyncpg`)
`async-mysql`	`pip install moltres[async-mysql]`	Async MySQL (`aiomysql`)
`pydantable-integration`	`pip install moltres[pydantable-integration]`	pydantable engine integration

Integrations (`moltres.integrations`)

Optional framework helpers (install the matching extra first):

from moltres.integrations import (
    fastapi_integration,
    pytest_integration,
    dbt_integration,
    django_integration,
    sqlalchemy_integration,
)

See integration guides under Integrations in the docs sidebar.

API decision guide

Type	Role	CRUD?
`Database` / `AsyncDatabase`	Connection + `db.table()` + `db.insert/update/delete/merge`	Yes
`TableHandle` / `AsyncTableHandle`	`db.table("t").select()` query entry	No (query only)
`DataFrame` / `AsyncDataFrame`	Lazy SQL transforms	Via `df.write.*` or collect then `db.insert`
`Records` / `AsyncRecords`	Eager row dicts from files or Python	`insert_into()`

PySpark compatibility

Moltres targets a PySpark-like DataFrame API. Coverage varies by operation and dialect. See:

What is not public API

Modules under moltres.sql, moltres.logical, moltres.dataframe.managers, and empty __init__.py packages are internal implementation details.

Public API

Top-level imports (moltres)

col vs column