{"slug": "koutendb-v0-9-0-from-a-locality-experiment-to-a-testable-database", "title": "KoutenDB v0.9.0: From a Locality Experiment to a Testable Database", "summary": "KoutenDB v0.9.0, a ring-oriented NoSQL document and vector database written in Nim, has been released. The release focuses on testing the locality model against realistic persistent related-data reads, adding benchmarks and optimizations. In a local benchmark, KoutenDB achieved 196.859 microseconds for a heterogeneous related-data bundle, compared to 515 microseconds for six indexed PostgreSQL queries and 236 microseconds for a PostgreSQL JSON aggregate.", "body_md": "I released **KoutenDB v0.9.0**.\n\nRelease:\n\n[https://github.com/puffball1567/koutendb/releases/tag/v0.9.0](https://github.com/puffball1567/koutendb/releases/tag/v0.9.0)\n\nKoutenDB is a ring-oriented NoSQL document and vector database written in Nim.\n\nIts central idea is deliberately narrow: when an application already knows a useful locality boundary, that knowledge should reduce the data a request has to inspect.\n\nPrevious releases established the data model, public API, native C ABI, and language-driver foundation. v0.9.0 concentrates on a harder question: can that locality model be tested against a realistic, persistent related-data read shape rather than only described as a design idea?\n\nThis is still a technical preview. It is not a claim that KoutenDB replaces PostgreSQL, Redis, or every document store. The goal of this release is to make the narrower claim measurable and reproducible.\n\nMany web application detail pages need more than one record. A user page, for example, may need a profile, a few addresses, recent employment entries, preferences, recent orders, and notifications. Each collection has its own limit and sort order.\n\nIn a relational database, this can be expressed with several indexed queries or with a JSON aggregate query built from limited subqueries. Both are valid approaches. The question KoutenDB explores is different: if these collections are already known to belong to one user, can that relationship be represented as bounded nearby data from the start?\n\nv0.9.0 models the example as subrings below a user ring:\n\n```\nkouten get --ring=users/<id> \\\n  --subring=profile,addresses,career,preferences,orders,notifications \\\n  --subring-limit=profile:1,addresses:3,career:2,preferences:1,orders:10,notifications:5 \\\n  --subring-rsort=orders:time,notifications:time\n```\n\nThis says exactly what the endpoint needs: retrieve six nearby collections, with independent bounds. It is not a general query language and it is not intended to be one. The useful property is that the caller supplies the locality boundary before the read begins.\n\nThe release adds a benchmark for that heterogeneous related-data bundle and strengthens the corresponding read path.\n\n`readStellar`\n\nnow prepares projection state once and reuses it across\nsubrings.`id`\n\nor\n`time`\n\nordering can use a bounded ring-window read path.`import-jsonl`\n\nsupports chunked commits through `--batch-size=N`\n\nfor larger\ndata imports.The point of these changes is not an isolated micro-optimization. A locality model only helps if its normal persistent read path remains bounded when the dataset grows.\n\nThe repository now includes a helper that builds fresh temporary KoutenDB and PostgreSQL data directories, loads the same logical user dataset, and measures the related-data bundle:\n\n```\nN=10000 READS=1000 examples/subring_bundle_postgres_bench.sh\n```\n\nOne local run on 2026-07-21 used an AMD Ryzen 5 5600H, Linux 6.8, Nim 2.2.10, and PostgreSQL 14.23.\n\n| Users | Logical records | System and query shape | Returned records | Read latency |\n|---|---|---|---|---|\n| 10,000 | 1,050,000 | KoutenDB `users/<id>/*` stellar read with per-subring bounds |\n22 across 6 rings | 196.859 us |\n| 10,000 | 1,050,000 | PostgreSQL: six indexed `SELECT` statements |\n22 | 515 us |\n| 10,000 | 1,050,000 | PostgreSQL: JSON aggregate over indexed limited subqueries | 1 JSON bundle | 236 us |\n\nThese numbers describe one machine and one workload; they are not a universal database ranking. PostgreSQL's aggregate form is close to the measured KoutenDB result, and it expresses the result through a different but perfectly\n\nreasonable abstraction. The value of the comparison is to keep the claim honest: KoutenDB's ring and subring model should be judged on workloads where the application can name a local working set.\n\nv0.9.0 also records the completed disk-backed effect-validation run on generated data. The validation imports deterministic JSONL corpora and compares broad retrieval with ring-routed retrieval. It reports import time, records scanned, estimated token volume, and retrieval latency.\n\nThe standard scale-1000 matrix completed locally with a largest case of 13,500,000 documents.\n\n| Workload | Broad scan | Ring-routed scan | Estimated tokens: broad -> routed |\n|---|---|---|---|\n`small-balanced` |\n168,000 | 24,000 | 692 -> 260 |\n`near-distractors` |\n1,860,000 | 120,000 | 1,730 -> 433 |\n`medium-noisy` |\n13,500,000 | 500,000 | 2,595 -> 692 |\n\nThe token column is an estimate for the generated retrieval payloads, not a benchmark of any model. More generally, this validation is not limited to AI workloads. Scanned records, transferred data, candidate memory, and downstream application work all increase when a request must inspect unrelated data.\n\nThe important result is that the test makes the expected trade-off visible:\n\nlocality can reduce the candidate set when the application supplies a valid ring boundary. It cannot invent a useful boundary when the application has none.\n\nThe release also adds an offline JSONL path:\n\n```\nKOUTEN_REAL_JSONL=/path/to/export.jsonl \\\nQUERY_RING=docs/japan \\\nexamples/offline_effect_validation.sh\n```\n\nThis is intended for copied or exported data rather than a production service.\n\nIt gives a team a way to test whether a proposed ring layout narrows its own workload before asking the database to serve live traffic.\n\nThat boundary matters. A database experiment should be reproducible without requiring production credentials, traffic capture, or an unbounded benchmark environment.\n\nThe v0.9.0 release state was checked with Nim module checks, the public API test program, the smoke suite, package validation, and whitespace validation:\n\n```\nnim check src/kouten/store.nim\nnim check src/koutendb.nim\nnim check src/koutencli.nim\nnim check tests/tapi.nim\nnim c --nimcache:/tmp/nimcache_kouten_tapi -r tests/tapi.nim\nscripts/test_all_smoke.sh\nnimble check\ngit diff --check\n```\n\nThe largest generated run remains an explicit manual validation rather than a default CI job. It is valuable precisely because it exercises a scale that a quick smoke test should not pretend to cover.\n\nv0.9.0 makes the locality hypothesis easier to test with persistent data and a concrete web-style read shape. The next work is about making that evaluation more operable: verification commands, controlled drain and snapshot workflows, backup checks, audit records, and safer topology transitions.\n\nThose are v0.10 development goals, not claims included in v0.9.0.\n\nKoutenDB remains an early project, but the direction is now more concrete:\n\ndata locality should be a testable part of a database read path, not only a diagram or a benchmark headline.\n\nSource and release notes:", "url": "https://wpnews.pro/news/koutendb-v0-9-0-from-a-locality-experiment-to-a-testable-database", "canonical_source": "https://dev.to/puffball1567/koutendb-v090-from-a-locality-experiment-to-a-testable-database-2api", "published_at": "2026-08-02 11:09:04+00:00", "updated_at": "2026-08-02 11:44:29.222179+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["KoutenDB", "PostgreSQL", "Nim", "puffball1567"], "alternates": {"html": "https://wpnews.pro/news/koutendb-v0-9-0-from-a-locality-experiment-to-a-testable-database", "markdown": "https://wpnews.pro/news/koutendb-v0-9-0-from-a-locality-experiment-to-a-testable-database.md", "text": "https://wpnews.pro/news/koutendb-v0-9-0-from-a-locality-experiment-to-a-testable-database.txt", "jsonld": "https://wpnews.pro/news/koutendb-v0-9-0-from-a-locality-experiment-to-a-testable-database.jsonld"}}