Saltearse al contenido

Embebido (Python)

El wheel namidb ejecuta el motor completo en tu proceso: sin servidor y sin salto de red. Esta página explica cómo ejecutarlo bien. Para cada método y parámetro, consulta la referencia de la API de Python.

Abrir un namespace

import namidb
db = namidb.Client("file:///var/lib/namidb?ns=prod")

El URI elige el backend y el namespace:

URIÚsalo para
memory://demoTests y demos. Desaparece cuando el proceso termina.
file:///var/lib/namidb?ns=prodUna máquina, durable en disco local.
s3://bucket/prefix?ns=prod&region=us-east-1AWS S3 y servicios compatibles con S3 (R2, MinIO, Tigris…).
gs://bucket?ns=prodGoogle Cloud Storage.
az://account/container?ns=prodAzure Blob Storage.

La gramática completa y el manejo de credenciales están en URIs de almacenamiento.

Abrir un namespace que todavía no existe lo crea. Un Client normal es el writer del namespace: al abrirlo reclama el namespace y bloquea (fencing) a cualquier otro proceso que estuviera escribiendo en él. Para ver un namespace en el que escribe otro proceso, ábrelo en solo lectura.

¿Cuándo son durables los datos?

Hay dos rutas de escritura, con reglas de commit distintas.

Las escrituras Cypher se confirman al retornar. CREATE, MERGE, SET, DELETE, REMOVE y el DDL se agregan al write-ahead log y se confirman con una escritura condicional del manifest antes de que cypher() retorne.

db.cypher("CREATE (:Person {name: 'Ada'})") # durable now

La API de carga masiva acumula hasta commit(). upsert_node, upsert_edge, put_nodes, merge_nodes, merge_edges, tombstone_* y los cargadores de Parquet agregan a un lote pendiente. Nada es durable hasta que llamas a commit().

import uuid
alice, bob = str(uuid.uuid4()), str(uuid.uuid4())
db.put_nodes("Person", [
{"_id": alice, "name": "Alice"},
{"_id": bob, "name": "Bob"},
])
db.merge_edges("KNOWS", [{"src": alice, "dst": bob, "since": 2020}])
db.commit() # WAL append + manifest commit

Los datos confirmados viven en el WAL y en una tabla en memoria hasta que se hace flush a archivos de datos inmutables. Llama a flush() periódicamente y al final de una carga; el cliente embebido no tiene un temporizador de flush en segundo plano.

db.flush()

Espacio en disco: flush, compactación y sweep

En modo embebido no hay mantenimiento en segundo plano, así que el cliente lo hace en línea:

  • flush() también ejecuta una pasada de compactación en cuanto algún bucket contiene compaction_l0_trigger archivos de nivel 0 (por defecto 8). Pasa compaction_l0_trigger=0 para desactivarlo y llamar tú mismo a compact().
  • Después de una compactación que se aplica, el cliente hace sweep: borra los archivos que ya no referencia ninguna versión del manifest (archivos fusionados, segmentos del WAL ya incorporados a archivos de datos, manifests reemplazados), siempre que se hayan escrito hace más de auto_sweep_min_age_secs (por defecto 60). Pasa auto_sweep_min_age_secs=None para desactivar el sweep automático.
  • sweep(min_age_secs=60, dry_run=False) ejecuta el mismo sweep a demanda y retorna lo que eliminó (o eliminaría).
report = db.compact()
print(report["applied"], report["l0_before"], report["l0_after"])
print(db.sweep(min_age_secs=0, dry_run=True))

La compactación escribe archivos temporales mientras fusiona. Para un URI file:// van a <root>/.namidb-spool junto al grafo, salvo que pases spool_dir= o definas NAMIDB_SPOOL_DIR. Los demás backends usan NAMIDB_SPOOL_DIR o, si no está, /var/tmp. Calcula aproximadamente el triple de los bytes compactados en ese volumen durante una pasada grande. El directorio de spool es para todo el proceso: lo decide el último cliente abierto.

db = namidb.Client(
"file:///data/graph?ns=case",
spool_dir="/data/scratch",
compaction_l0_trigger=8,
auto_sweep_min_age_secs=60,
)

Leer desde otro proceso

Un namespace tiene exactamente un writer. Un segundo proceso que solo lee debería abrirlo en solo lectura, lo que nunca reclama el namespace:

reader = namidb.Client("file:///var/lib/namidb?ns=prod", read_only=True)
print(reader.cypher("MATCH (p:Person) RETURN count(p) AS n").rows())
# Pick up whatever the writer committed since:
if reader.refresh():
print("new data")
  • Un lector ve cada commit hasta el momento en que se abrió o se refrescó por última vez, incluidos los commits a los que el writer todavía no les hizo flush (reproduce el WAL sin flush).
  • Se queda en esa versión hasta refresh(), o como máximo una hora: una lectura sobre una versión más antigua refresca primero.
  • Cada llamada que modifica (escrituras, DDL, commit, flush, compact, sweep, cargadores) lanza PermissionError.
  • El namespace ya debe existir.
  • El lector mantiene un pequeño lease de retención en manifest/pins/ para que el sweep del writer no borre archivos que todavía necesita, y lo renueva en segundo plano. close(), o salir de un bloque with, lo libera de inmediato; si no, expira unos 15 minutos después de su última renovación.
with namidb.Client("file:///var/lib/namidb?ns=prod", read_only=True) as r:
print(r.cypher("MATCH (n) RETURN count(n) AS n").first())

Hilos y asyncio

Cada llamada bloqueante libera el GIL. Las lecturas (lecturas con cypher, lookup_node, scan_*, búsquedas de relaciones) se ejecutan sobre el último snapshot confirmado sin esperar el lock del writer, así que varios hilos pueden consultar un mismo Client a la vez y una lectura larga nunca bloquea las escrituras. Las escrituras van de a una.

Para asyncio, usa las corrutinas equivalentes acypher() y acompact(); se ejecutan en el mismo runtime que las llamadas síncronas, así que combinar ambas en un mismo cliente no es problema.

import asyncio
import namidb
async def main():
db = namidb.Client("memory://acme")
await db.acypher("CREATE (:Person {name: 'Alice'})")
result = await db.acypher(
"MATCH (p:Person {name: $name}) RETURN p.name AS name",
params={"name": "Alice"},
)
print(result.rows()) # [{'name': 'Alice'}]
asyncio.run(main())

Limitar una consulta

cypher() y acypher() aceptan los argumentos de solo palabra clave timeout_ms y max_rows:

from namidb import QueryRowCapError, QueryTimeoutError
try:
db.cypher("MATCH (a)-[]->(b) RETURN a, b", timeout_ms=5_000, max_rows=100_000)
except QueryTimeoutError: # subclass of TimeoutError
...
except QueryRowCapError: # subclass of RuntimeError
...

timeout_ms cuenta desde la llamada, incluido el tiempo que una escritura espera el lock del cliente. Una escritura que agota el tiempo se descarta, no se confirma. max_rows hace fallar una lectura en cuanto cualquier paso de su plan produce más filas que ese valor; las escrituras lo ignoran.

Diferencias con el servidor

El cliente embebido comparte el motor con namidb-server, pero algunas funciones del servidor no aplican:

  • No hay temporizadores de flush ni de compactación en segundo plano (ver arriba).
  • No hay gobernador de memoria del proceso (NAMIDB_MEMORY_MAX_BYTES es solo del servidor). Los límites de las cachés compartidas, como NAMIDB_CACHE_MAX_BYTES, sí aplican.
  • No hay autenticación, TLS, endpoint de métricas ni rutas de administración.

Consulta Configuración para ver qué variables de entorno lee el motor embebido.