Saltearse al contenido

Bolt (drivers de Neo4j)

namidb-server puede hablar el protocolo Bolt, así que los drivers oficiales de Neo4j (Python, JavaScript, Java, .NET, Go) y las herramientas basadas en Bolt se conectan sin cambios. Bolt y HTTP comparten el mismo namespace, writer, tokens y configuración TLS, así que nunca discrepan.

Habilitarlo

Ventana de terminal
namidb-server --store "file:///var/lib/namidb?ns=prod" \
--auth-token "$NAMIDB_AUTH_TOKEN" \
--bolt-listen 0.0.0.0:7687

(NAMIDB_BOLT_LISTEN es la forma como variable de entorno.) Sin el flag, el servidor es solo HTTP.

Conectarse

from neo4j import GraphDatabase
driver = GraphDatabase.driver(
"bolt://localhost:7687",
auth=("namidb", NAMIDB_AUTH_TOKEN), # any user name; the token is the password
)
with driver.session() as s:
s.run("CREATE (:City {name: 'Lima'})").consume()
for record in s.run("MATCH (c:City) RETURN c.name AS name"):
print(record["name"]) # Lima
driver.close()
  • Usa el esquema bolt:// (o bolt+s:// / bolt+ssc:// con TLS). neo4j:// pide una tabla de enrutamiento, que NamiDB no sirve; los drivers fallan entonces con “Failed to obtain connection towards ‘WRITE’ server”.
  • Autenticación. Basic auth con cualquier nombre de usuario y el token como contraseña, o bearer auth (neo4j.bearer_auth(token)). Ambas resuelven el token exactamente igual que HTTP, incluidos los JWT cuando la feature jwt está habilitada. Un token incorrecto falla con Neo.ClientError.Security.Unauthorized.
  • Versiones del protocolo. Se negocian 5.7, 5.4, 5.0 y 4.4, prefiriendo la más nueva que ofrezca el driver. Desde 5.7, los fallos llevan metadatos GQLSTATUS.
  • Server agent. El servidor se anuncia como Neo4j/5.13.0 porque los drivers oficiales y las GUIs rechazan los servidores que no lo hacen. Cámbialo con NAMIDB_BOLT_SERVER_AGENT, por ejemplo NamiDB/3.3.0 para clientes más permisivos.

Bases de datos

Modosession(database=…)
Single-tenantSe ignora; cada sesión usa el namespace de --store.
Multi-tenantIndica el namespace. Si se omite, se usa --default-namespace. Un token limitado a otros namespaces recibe Neo.ClientError.Security.Forbidden.
with driver.session(database="acme") as s:
s.run("MATCH (i:Item) RETURN i.sku AS sku").value()

Transacciones

El auto-commit (session.run(…)) ejecuta cada sentencia como su propia transacción, igual que HTTP. Los drivers también pueden agrupar sentencias en una transacción explícita:

def add_city(tx, name):
tx.run("CREATE (:City {name: $name})", name=name)
return tx.run("MATCH (c:City) RETURN count(c) AS n").single()["n"]
with driver.session() as s:
total = s.execute_write(add_city, "Quito") # commits on return
names = s.execute_read(
lambda tx: tx.run("MATCH (c:City) RETURN c.name AS n ORDER BY n").value()
)
tx = s.begin_transaction()
tx.run("CREATE (:Draft)")
tx.rollback() # nothing is kept
  • Las sentencias dentro de una transacción ven las escrituras anteriores de la transacción.
  • Las transacciones de escritura mantienen el lock del writer del namespace hasta el COMMIT o el ROLLBACK. Mantenlas cortas. Una transacción inactiva se revierte después de --bolt-tx-timeout (por defecto 30s), y cualquier transacción después de NAMIDB_BOLT_MAX_TX_LIFETIME (por defecto 5m).
  • Las transacciones de lectura (execute_read, o una sesión abierta en modo de acceso de lectura) se ejecutan sobre el snapshot publicado y nunca toman el lock del writer.
  • En modo multi-tenant, una transacción explícita queda fijada a la base de datos indicada cuando empezó.
  • Cada sentencia sigue teniendo el presupuesto --query-timeout / --write-timeout del servidor.

Mapeo de tipos

CypherTipo de Bolt / del driver (se muestra Python)
NULL, BOOLEAN, INTEGER, FLOAT, STRINGNone, bool, int, float, str
LIST, MAPlist, dict
VECTORlista de flotantes
BYTESbytes
DATEneo4j.time.Date
DATETIMEneo4j.time.DateTime sin zona horaria; el valor está en UTC
Nodoneo4j.graph.Node; element_id es el UUID del nodo
Relaciónneo4j.graph.Relationship
Caminoneo4j.graph.Path

Los parámetros se mapean igual en sentido inverso; se aceptan parámetros Date y DateTime del driver.

Errores y reintentos

Los fallos de Bolt usan la misma clasificación que HTTP: el código de Neo4j es la columna neo4j_code de la tabla de errores HTTP. Los drivers oficiales reintentan automáticamente Neo.TransientError.* (presión de recursos, límites de admisión, memory_pressure) y nada más. Los timeouts, los límites de filas y el presupuesto de memoria por consulta (query_memory_limit, como Neo.ClientError.Statement.ResourceLimitExceeded) son ClientError a propósito: volver a ejecutar chocaría otra vez con el mismo presupuesto.

Resultados

RUN retorna los nombres de las columnas; las filas se producen a medida que PULL las pide, así que el fetch size del driver limita lo que se convierte y se envía de una vez. Las sentencias de escritura informan los contadores en el resumen del resultado (result.consume().counters.nodes_created). EXPLAIN … retorna el plan como filas plan.

Un resultado que todavía no se pidió queda en el buffer de la sesión, y la sentencia conserva su presupuesto de memoria de trabajo y su parte del pool compartido hasta que se pide la última fila o el resultado se descarta, se reinicia o se cierra. Consume o cierra los resultados sin demora, o otras consultas pueden recibir un memory_pressure reintentable.

Límites

LímitePor defectoAjuste
Conexiones Bolt concurrentes1024; las conexiones adicionales se cierranNAMIDB_BOLT_MAX_CONNECTIONS
Tamaño de mensaje antes de autenticar64 KiB (fijo)—
Tamaño de mensaje después de autenticar64 MiB--bolt-max-message-bytes
Presupuesto compartido de memoria de decodificaciónla mitad de --memory-max-bytes; si no, cerca de 1 GiBNAMIDB_BOLT_MEMORY_BUDGET_BYTES
Plazo para un mensaje parcial120s desde el primer byteNAMIDB_BOLT_PARTIAL_MESSAGE_TIMEOUT
Handshake10 s—

Los parámetros vectoriales cuestan unos nueve bytes de transmisión por flotante, así que el tope de mensaje por defecto admite lotes de aproximadamente 2.000 embeddings de 1024 dimensiones. Un mensaje demasiado grande falla con Neo.ClientError.Request.Invalid y la conexión se cierra; divide los conjuntos grandes de parámetros en lotes. Los mensajes de control pequeños (PULL, DISCARD, COMMIT, ROLLBACK, RESET, GOODBYE, LOGOFF) siempre se admiten para que los clientes puedan vaciar resultados y recuperarse bajo presión de memoria.

Herramientas

Los clientes Bolt que usan los drivers oficiales generalmente funcionan para consultar y para explorar el esquema: NamiDB responde las llamadas de introspección que hacen las GUIs (CALL db.labels(), db.relationshipTypes(), db.propertyKeys(), db.schema.visualization(), SHOW INDEXES, SHOW CONSTRAINTS). Las funciones de administración de Neo4j (usuarios, procedimientos dbms.*, APOC) no están disponibles.

Rotación de tokens

HTTP y Bolt multi-tenant toman un archivo de tokens recargado en la siguiente petición o sentencia. Una sesión Bolt single-tenant conserva la identidad con la que se autenticó, así que revocar un token no termina las sesiones activas; reinicia el servidor o cierra las conexiones si una revocación debe aplicarse de inmediato.