Crates de Rust
Crates
| Crate | Rol |
|---|---|
namidb-core | Tipos compartidos: ids, esquema, errores |
namidb-storage | Parseo de URIs, sesiones de writer y de lector, WAL, commits del manifest, archivos de datos, flush, compactación, backup |
namidb-query | Parser, planificador, optimizador y ejecutor de Cypher |
namidb-graph | Kernels de algoritmos de grafos |
namidb-markdown | Ingesta de vaults de Markdown y embedders |
namidb-bolt | Protocolo Bolt (PackStream, handshake, máquina de estados de sesión) |
namidb-server, namidb-cli, namidb-mcp | Los binarios |
namidb | Fachada; actualmente solo reexporta namidb-core |
[dependencies]namidb-storage = { git = "https://github.com/namidb/namidb", tag = "v3.3.0" }namidb-query = { git = "https://github.com/namidb/namidb", tag = "v3.3.0" }Abrir un namespace
use namidb_storage::{parse_uri, ReaderSession, WriterSession};
let (store, paths) = parse_uri("file:///var/lib/namidb?ns=prod")?;let mut writer = WriterSession::open(store.clone(), paths.clone()).await?;| Elemento | Propósito |
|---|---|
parse_uri(uri) -> (Arc<dyn ObjectStore>, NamespacePaths) | La misma gramática que todos los demás puntos de entrada (URIs de almacenamiento). |
parse_store(uri) | Solo el store, sin exigir ?ns=. |
WriterSession::open(store, paths) | Abre (o crea) un namespace como su writer. Bloquea (fencing) a cualquier writer anterior. |
ReaderSession::open(store, paths, cache) | Abre un namespace existente en solo lectura, sin reclamarlo; refresh() avanza al commit más reciente. |
Ejecutar Cypher
| Función | Propósito |
|---|---|
parse(src) -> Query | Parsea una sentencia. |
plan(&query, &catalog) -> LogicalPlan | Traduce y optimiza. Construye el catálogo con StatsCatalog::from_manifest(&writer.snapshot().manifest().manifest). |
LogicalPlan::contains_write() | Si el plan escribe. |
execute(&plan, &snapshot, ¶ms) -> Vec<Row> | Ejecuta una lectura sobre un snapshot (writer.snapshot()). |
execute_write(&plan, &mut writer, ¶ms) -> WriteOutcome | Ejecuta una escritura y la confirma antes de retornar; ante un error, el lote acumulado se descarta. |
execute_write_with_deadline(…, deadline) | Lo mismo con un deadline que cubre la ejecución y el commit. |
explain_query(…), explain_plan_lines(…) | Muestran planes como EXPLAIN. |
show_constraints_rows, show_indexes_rows | Filas para SHOW CONSTRAINTS / SHOW INDEXES. |
Params es un BTreeMap<String, RuntimeValue>. Row contiene un
bindings: BTreeMap<String, RuntimeValue>; usa output_columns(&plan) para
obtener el orden del RETURN. WriteOutcome lleva nodes_created,
edges_created, nodes_deleted, edges_deleted, properties_set y las
filas retornadas.
Variantes de RuntimeValue: Null, Bool, Integer(i64), Float(f64),
String, Bytes, Vector(Vec<f32>), List, Map, Date (días desde el
epoch), DateTime (microsegundos UTC), Node, Rel, Path.
Escribir sin Cypher
WriterSession acumula registros directamente; commit_batch() los hace
durables:
| Método | Propósito |
|---|---|
upsert_node(label, id, &NodeWriteRecord) / upsert_node_with_labels(labels, id, &record) | Acumula un nodo. |
upsert_edge(edge_type, src, dst, &EdgeWriteRecord) | Acumula una relación. |
tombstone_node(label, id), tombstone_edge(edge_type, src, dst) | Acumulan borrados. |
commit_batch() | Append al WAL + commit del manifest. |
discard_batch() | Descarta los registros acumulados. |
Esquema
El servidor y la CLI interceptan las sentencias DDL antes de la planificación. En Rust llama a los métodos directamente:
| Método | DDL equivalente |
|---|---|
create_unique_constraint_named(name, label, &properties, if_not_exists) (una propiedad o una tupla compuesta) | CREATE CONSTRAINT … IS UNIQUE |
create_property_index_named(…), create_composite_index_named(…) | CREATE INDEX |
register_vector_index(…), drop_vector_index(name, if_exists) | CREATE / DROP VECTOR INDEX (feature vector-index) |
register_text_index(…), drop_text_index(name, if_exists) | CREATE FULLTEXT INDEX / DROP INDEX (feature text-index) |
El Query que retorna parse expone as_create_constraint(),
as_create_index(), as_create_vector_index(),
as_create_fulltext_index() y as_show_schema() para detectar estas
sentencias y leer sus cláusulas.
Mantenimiento
| Método o función | Propósito |
|---|---|
WriterSession::flush(schema) | Escribe la memtable en archivos L0. |
WriterSession::maybe_flush(max_wal_segments) | Hace flush solo cuando el WAL creció más allá de un límite. |
WriterSession::compact_l0(&schema) | Compacta el nivel 0. |
sweep_orphans(…) | Borra objetos sin referencias (el sweep del janitor). |
copy_namespace_snapshot(…) | La copia consistente de snapshot detrás de namidb backup / restore. |
Entorno
El motor lee sus ajustes de caché, spool y búsqueda del entorno la primera
vez que los necesita (NAMIDB_CACHE_MAX_BYTES, NAMIDB_SPOOL_DIR, …);
consulta la referencia de configuración.
Los programas embebidos que quieran la validación temprana de esos valores
que hace el servidor pueden llamar a
namidb_storage::validate_cache_configuration() al arrancar.