Saltearse al contenido

Crates de Rust

Crates

CrateRol
namidb-coreTipos compartidos: ids, esquema, errores
namidb-storageParseo de URIs, sesiones de writer y de lector, WAL, commits del manifest, archivos de datos, flush, compactación, backup
namidb-queryParser, planificador, optimizador y ejecutor de Cypher
namidb-graphKernels de algoritmos de grafos
namidb-markdownIngesta de vaults de Markdown y embedders
namidb-boltProtocolo Bolt (PackStream, handshake, máquina de estados de sesión)
namidb-server, namidb-cli, namidb-mcpLos binarios
namidbFachada; 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?;
ElementoPropó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ónPropósito
parse(src) -> QueryParsea una sentencia.
plan(&query, &catalog) -> LogicalPlanTraduce y optimiza. Construye el catálogo con StatsCatalog::from_manifest(&writer.snapshot().manifest().manifest).
LogicalPlan::contains_write()Si el plan escribe.
execute(&plan, &snapshot, &params) -> Vec<Row>Ejecuta una lectura sobre un snapshot (writer.snapshot()).
execute_write(&plan, &mut writer, &params) -> WriteOutcomeEjecuta 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_rowsFilas 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étodoPropó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étodoDDL 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ónPropó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.