Saltearse al contenido

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.

Ventana de terminal
pip install namidb-cloud # sync client, no dependencies
pip 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 database
schema = movies.schema()

Async:

import asyncio
from 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)

ArgumentoPor defecto
api_key$NAMIDB_API_KEYObligatorio; si falta, lanza missing_api_key
url$NAMIDB_URL, y si no https://db.namidb.com
timeout90.0Segundos por operación de socket; cubre el timeout de consulta del plan más largo más un arranque en frío
max_retries2Reintentos 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 clave
  • write_outcome: WriteOutcome | None (nodes_created, edges_created, nodes_deleted, edges_deleted, properties_set)
  • request_id: str | None, inclúyelo al hablar con soporte
  • engine_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:
raise

Listar 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:
raise

Todos 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 repeat
db.query("movies", "MATCH (n) RETURN n", idempotent=False) # never repeat

API 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"])
RecursoMétodos
mgmt.organization(), mgmt.usage()La organización del token; el uso de este periodo
mgmt.databaseslist, iter, create(name), get(name), delete(name)
mgmt.backupslist(database), create(database), get(id)
mgmt.restorescreate(backup_id=, database_name=), point_in_time(database, at=, database_name=) (un clon point_in_time), get(id)
mgmt.clonescreate(database, name=, source=, at=) (latest_backup, fresh_snapshot, point_in_time), get(id)
mgmt.exportslist(database), create(database), get(id), download(id, file)
mgmt.ip_allowlistlist(api_key_id=), add(cidr, label=, api_key_id=), remove(id)
mgmt.api_keyslist, iter, create(name, role=, databases=, expires_at=), get, rotate(id, overlap_days=), revoke(id)
mgmt.management_tokenslist, iter, create(name, scope=, expires_at=) (el secreto está en token, una sola vez), get(id), revoke(id); scope admin
mgmt.memberslist, iter, remove(user_id)
mgmt.invitationslist, create(email, role=), revoke(id)
mgmt.supportlist, 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.