Skip to content
NamiDB NamiDB

CLI

The namidb binary wraps the engine for ad-hoc query work (parse, explain, run) against any supported storage backend. No daemon, no server. Each invocation opens a WriterSession (or a Snapshot), does its work, and exits.

See Install for the install command.

Subcommands

namidb parse

Lexes, parses, and prints the canonical round-trip of a Cypher query. Useful for catching syntax errors and verifying the parser accepts a query without touching storage.

Terminal window
namidb parse "MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN b.name LIMIT 5"

namidb explain --verbose

Shows the optimised logical plan with cost and selectivity annotations. Touches the parser, the lowerer, and the optimizer but not storage, so it’s safe to run against a production namespace without I/O.

Terminal window
namidb explain --verbose \
  "MATCH (a:Person)-[:KNOWS]->(b) RETURN b ORDER BY b.id LIMIT 20"

namidb run

Executes a query.

Without --store, runs against an ephemeral in-memory namespace — exactly the same as memory://default. Anything you create is gone when the process exits.

Terminal window
namidb run "CREATE (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}), (a)-[:KNOWS]->(b)"
namidb run "MATCH (a:Person)-[:KNOWS]->(b) RETURN a.name, b.name"

With --store <uri> it opens a durable namespace on any supported backend (file://, s3://, gs://, az://, memory://). Two runs with the same URI see the same data.

Terminal window
namidb run --store "file:///var/lib/namidb?ns=prod" \
  "CREATE (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}), (a)-[:KNOWS]->(b)"


namidb run --store "file:///var/lib/namidb?ns=prod" \
  "MATCH (a:Person)-[:KNOWS]->(b) RETURN a.name, b.name"

Any cloud bucket works the same way:

Terminal window
namidb run --store "s3://my-bucket/data?ns=prod&region=us-east-1" \
  "MATCH (p:Person) RETURN count(*) AS n"


namidb run --store "gs://my-bucket?ns=prod" \
  "MATCH (p:Person) RETURN count(*) AS n"


namidb run --store "az://acct/container?ns=prod" \
  "MATCH (p:Person) RETURN count(*) AS n"

Credentials come from the standard cloud env vars (AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, AZURE_STORAGE_ACCOUNT_NAME, etc.).

URI grammar

--store accepts the same URI scheme as the Python client and the HTTP server. See Storage backends for the per-backend reference. Endpoint overrides (R2, MinIO, LocalStack), GCS service-account paths, Azure emulator mode are all honored.

What’s next

  • Reading data — what to put inside the quoted query string.
  • HTTP server — when you want a long-running process instead of a per-invocation binary.
  • Storage backends — every URI scheme --store accepts.