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. 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"},"age":30,"name":"ana"}

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.

4. 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"},"age":30,"name":"ana"}

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

5. Inspect the catalog

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

omgdb inspect app.omgdb
# users: 2 docs

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

6. Describe the database

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

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

See introspection for what schema inference covers.

7. 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.

8. Create an index

Create a secondary equality index on a field. The index accelerates top-level equality (and range/multikey) predicates; it holds no authoritative data and can be rebuilt from the log.

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

Limitation: Compound (multi-field), unique, and partial indexes are not implemented yet. See indexes.

9. 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>'.

10. 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.

11. Verify the store

verify re-reads the op-log and proves that replaying it reproduces the live in-memory state. 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, a torn trailing record is skipped on open and noted with a WARN on stderr. 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
# {"op":"insert","ns":"users","doc":{"_id":{"$oid":"018f...c2"},"age":30,"name":"ana"}}	1a2b3c4d
# {"op":"insert","ns":"users","doc":{"_id":{"$oid":"018f...d7"},"age":20,"name":"bob"}}	5e6f7a8b
# ...

This file is the entire authoritative state of the database. Everything else is derived.

Point an agent at it

To drive the store from an LLM 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

Edit this page on GitHub →