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://demo | Tests y demos. Desaparece cuando el proceso termina. |
file:///var/lib/namidb?ns=prod | Una máquina, durable en disco local. |
s3://bucket/prefix?ns=prod®ion=us-east-1 | AWS S3 y servicios compatibles con S3 (R2, MinIO, Tigris…). |
gs://bucket?ns=prod | Google Cloud Storage. |
az://account/container?ns=prod | Azure 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 nowLa 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 commitLos 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 contienecompaction_l0_triggerarchivos de nivel 0 (por defecto8). Pasacompaction_l0_trigger=0para desactivarlo y llamar tú mismo acompact().- 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 defecto60). Pasaauto_sweep_min_age_secs=Nonepara 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) lanzaPermissionError. - 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 bloquewith, 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 asyncioimport 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_BYTESes solo del servidor). Los límites de las cachés compartidas, comoNAMIDB_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.