h5i-db documentation#

h5i-db is a fast analytical database for quantitative finance and time-series workloads: an embedded, versioned store with DataFusion SQL, native ASOF joins, and previewable mutations. It is written in Rust, driven from the CLI or Python, and built to be safe in the hands of AI agents.

A database is a single directory on disk: like SQLite or DuckDB, there is no server process. Data lives in immutable, time-sorted Parquet segments; every write is an atomic commit that produces a new version, and any past version stays readable forever:

$ h5i-db init market.db
$ h5i-db ingest market.db trades ticks.parquet
$ h5i-db query market.db "SELECT symbol, vwap(price, size) FROM trades GROUP BY symbol"

import h5i_db

db = h5i_db.Database("market.db")
df = db.sql("SELECT * FROM h5i('trades', 42)").to_pandas()   # time travel

What makes it different#

Time-series SQL, natively: full SQL through DataFusion, plus asof_join, time_bucket, vwap, ewma, and gapfill. Storage is time-sorted and declares it, so bucketed aggregations stream instead of sorting.
Every write is a version: immutable segments and per-version manifests make version reads O(1) and as_of lookups O(log V). Named snapshots pin exact versions across tables, so a backtest stays reproducible.
Previewable mutations: deletes and range replacements can be staged as plans. You get exact affected-row counts and before/after samples first, then a metadata-only apply. A mutation policy can require this flow.
Crash-safe by construction: fsync-before-swap, checksums on every object, and a manifest hash chain. The old head survives a crash at any step.
Agent-ready by contract: machine-readable output formats, structured errors with a retryable flag, stable exit codes, and resource limits as flags. It is the same CLI and API humans use, safe to hand to automation.

Finding your way around#

MANUAL Quickstart A working database in five commands, CLI and Python side by side. MANUAL Core concepts Versions, segments, manifests, snapshots, plans, and the mutation policy. REFERENCE CLI reference Every command, flag, output format, and exit code of the h5i-db binary. REFERENCE SQL reference Time travel, ASOF joins, and the time-series function library beyond stock DataFusion. REFERENCE Python API h5i_db.Database, query results, mutation plans, and typed exceptions. TUTORIALS Cookbook 37 executed notebooks: fundamentals, market data engineering, alpha research, risk & production.

Where to go next#

Never used h5i-db? Start with Installation, then the Quickstart.
Coming from pandas/Polars research code? The Cookbook fundamentals teach the database concepts through market-data examples.
Running it in production? The Operations guide covers backup, vacuum, compaction, and the recovery runbook.
Wiring it into an agent or pipeline? See Agents & automation for the machine contract.