Skip to content

README.md

Latest commit

 

History

History
85 lines (71 loc) · 5.85 KB

README.md

File metadata and controls

85 lines (71 loc) · 5.85 KB
Raw

SirixDB Documentation

Start here. This index groups the docs by audience so you don't have to read a flat list of files.

Looking for the quickstart, install instructions, and query examples? Those live in the project README. The hosted docs site is at https://sirix.io/docs/index.html.

For users & operators

Doc What it covers
ARCHITECTURE.md How SirixDB works: the node-tree encoding, copy-on-write page layout, sliding-snapshot versioning, indexes, and the bitemporal model. The best single doc for understanding the system.
operations.md Running SirixDB in production: configuration, memory/JVM tuning, supported environments, and deployment guidance.
BULK_IMPORT.md The sequential and parallel bulk JSON loaders: API, the configurations they refuse, which index families they maintain in the load's single pass, verification guarantees, tuning knobs, and measured numbers.
NATIVE_IMAGE.md Building and running the GraalVM native binaries (instant startup for the CLI, shell, and REST server).
MCP_SERVER_DESIGN.md The Model Context Protocol server for AI agents: tools, resources, snapshot/diff workflow, and security model.

Correctness

Doc What it covers
formal-verification.md The invariant catalog: load-bearing invariants of the engine stated as pre/post-conditions, each with a proof sketch and a pointer to the CI test that discharges it.
cost-based-optimizer-design.md Design of the cost-based query optimizer (PathSummary statistics, selectivity/cardinality estimation, predicate pushdown, join ordering).
KNOWN_LIMITATIONS.md Every disabled test in sirix-core, why it is off, and the tracking artifact — so a real correctness gap is never mistaken for a benchmark that is simply not run in CI.

Projection indexes

Doc What it covers
PROJECTION_INDEXES.md The user-facing feature: what a columnar projection index is, how to create one in JSONiq, and which analytical queries it accelerates. Start here.
PROJECTION_INDEX_DEEP_DIVE.md One dataset walked through every layer — JSON rows to columnar leaves to semantic segments to the bytes on disk to the SIMD kernels — and back up through maintenance and time travel.
PROJECTION_INDEX_INCREMENTAL_MAINTENANCE.md Normative contract for the V0 storage format: exact record lookup, document-order routing, and local update/delete/insert/move maintenance.

The remaining PROJECTION_INDEX_*.md files are storage-format design notes; the deep dive cites them where they matter.

Benchmarks

Doc What it covers
BENCHMARKS.md REST-API behavior under concurrency and a 10,000-commit large-history run, with the environment and raw-log provenance for every number.
CLICKBENCH.md The ClickBench port: the 43 queries translated SQL → JSONiq, the JSON encoding, how to run the load/query/differential gates, and the engine defects the port uncovered.
BENCHMARK_CAMPAIGNS.md Every change made in the ClickBench and JSONBench performance campaigns, written to be readable without prior knowledge of SirixDB internals.

Design notes & development archive

These are engineering working-notes kept for transparency and future reference. They document how some of the harder subsystems were designed, proven, and hardened — especially the HOT (Height-Optimized Trie) index. They are not required reading to use SirixDB, and some describe superseded iterations; treat them as an archive of the design process rather than current user-facing documentation.