30-second quickstart

The fastest possible taste of NamiDB. Ephemeral, in-process, no setup.

Install

Python

pip install namidb

Rust

cargo add namidb

CLI

cargo install --git https://github.com/namidb/namidb namidb-cli

Hello, graph

Python

import namidb as tg

client = tg.Client("memory://acme")

client.cypher("CREATE (a:Person {name: 'Alice'})")
client.cypher("CREATE (b:Person {name: 'Bob'})")
client.cypher(
    "MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) "
    "CREATE (a)-[:KNOWS {since: 2020}]->(b)"
)

result = client.cypher("MATCH (p:Person) RETURN p.name AS name")
print(result.rows())
# [{'name': 'Alice'}, {'name': 'Bob'}]

Rust

use namidb_query::{execute, lower, parse, Params};
use namidb_storage::{parse_uri, WriterSession};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (store, paths) = parse_uri("memory://acme")?;
    let mut writer = WriterSession::open(store, paths).await?;

    // ... upsert nodes / edges, then commit_batch + flush ...

    let snap = writer.snapshot();
    let query = parse("MATCH (a:Person) RETURN count(*) AS n")?;
    let plan  = lower(&query)?;
    let rows  = execute(&plan, &snap, &Params::new()).await?;

    println!("{rows:?}");
    Ok(())
}

CLI

namidb run "CREATE (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})"
namidb run "MATCH (p:Person) RETURN p.name"

HTTP

# In one shell: start the server
namidb-server --store memory://acme --listen 127.0.0.1:8080

# In another:
curl -s -X POST http://127.0.0.1:8080/v0/cypher \
  -H 'Content-Type: application/json' \
  -d '{"query": "CREATE (a:Person {name: \"Alice\"}) RETURN a.name"}'

What just happened?

You created a namespace called acme backed by in-memory storage, inserted two nodes and one edge, and read back a projection. Everything ran in-process — no daemon, no credentials, no network round-trips.

Make it persistent

Swap the URI. The same six lines of code work against any backend:

Local file

client = tg.Client("file:///var/lib/namidb?ns=prod")

AWS S3

client = tg.Client("s3://my-bucket/data?ns=prod&region=us-east-1")

Cloudflare R2

client = tg.Client(
    "s3://my-bucket?ns=prod"
    "&endpoint=https://<ACCOUNT_ID>.r2.cloudflarestorage.com"
    "&region=auto"
)

GCS

client = tg.Client("gs://my-bucket/data?ns=prod")

Azure Blob

client = tg.Client("az://account/container?ns=prod")

Next steps

• Your graph in S3 — the headline use case, end-to-end.
• Choose a deployment — Embedded vs Server vs Cloud.
• Cypher reference — exactly which Cypher / GQL the engine understands today.
• Operations / URI grammar — all backends, every query-string flag.