SDK de Python
namidb-cloud es el cliente oficial de Python. Ejecuta Cypher sobre la
API HTTP y envuelve la
API de gestión. El cliente síncrono usa
solo la librería estándar; el cliente asyncio necesita httpx. Python 3.9+,
Apache-2.0.
pip install namidb-cloud # sync client, no dependenciespip install 'namidb-cloud[async]' # adds AsyncNamiDB (httpx)El paquete para el servicio cloud es namidb-cloud (módulo namidb_cloud). El
motor embebido que ejecutas tú mismo es un paquete distinto, namidb:
consulta Python (self-hosted).
Inicio rápido
from namidb_cloud import NamiDB
db = NamiDB() # reads NAMIDB_API_KEY (and NAMIDB_URL, default https://db.namidb.com)
db.query("movies", "CREATE (:Movie {id: $id, title: $title})", {"id": "m1", "title": "Heat"})
result = db.query("movies", "MATCH (m:Movie) RETURN m.title AS title ORDER BY title LIMIT $n", {"n": 10})for row in result: print(row["title"])
movies = db.database("movies") # bind one databaseschema = movies.schema()Async:
import asynciofrom namidb_cloud import AsyncNamiDB
async def main() -> None: async with AsyncNamiDB() as db: result = await db.query("movies", "MATCH (m:Movie) RETURN m.title AS title LIMIT 5") print(result.rows)
asyncio.run(main())NamiDB(api_key=None, url=None, timeout=90.0, max_retries=2)
| Argumento | Por defecto | |
|---|---|---|
api_key | $NAMIDB_API_KEY | Obligatorio; si falta, lanza missing_api_key |
url | $NAMIDB_URL, y si no https://db.namidb.com | |
timeout | 90.0 | Segundos por operación de socket; cubre el timeout de consulta del plan más largo más un arranque en frío |
max_retries | 2 | Reintentos después del primer intento |
AsyncNamiDB recibe los mismos argumentos más http_client (un
httpx.AsyncClient que gestionas tú). Ambos son context managers (close() /
await aclose()). NamiDB es thread-safe y mantiene una conexión abierta por
hilo.
Métodos
db.query(database, cypher, params=None, *, idempotent=None, timeout=None)
Devuelve un QueryResult:
columns: list[str]rows: list[dict], un dict por fila con el nombre de la columna como clavewrite_outcome: WriteOutcome | None(nodes_created,edges_created,nodes_deleted,edges_deleted,properties_set)request_id: str | None, inclúyelo al hablar con soporteengine_ms: float | None
Iterar un QueryResult devuelve sus filas; len() es la cantidad de filas. Los
valores usan la codificación JSON del motor (nodos como {"_kind": "node", …},
relaciones como {"_kind": "rel", …}, datetimes como strings RFC 3339, bytes
como base64, vectores como listas de floats). params debe ser serializable a
JSON.
db.schema(database)
Un Schema con constraints, indexes, labels, relationship_types y
request_id; cada constraint e índice es un SchemaEntry (name, type,
entity_type, labels_or_types, properties).
db.databases()
list[DatabaseInfo] (name, status) con las bases de datos a las que llega
la key.
db.running_queries(database) y db.cancel_query(database, query_id)
running_queries devuelve las sentencias que se están ejecutando en la base de
datos en este momento, de la más larga a la más corta, como
list[RunningQuery] (id, protocol, statement, elapsed_ms).
cancel_query detiene una en su siguiente punto de verificación, y su cliente
recibe un error cancelled. Ambas necesitan una key de lectura y escritura
(read_only_key si no), porque el texto de las sentencias incluye sus
literales. Cancelar una sentencia que ya no se está ejecutando lanza
query_not_found.
from namidb_cloud import ErrorCode, NamiDBError
for q in db.running_queries("movies"): if q.elapsed_ms > 60_000: try: db.cancel_query("movies", q.id) except NamiDBError as err: if err.code != ErrorCode.QUERY_NOT_FOUND: raiseListar se reintenta como una lectura y nunca despierta una base de datos
dormida (en ese caso no tiene nada en ejecución). Una cancelación se reintenta
solo cuando NamiDB la rechazó antes de que pudiera tener efecto. Ninguna de las
dos cuenta como petición. AsyncNamiDB tiene los mismos dos métodos.
db.database(name)
Un handle con query, schema, running_queries, cancel_query,
bulk_write, import_nodes e import_relationships ligados a esa base de
datos.
Importación masiva
db.import_nodes("movies", people, label="Person", key="id", on_progress=lambda done, total, batches: print(done, total))
res = db.import_relationships( "movies", [{"from": 1, "to": 2, "since": 2020}], rel_type="KNOWS", from_label="Person", from_key="id", to_label="Person", to_key="id",) # res.linked counts rows whose two ends exist
db.bulk_write("movies", "UNWIND $rows AS row MERGE (m:Movie {title: row.title})", titles, idempotent=True)Los lotes se cortan en batch_rows (1,000 por defecto) y batch_bytes (1 MiB
por defecto), esperan ante rate_limited y engine_starting
(max_rate_limit_retries, 30 por defecto) y se dividen ante
payload_too_large. Los lotes con MERGE se reintentan como las lecturas; los
lotes con CREATE nunca se reenvían después de un fallo ambiguo. El cliente
async tiene los mismos métodos.
Errores
Todo fallo lanza NamiDBError: code (constantes en ErrorCode), status (0
cuando no llegó ninguna respuesta), message, request_id, retry_after, y
neo4j_code / gql_status cuando el motor los informó.
from namidb_cloud import ErrorCode, NamiDB, NamiDBError
try: db.query("movies", 'CREATE (:Movie {id: "m1"})')except NamiDBError as err: if err.code == ErrorCode.READ_ONLY_KEY: ... # this key can only read elif err.code == ErrorCode.PLAN_LIMIT: ... # allowance used up: upgrade, or wait err.retry_after seconds else: raiseTodos los códigos: Errores.
Reintentos
Hasta max_retries veces, esperando lo que indique Retry-After cuando el
servidor lo envía (si es más de 60 s, se lanza el error en lugar de esperar), y
si no, con backoff exponencial con jitter de 0.5 s a 8 s.
Las escrituras nunca se reintentan una vez que pudieron haber llegado al
motor. Una consulta cuenta como escritura cuando contiene una cláusula de
escritura (CREATE, MERGE, SET, DELETE, REMOVE, DROP, CALL, …). Las
escrituras sí se reintentan cuando NamiDB las rechazó antes de que el motor las
viera (engine_starting, rate_limited, control_plane_unavailable) o cuando
la petición nunca llegó a salir. Puedes cambiarlo en cada llamada:
db.query("movies", "MERGE (:Movie {id: $id})", {"id": "m1"}, idempotent=True) # safe to repeatdb.query("movies", "MATCH (n) RETURN n", idempotent=False) # never repeatAPI de gestión
ManagementClient usa un token de gestión (nmdb_mgmt_…) contra
https://app.namidb.com/api/v1.
from namidb_cloud import ManagementClient
with ManagementClient() as mgmt: # reads NAMIDB_MANAGEMENT_TOKEN (and NAMIDB_MANAGEMENT_URL) db = mgmt.databases.create("movies") key = mgmt.api_keys.create("movies-app", role="read-only", databases=["movies"]) print(key.token) # the full API key, returned this once
backup = mgmt.backups.create("movies") mgmt.restores.create(backup_id=backup.id, database_name="movies-copy") mgmt.clones.create("movies", name="movies-staging", source="fresh_snapshot") # The database as it was then (exact inside the plan's restore-point window). pit = mgmt.restores.point_in_time("movies", at="2026-11-03T09:00:00Z", database_name="movies-tuesday") # poll mgmt.clones.get(pit.id); pit.recovery_point and pit.recovery_source say what it holds
# A short-lived token for a CI job (admin scope; never broader or longer-lived than this one). ci = mgmt.management_tokens.create("ci", scope="write", expires_at="2026-11-04T00:00:00Z") print(ci.token) # shown this once
exp = mgmt.exports.create("movies") # poll mgmt.exports.get(exp.id) until "succeeded" cypher = mgmt.exports.download(exp.id, "import.cypher")
mgmt.ip_allowlist.add("203.0.113.0/24", label="office") for d in mgmt.databases.iter(): print(d.name, d.status, d.endpoints["http"])| Recurso | Métodos |
|---|---|
mgmt.organization(), mgmt.usage() | La organización del token; el uso de este periodo |
mgmt.databases | list, iter, create(name), get(name), delete(name) |
mgmt.backups | list(database), create(database), get(id) |
mgmt.restores | create(backup_id=, database_name=), point_in_time(database, at=, database_name=) (un clon point_in_time), get(id) |
mgmt.clones | create(database, name=, source=, at=) (latest_backup, fresh_snapshot, point_in_time), get(id) |
mgmt.exports | list(database), create(database), get(id), download(id, file) |
mgmt.ip_allowlist | list(api_key_id=), add(cidr, label=, api_key_id=), remove(id) |
mgmt.api_keys | list, iter, create(name, role=, databases=, expires_at=), get, rotate(id, overlap_days=), revoke(id) |
mgmt.management_tokens | list, iter, create(name, scope=, expires_at=) (el secreto está en token, una sola vez), get(id), revoke(id); scope admin |
mgmt.members | list, iter, remove(user_id) |
mgmt.invitations | list, create(email, role=), revoke(id) |
mgmt.support | list, iter, create(subject, body, category=, severity=, database=), get(number), reply(number, body) |
Argumentos: token, url, timeout (segundos, 30 por defecto), max_retries
(2 por defecto). Los resultados son dataclasses congeladas (ManagedDatabase,
ApiKey, ManagementToken, Backup, Restore, Clone, Export, IpRule,
SupportTicket, Usage, Member, Invitation); el token de una API key o
de un token de gestión se omite de su repr. list devuelve una Page (data, next_cursor); iter recorre
todas las páginas. Los fallos transitorios se reintentan con backoff, y cada
creación envía un Idempotency-Key (uno nuevo, o el idempotency_key= que
pases) que sus reintentos reutilizan.
Changelog
Las notas de versión están en el CHANGELOG.md del paquete en PyPI.