Saltearse al contenido
NamiDB NamiDB

SDK de Rust (embebido)

El crate namidb es la fachada pública del motor: re-exporta la superficie estable de namidb-core, namidb-storage, namidb-graph y namidb-query, así el código downstream sólo necesita una línea.

Agregarlo

Cargo.toml
[dependencies]
namidb = "0.3"
tokio = { version = "1", features = ["full"] }
anyhow = "1"

El MSRV es Rust 1.85.

Abrir un namespace

use namidb::storage::{parse_uri, WriterSession};


#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (store, paths) = parse_uri("s3://my-bucket?ns=prod&region=us-east-1")?;
    let mut writer = WriterSession::open(store, paths).await?;


    // ... upserts, commit_batch, snapshot reads ...


    Ok(())
}

Funciona con cualquier esquema de URI: memory://, file://, s3://, gs://, az://.

Ejecutar Cypher

use namidb_query::{execute, lower, parse, Params};


let query = parse(
    "MATCH (a:Person) WHERE a.age > $min RETURN a.name AS name"
)?;
let plan = lower(&query)?;


let snap   = writer.snapshot();
let params = Params::from_iter([("min", 18.into())]);
let rows   = execute(&plan, &snap, &params).await?;


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

API directa de escritura

Para el camino de ingesta con mayor throughput (sin pasar por el parser):

use namidb_core::id::{NodeId, EdgeType, Label};
use namidb_core::value::Value;


let alice = NodeId::generate_v7();
let bob   = NodeId::generate_v7();


writer.upsert_node(Label::new("Person"), alice, [
    ("name", Value::String("Alice".into())),
    ("age",  Value::Integer(30)),
].into())?;


writer.upsert_node(Label::new("Person"), bob, [
    ("name", Value::String("Bob".into())),
].into())?;


writer.upsert_edge(
    EdgeType::new("KNOWS"),
    alice,
    bob,
    [("since", Value::Integer(2020))].into(),
)?;


writer.commit_batch().await?;   // WAL append + manifest CAS
writer.flush().await?;          // memtable -> SSTs L0

Snapshots

let snap_a = writer.snapshot();
// ... ocurren escrituras, el manifest avanza ...
let snap_b = writer.snapshot();
// snap_a sigue referenciando el manifest anterior; ambos son válidos.

Los snapshots son baratos: pinean una versión de manifest y las SSTs que referencia. El GC no va a reclamar SSTs mientras algún snapshot las sostenga.

Configuración de caches

Env varDefaultCache
NAMIDB_ADJACENCYONCSR adjacency (RFC-018)
NAMIDB_NODE_CACHEONLookups de NodeView (RFC-019)
NAMIDB_SST_CACHEONBody de SST + streams de propiedades de edges (RFC-020)
NAMIDB_FACTORIZEOFFEjecutor factorizado (RFC-017)

Layout de crates

CrateSuperficie
namidbFachada pública (re-exporta las partes estables de los demás)
namidb-coreNamespaceId, NodeId, EdgeId, Lsn, Value, Schema, errores
namidb-storageLSM, WAL, manifest, SST, memtable, parser de URIs, CAS de file://
namidb-graphColumnas de propiedades + CSR adjacency
namidb-queryParser de Cypher / GQL, optimizador, ejecutor

Para uso día a día, dependé sólo de namidb. Bajá a los sub-crates cuando estés embebiendo profundo (por ejemplo, escribiendo reglas custom del optimizador).

Ver también