Referencia de la API de Python
pip install namidb # Python >= 3.9; pyarrow >= 14 comes with itimport namidbprint(namidb.__version__) # 3.3.0El paquete exporta Client, QueryResult, NodeIter, EdgeIter,
QueryTimeoutError y QueryRowCapError. Para patrones de despliegue
(durabilidad, espacio en disco, clientes de solo lectura, hilos) consulta
Embebido (Python).
Client
namidb.Client( uri, cache_bytes=None, *, read_only=False, spool_dir=None, auto_sweep_min_age_secs=60, compaction_l0_trigger=8,)| Parámetro | Significado |
|---|---|
uri | URI de almacenamiento con el namespace: memory://ns, file:///dir?ns=ns, s3://…, gs://…, az://…. Consulta URIs de almacenamiento. |
cache_bytes | Tamaño de la caché de SST de este cliente, informado por cache_stats(). Por defecto 64 MiB. Las cachés de todo el proceso se dimensionan con NAMIDB_CACHE_MAX_BYTES. |
read_only | Abre sin reclamar el namespace; cada método que modifica lanza PermissionError. El namespace debe existir. |
spool_dir | Directorio temporal para la compactación. Por defecto NAMIDB_SPOOL_DIR, luego <root>/.namidb-spool para file://, si no /var/tmp. |
auto_sweep_min_age_secs | Después de una compactación aplicada, borra los objetos sin referencias más antiguos que este valor. None desactiva el sweep automático. |
compaction_l0_trigger | flush() compacta cuando un bucket contiene esta cantidad de archivos de nivel 0. 0 desactiva. |
Un Client también es un context manager; salir del bloque with llama a
close().
Cypher
| Método | Retorna |
|---|---|
cypher(query, params=None, *, timeout_ms=None, max_rows=None) | QueryResult |
acypher(query, params=None, *, timeout_ms=None, max_rows=None) | QueryResult awaitable |
- Las escrituras y el DDL se confirman antes de que la llamada retorne.
paramses undict[str, Any]; consulta el mapeo de tipos.timeout_mslimita la llamada completa, incluida la espera por el lock de escritura del cliente; una escritura que agota el tiempo se descarta. LanzaQueryTimeoutError.max_rowshace fallar una lectura en cuanto cualquier paso del plan produce más filas. LanzaQueryRowCapError. Las escrituras lo ignoran.- Los errores de sintaxis y de planificación lanzan
ValueError; los errores de ejecución lanzanRuntimeError; las escrituras en un cliente de solo lectura lanzanPermissionError.
result = db.cypher( "MATCH (p:Person) WHERE p.age > $min RETURN p.name AS name, p.age AS age", params={"min": 26},)QueryResult
| Miembro | Retorna |
|---|---|
columns | Nombres de columnas en el orden del RETURN (también para un resultado vacío). |
rows() | list[dict], un dict por fila. |
first() | La primera fila, o None. |
len(result) | Cantidad de filas. |
to_arrow() | pyarrow.Table |
to_pandas() | pandas.DataFrame (requiere namidb[pandas]) |
to_polars() | polars.DataFrame (requiere namidb[polars]) |
r = db.cypher("MATCH (i:Item) RETURN i.name AS name ORDER BY name")r.columns # ['name']len(r) # 3r.first() # {'name': 'a'}r.to_pandas() # DataFrame with one column, 'name'Carga masiva
Estos métodos acumulan cambios en un lote pendiente. Llama a commit()
para hacerlos durables. Omiten el parseo y la planificación de Cypher, así
que son la ruta rápida para cargas grandes.
| Método | Efecto |
|---|---|
put_nodes(label, rows) | Reemplaza nodos. Cada fila es un dict con _id (string UUID) más propiedades; la fila es el conjunto completo de propiedades del nodo y label su único label. No lee primero: es lo más rápido para cargas iniciales. Retorna la cantidad acumulada. |
merge_nodes(label, rows) | Fusiona en los nodos guardados: las claves no mencionadas se conservan, un valor None elimina la clave y se agrega label. Lee cada nodo primero. |
merge_edges(edge_type, rows) | Hace upsert de relaciones. Cada fila tiene strings UUID src y dst más propiedades. |
upsert_node(label, id, properties) | Acumula un nodo. |
upsert_node_with_labels(labels, id, properties) | Acumula un nodo con un conjunto completo de labels. |
upsert_edge(edge_type, src, dst, properties) | Acumula una relación. |
tombstone_node(label, id) | Acumula el borrado de un nodo. |
tombstone_edge(edge_type, src, dst) | Acumula el borrado de una relación. |
load_parquet_nodes(label, path, commit_every=0) | Carga un archivo Parquet: una columna node_id de UUIDs de 16 bytes (FixedSizeBinary(16) o binario de 16 bytes), y cada otra columna como una propiedad. Retorna las filas cargadas. |
load_parquet_edges(edge_type, path, commit_every=0) | Carga un archivo Parquet con columnas src y dst de UUIDs de 16 bytes; las demás columnas son propiedades. Los extremos deben existir. |
commit() | Confirma el lote pendiente (append al WAL + commit del manifest). Retorna el último LSN, o None para un lote vacío. |
import uuid
alice, bob = str(uuid.uuid4()), str(uuid.uuid4())db.put_nodes("Person", [ {"_id": alice, "name": "Alice", "age": 30}, {"_id": bob, "name": "Bob"},])db.merge_edges("KNOWS", [{"src": alice, "dst": bob, "since": 2020}])db.commit()db.flush()_id es el id del nodo, el mismo valor que n._id e id(n) en Cypher; no
se guarda como propiedad, así que una clave de negocio llamada id puede
convivir con él. Las filas identificadas solo con id (la forma anterior)
siguen funcionando: id se convierte en el id del nodo y también se
conserva como propiedad id.
Con commit_every=N, los cargadores de Parquet hacen commit cada N
filas; con 0 todo queda pendiente hasta que llamas a commit().
import pyarrow as pa, pyarrow.parquet as pq
ids = [uuid.uuid4() for _ in range(3)]pq.write_table(pa.table({ "node_id": pa.array([u.bytes for u in ids], type=pa.binary(16)), "name": ["a", "b", "c"],}), "nodes.parquet")pq.write_table(pa.table({ "src": pa.array([ids[0].bytes, ids[1].bytes], type=pa.binary(16)), "dst": pa.array([ids[1].bytes, ids[2].bytes], type=pa.binary(16)), "w": [1.0, 2.0],}), "edges.parquet")
db.load_parquet_nodes("Item", "nodes.parquet") # 3db.load_parquet_edges("LINK", "edges.parquet") # 2db.commit()Búsquedas y scans
Estos métodos leen datos confirmados sin Cypher.
| Método | Retorna |
|---|---|
lookup_node(label, id) | Un dict de nodo, o None |
out_edges(edge_type, src), in_edges(edge_type, dst) | Lista de dicts de relaciones |
scan_label(label, limit=None) | Lista de dicts de nodos |
scan_label_arrow(label, limit=None) | pyarrow.Table con id, label, labels, lsn, schema_version y una columna por clave de propiedad |
iter_label(label, limit=None) | Un NodeIter perezoso, 1.024 nodos por paso |
scan_edge_type(edge_type, limit=None) | Lista de dicts de relaciones |
iter_edge_type(edge_type, limit=None) | Un EdgeIter perezoso |
db.lookup_node("Person", alice)# {'id': '…', 'label': 'Person', 'labels': ['Person'], 'lsn': 1,# 'schema_version': 0, 'properties': {'age': 30, 'name': 'Alice'}}
db.out_edges("KNOWS", alice)# [{'edge_type': 'KNOWS', 'src': '…', 'dst': '…', 'lsn': 3,# 'properties': {'since': 2020}}]Un iterador lee cada fila de la versión que estaba vigente cuando se creó, aunque sigan las escrituras y las compactaciones, y mantiene vivos los archivos de esa versión hasta que se descarta. Si un paso lanza una excepción, el iterador termina.
Mantenimiento
| Método | Efecto |
|---|---|
flush() | Escribe la tabla en memoria en archivos de nivel 0; luego compacta si un bucket llegó a compaction_l0_trigger. |
compact() / acompact() | Ejecuta una pasada de compactación. Retorna un dict: applied, l0_before, l0_after, source_ssts_removed, new_ssts_written, bloom_sidecars_written, manifest_version_before, manifest_version_after. |
sweep(min_age_secs=60, dry_run=False) | Borra los objetos sin referencias más antiguos que min_age_secs. Retorna conteos (orphans_deleted, bytes_freed, wal_segments_reclaimed, manifest_snapshots_reclaimed, …, aborted_by_pin). |
refresh() | Clientes de solo lectura: pasa al commit más reciente; True si avanzó. No hace nada (False) en un writer. |
close() | Clientes de solo lectura: libera ahora el lease de retención. El cliente sigue funcionando. |
cache_stats() | (hits, misses, inserts, usage_bytes) de la caché de SST de este cliente. |
load_vault(path, label="Note", edge_type="LINKS_TO", commit_every=1000, prune=False, placeholders=False) | Carga un vault de Markdown (consulta CLI); hace commit antes de retornar y retorna estadísticas de la carga. |
Si aborted_by_pin es True en un reporte de sweep, apareció el lease de
un lector a mitad del sweep y no se borró nada; vuelve a ejecutar el sweep.
Excepciones
| Excepción | Base | Se lanza cuando |
|---|---|---|
namidb.QueryTimeoutError | TimeoutError | Se agotó timeout_ms |
namidb.QueryRowCapError | RuntimeError | Se superó max_rows |
ValueError | — | URI o namespace inválido, error de sintaxis o de planificación de Cypher |
RuntimeError | — | Error de ejecución o de almacenamiento, violación de una restricción |
PermissionError | — | Una llamada que modifica en un cliente read_only=True |
Mapeo de tipos
Los parámetros y los resultados usan el mismo mapeo.
| Cypher | Python |
|---|---|
NULL | None |
BOOLEAN | bool (se comprueba antes que int, así que True nunca se convierte en 1) |
INTEGER | int |
FLOAT | float |
STRING | str |
BYTES | bytes |
LIST, VECTOR | list (pasa list[float] para los vectores) |
MAP | dict[str, …] |
DATE | datetime.date |
DATETIME | datetime.datetime, UTC |
| Nodo | {'_kind': 'node', 'id', 'label', 'labels', 'properties'} |
| Relación | {'_kind': 'rel', 'edge_type', 'src', 'dst', 'properties'} |
| Camino | lista que alterna dicts de nodos y de relaciones |
Concurrencia
- Cada llamada bloqueante libera el GIL.
- Las lecturas se ejecutan sobre el último snapshot confirmado sin el lock
del writer; muchos hilos pueden leer un mismo
Clienta la vez. - Las escrituras se serializan por cliente.
- Un writer por namespace entre procesos: abrir un
Clientcon escritura bloquea (fencing) a cualquier otro writer de ese namespace. Usaread_only=Truepara lectores adicionales.