OMGDB DOCS
// Start

Quickstart

A guided walkthrough from an empty folder to an agent-ready OMGDB store using only real omgdb CLI commands.

This walkthrough takes you from an empty folder to a populated, verified, agent-ready store using only commands the omgdb binary actually implements. Every step shows the command and a one-line note on what it prints. The example store path is app.omgdb throughout.

A store is a directory bundle whose source of truth is an append-only NDJSON op-log (app.omgdb/oplog.ndjson). Indexes, vectors, and caches are derived artifacts you can rebuild from that log. See storage and architecture for the full model.

Note: Document, _id, filter, projection, pipeline, and update arguments are all passed as JSON strings. On a POSIX shell, single-quote them so the shell does not eat the inner double quotes.

1. Create a store

The simplest form opens (or creates) a store directory:

omgdb create app.omgdb
# created store at app.omgdb

Optionally seed it from a JSON collection spec with --from. The spec defines collections and their validation rules, which are then enforced on insert.

{ "collections": { "users": { "required": ["name"], "fields": { "age": "long" } } } }
omgdb create app.omgdb --from spec.json
# created store at app.omgdb (1 collection(s) defined)

Note: --from reads the spec as JSON, not YAML. Only the collections object (with required and fields) is supported. See schema validation.

2. Insert documents

Insert a JSON object into a collection. The assigned _id is printed as canonical JSON — an ObjectId rendered {"$oid":"..."}.

omgdb insert app.omgdb users '{"name":"ana","age":30}'
# {"$oid":"018f...c2"}

omgdb insert app.omgdb users '{"name":"bob","age":20}'
# {"$oid":"018f...d7"}

The document argument must be a JSON object, or the command errors with document must be a JSON object.

3. Bulk load with import-jsonl

For anything bigger than a handful of documents, stream a JSON Lines file instead of looping insert. Each non-empty line must be a JSON object; documents are committed in atomic batches (1,000 per commit by default, tunable with --batch-size), so the whole load pays one fsync per batch instead of one per document:

omgdb import-jsonl app.omgdb users users.jsonl
# {"inserted":50000,"batches":50}

Loading 50,000 documents takes about 2 seconds. Single durable inserts are fsync-bound — the same physical wall every embedded database hits — so the batch path is the right tool for bulk data.

4. Find with a filter

Find matching documents with a MongoDB-style filter. Each match prints as one canonical-JSON line. The positional filter defaults to {} (match all).

omgdb find app.omgdb users '{"age":{"$gte":25}}'
# {"_id":{"$oid":"018f...c2"},"name":"ana","age":30}

Use --limit N to cap output and --project '{"field":1}' to include (or 0 to exclude) fields. An unknown operator surfaces a clear error naming the bad token (e.g. $bogus). The full set is documented in query operators.

5. Get a document by _id

Fetch a single document by its _id, parsed as JSON. Pass the ObjectId verbatim:

omgdb get app.omgdb users '{"$oid":"018f...c2"}'
# {"_id":{"$oid":"018f...c2"},"name":"ana","age":30}

If nothing matches, the command exits non-zero with document not found.

6. Inspect the catalog

List each collection and its document count. With --json it emits a machine-readable shape for tools and AI agents.

omgdb inspect app.omgdb
# users: 2 docs

omgdb inspect app.omgdb --json
# {"collections":[{"name":"users","count":2}]}

7. Describe the database

describe prints a Markdown manual of the live store: each collection, its inferred per-field schema, its indexes and validation spec, and sample documents. This is the page an agent reads to learn a database it has never seen.

omgdb describe app.omgdb
# ## users
# ... inferred fields (name, age) and sample documents ...

See introspection for what schema inference covers.

8. Import a Markdown file

import-md ingests a Markdown file as a single document: YAML frontmatter becomes queryable fields and headings become a stored section tree under _sections. It inserts into the named collection and prints the new _id.

Given note.md:

---
title: Spec
tags: ["a"]
---
# Intro

hello
omgdb import-md app.omgdb docs note.md
# {"$oid":"018f...e9"}

omgdb find app.omgdb docs '{"title":"Spec"}'
# frontmatter is queryable; the document contains _sections

More detail in markdown.

9. Create an index

Create a secondary index on one or more fields. Indexes accelerate top-level equality, $in, range, and multikey predicates; they hold no authoritative data and can be rebuilt from the log.

omgdb create-index app.omgdb users name
# created index on `users.name`

Multiple fields create a compound index; --unique adds a uniqueness constraint; --partial '<filter-json>' restricts the index to matching documents:

omgdb create-index app.omgdb users tenant email --unique
# created unique compound index on `users.(tenant,email)`

See indexes for what each variant accelerates and how the planner proves an index safe before using it.

10. Explain a query

explain shows how a filter will be executed — index scan versus full scan — by compiling the filter and reporting the chosen plan.

omgdb explain app.omgdb users '{"name":"ana"}'
# describes whether the users.name index is used or a full scan is needed

For a “why-not” view of per-predicate selectivity, use omgdb diagnose app.omgdb users '<filter>'; for machine-readable index recommendations, omgdb suggest-indexes.

11. Vector search a text field

vsearch ranks documents by similarity of a text field to a query using the bundled offline embedder. Each hit prints as <score>\t<document>.

omgdb vsearch app.omgdb docs text "database search" --k 5
# 0.7421	{"_id":{"$oid":"..."},"text":"database search and indexing", ...}

Use --filter '<json>' to pre-filter candidates (hybrid search). To persist embeddings for reuse, run omgdb vsync app.omgdb docs text, which writes a sidecar collection docs.__vectors.

Note: The bundled embedder is a deterministic, dependency-free hashing baseline — not a neural model — so relevance is approximate. See vector search and context packs.

12. Verify the store

verify re-reads the op-log and proves that replaying it reproduces the state — every record and every derived cache. This is the integrity check that makes the text-canonical design trustworthy.

omgdb verify app.omgdb
# OK: 4 record(s), 3 document(s) in 2 collection(s); log reproduces state

It exits non-zero with INCONSISTENT if replay does not reproduce the state. If a write was interrupted, the torn trailing fragment is preserved to oplog.torn.bak and trimmed from the log on open, noted with a WARN on stderr — nothing is silently dropped. To recover a genuinely corrupt log, see omgdb repair in storage.

Peek at the text-canonical log

Because the op-log is plain NDJSON with a per-record CRC32, you can read it directly. Each line is <canonical-json>\t<crc32-hex>:

cat app.omgdb/oplog.ndjson
# {"lsn":0,"ts":{"$date":1719900000000},"op":"insert","ns":"users","id":{"$oid":"018f...c2"},"doc":{"_id":{"$oid":"018f...c2"},"name":"ana","age":30}}	1a2b3c4d
# {"lsn":1,"ts":{"$date":1719900012000},"op":"insert","ns":"users","id":{"$oid":"018f...d7"},"doc":{"_id":{"$oid":"018f...d7"},"name":"bob","age":20}}	5e6f7a8b
# ...

This file is the entire authoritative state of the database. Everything else — including the .cache sidecars you may see next to it — is derived and rebuildable.

Point an agent at it

To drive the store from a coding agent, run the MCP (Model Context Protocol) stdio server. The capability ceiling is set with --scope (read, read-write (default), or dangerous).

omgdb mcp --scope read-write
# JSON-RPC over stdio; serverInfo name "omgdb"; tools include vsearch and aggregate

The combination of describe (the manual), explain/diagnose (the debugger), verify (the proof), and the MCP server is what makes a store agent-ready. See mcp and agent mutations.

Where to next

View this page as raw Markdown →