Saltearse al contenido

Referencia de la API de Python

Ventana de terminal
pip install namidb # Python >= 3.9; pyarrow >= 14 comes with it
import namidb
print(namidb.__version__) # 3.3.0

El 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ámetroSignificado
uriURI de almacenamiento con el namespace: memory://ns, file:///dir?ns=ns, s3://…, gs://…, az://…. Consulta URIs de almacenamiento.
cache_bytesTamañ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_onlyAbre sin reclamar el namespace; cada método que modifica lanza PermissionError. El namespace debe existir.
spool_dirDirectorio temporal para la compactación. Por defecto NAMIDB_SPOOL_DIR, luego <root>/.namidb-spool para file://, si no /var/tmp.
auto_sweep_min_age_secsDespué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_triggerflush() 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étodoRetorna
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.
  • params es un dict[str, Any]; consulta el mapeo de tipos.
  • timeout_ms limita la llamada completa, incluida la espera por el lock de escritura del cliente; una escritura que agota el tiempo se descarta. Lanza QueryTimeoutError.
  • max_rows hace fallar una lectura en cuanto cualquier paso del plan produce más filas. Lanza QueryRowCapError. Las escrituras lo ignoran.
  • Los errores de sintaxis y de planificación lanzan ValueError; los errores de ejecución lanzan RuntimeError; las escrituras en un cliente de solo lectura lanzan PermissionError.
result = db.cypher(
"MATCH (p:Person) WHERE p.age > $min RETURN p.name AS name, p.age AS age",
params={"min": 26},
)

QueryResult

MiembroRetorna
columnsNombres 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) # 3
r.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étodoEfecto
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") # 3
db.load_parquet_edges("LINK", "edges.parquet") # 2
db.commit()

Búsquedas y scans

Estos métodos leen datos confirmados sin Cypher.

MétodoRetorna
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étodoEfecto
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ónBaseSe lanza cuando
namidb.QueryTimeoutErrorTimeoutErrorSe agotó timeout_ms
namidb.QueryRowCapErrorRuntimeErrorSe 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.

CypherPython
NULLNone
BOOLEANbool (se comprueba antes que int, así que True nunca se convierte en 1)
INTEGERint
FLOATfloat
STRINGstr
BYTESbytes
LIST, VECTORlist (pasa list[float] para los vectores)
MAPdict[str, …]
DATEdatetime.date
DATETIMEdatetime.datetime, UTC
Nodo{'_kind': 'node', 'id', 'label', 'labels', 'properties'}
Relación{'_kind': 'rel', 'edge_type', 'src', 'dst', 'properties'}
Caminolista 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 Client a la vez.
  • Las escrituras se serializan por cliente.
  • Un writer por namespace entre procesos: abrir un Client con escritura bloquea (fencing) a cualquier otro writer de ese namespace. Usa read_only=True para lectores adicionales.