Memoria, cachés y disco
NamiDB lee archivos inmutables del store y mantiene cachés acotadas delante de ellos. Los valores por defecto sirven para cargas de grafos habituales; dimensiona explícitamente para corpus vectoriales o full-text grandes y para máquinas compartidas.
La memoria que usa un proceso de servidor es, aproximadamente:
caches (≤ NAMIDB_CACHE_MAX_BYTES)+ memtables (≤ --memtable-stall-bytes per active namespace, softly)+ active queries and result rows (≤ the shared query pool, when a ceiling is set)+ transient flush / compaction / index-build work+ Bolt message buffers (≤ NAMIDB_BOLT_MEMORY_BUDGET_BYTES)+ allocator and runtime overheadEl tope de cachés
NAMIDB_CACHE_MAX_BYTES (por defecto 1073741824, 1 GiB) es un único tope
para todo el proceso que abarca cada caché compartida: cuerpos de
archivos de datos, row groups decodificados, side-cars de propiedades,
vistas de nodos, lectores de relaciones, bloom filters, cuerpos de índices
de búsqueda, metadatos de archivos y la caché de rangos en RAM. Lo
comparten todos los namespaces, así que un servidor multi-tenant no lo
multiplica por tenant. 0 desactiva las cachés compartidas. Los valores son
bytes exactos; un valor mal formado detiene el servidor al arrancar en
lugar de usar un valor de respaldo en silencio.
El tope se reparte automáticamente entre los niveles. Las variables
anteriores por nivel (NAMIDB_SST_CACHE_BUDGET_MIB,
NAMIDB_NODE_CACHE_BUDGET_MIB, … listadas en la
referencia de configuración) siguen
funcionando como solicitudes relativas; cuando suman más que el tope, se
reducen proporcionalmente.
El log de arranque muestra el resultado:
INFO namidb_storage::cache_budget: resolved process-wide cache capacities cache_max_bytes=1073741824 cache_assigned_bytes=1073741824 sst_cache_bytes=960716369 search_index_cache_bytes=361681456 cache_path_registry_bytes=11302545 range_page_cache_bytes=22605091 node_cache_bytes=90420364 adjacency_cache_bytes=0Las cachés por consulta son aparte y pequeñas: cada snapshot activo
mantiene como máximo NAMIDB_SNAPSHOT_NODE_CACHE_MAX_BYTES,
NAMIDB_SNAPSHOT_ROW_GROUP_CACHE_MAX_BYTES y
NAMIDB_SNAPSHOT_EDGE_READER_CACHE_MAX_BYTES (cada una
min(1 MiB, cache ceiling / 64) por defecto).
La caché opcional de adyacencia (CSR) en RAM está desactivada por
defecto porque mantiene en memoria todas las relaciones de un tipo.
Habilítala con NAMIDB_ADJACENCY=1 solo cuando hayas dimensionado la
memoria para ella; entonces toma una parte del tope.
El gobernador de memoria (servidor)
--memory-max-bytes / NAMIDB_MEMORY_MAX_BYTES define un tope sobre la
memoria residente de todo el proceso (RSS en Linux y macOS, working set en
Windows):
| Valor | Significado |
|---|---|
0 (por defecto) | Desactivado |
| Una cantidad de bytes | Ese tope |
auto | 90% del límite de memoria del cgroup del contenedor; el servidor se niega a arrancar si no hay un límite finito |
Cuando está definido:
- al 90% del tope el servidor vacía las cachés reconstruibles (un watchdog de 500 ms lo hace incluso en reposo);
- al llegar al tope, se rechaza el trabajo Cypher nuevo con un 503
memory_pressurereintentable (Bolt:Neo.TransientError.General.DatabaseUnavailable), y/v0/healthinformamemory_pressure: true, hasta que la memoria baje; POST /v0/admin/flushy los mensajes de control pequeños de Bolt siguen disponibles para que los operadores y los clientes puedan aliviar la presión.
La admisión se comprueba cuando una sentencia empieza. Una sentencia que ya
está en ejecución queda acotada por el
presupuesto por consulta
que se describe abajo, y que el mismo tope activa. Ninguno de los dos
reemplaza un límite del sistema operativo: el flush, la compactación y otro
trabajo en segundo plano todavía pueden hacer crecer la memoria por un rato.
Combina el tope con un límite de contenedor o de cgroup, por ejemplo NAMIDB_MEMORY_MAX_BYTES=auto con
docker run --memory=4g, o NAMIDB_MEMORY_MAX_BYTES=3758096384 (3,5 GiB)
bajo un límite de 4 GiB. Es solo del servidor; los clientes embebidos no lo
instalan.
El presupuesto de memoria por consulta (servidor)
Desde 3.2.1, cada sentencia en ejecución (HTTP y Bolt, lecturas y escrituras)
tiene un presupuesto de memoria de trabajo, definido por
--query-memory-max-bytes / NAMIDB_QUERY_MEMORY_MAX_BYTES. Una consulta que
lo supera falla con un error tipado y el servidor sigue atendiendo todo lo
demás, en lugar de crecer hasta que el kernel mata el proceso y, con él, cada
petición en curso.
| Valor | Significado |
|---|---|
auto (por defecto) | 50% de --memory-max-bytes; desactivado cuando ese tope es 0 |
| Una cantidad de bytes | Ese presupuesto para cada consulta, con o sin tope |
0 | Desactivado |
Por lo tanto, un servidor que nunca definió NAMIDB_MEMORY_MAX_BYTES se
comporta como antes, y uno que sí lo definió obtiene el presupuesto al
actualizar a 3.2.1.
Qué se contabiliza. El ejecutor contabiliza las filas que materializa cada
operador, más el estado que puede crecer mientras un operador se ejecuta: las
listas de UNWIND, las expansiones y los recorridos de longitud variable, las
proyecciones, los joins y los productos cruzados, las agrupaciones y
collect(), DISTINCT, las claves de ordenamiento y las listas de range().
Lo hace en el ejecutor por defecto y en el factorizado (NAMIDB_FACTORIZE=1).
Las estimaciones son conservadoras: cuentan el heap que las filas ocupan de
verdad, incluida la sobrecarga del asignador, y se equivocan hacia arriba.
Además:
- También se contabilizan las copias del resultado en la respuesta HTTP (el árbol JSON y su texto). En una escritura se contabilizan antes del commit, así que una escritura cuya respuesta no cabría se revierte y no confirma nada.
- Un resultado de Bolt queda en el buffer de la sesión hasta que el cliente lo pide, y la sentencia conserva su presupuesto hasta que se pide la última fila o el resultado se descarta, se reinicia o se cierra.
--query-row-capno cambia y se sigue aplicando por su cuenta: la consulta se detiene en el primer límite que alcance.
El pool compartido. Con un tope de memoria, todas las consultas en ejecución reservan además de un único pool del 75% del tope, así que muchas consultas que caben cada una en su presupuesto no pueden sumar más que eso. Una consulta que se ejecuta sola siempre obtiene su presupuesto completo, y un valor por consulta mayor que el pool se recorta al pool. Una consulta que crece también vuelve a medir la memoria residente del proceso cada 16 MiB, y se detiene si el proceso completo llegó a su tope, sin importar qué lo llenó. Con un presupuesto exacto y sin tope no hay pool ni nuevas mediciones, solo el presupuesto por consulta.
El log de arranque muestra los valores resueltos. En un contenedor de 384 MiB
con NAMIDB_MEMORY_MAX_BYTES=auto (un tope de 362.387.865 bytes):
INFO namidb_server: per-query working-memory budget enabled query_memory_max_bytes=181193932 query_memory_pool_bytes=271790898Lo que ven los clientes
| Se detiene porque | HTTP | code | Bolt | gql_status | Reintento |
|---|---|---|---|---|---|
| La consulta necesita más que su propio presupuesto | 413 | query_memory_limit | Neo.ClientError.Statement.ResourceLimitExceeded | 54000 | No: vuelve a fallar igual |
| El pool compartido está lleno, o el proceso llegó a su tope | 503 | memory_pressure | Neo.TransientError.General.DatabaseUnavailable | 53000 | Sí, con backoff |
Un UNWIND de 600.000 filas en ese contenedor de 384 MiB (la misma consulta
con 100.000 filas retorna con normalidad):
{"code":"query_memory_limit","error":"read execution failed: query exceeded its working-memory budget: it needs at least 181600304 bytes, the per-query limit (NAMIDB_QUERY_MEMORY_MAX_BYTES) is 181193932 bytes; return fewer or narrower rows (LIMIT, pagination, aggregation)","gql_status":"54000","neo4j_code":"Neo.ClientError.Statement.ResourceLimitExceeded"}Varias consultas grandes a la vez que, juntas, llenan el pool:
{"code":"memory_pressure","error":"read execution failed: query working memory unavailable: it needs 259293232 bytes but concurrent queries hold the shared query-memory pool of 805306368 bytes; retry after other queries finish","gql_status":"53000","neo4j_code":"Neo.TransientError.General.DatabaseUnavailable"}El servidor sigue respondiendo después de cualquiera de los dos errores, y una
conexión Bolt sigue siendo utilizable después del fallo. Los drivers oficiales
de Neo4j reintentan por su cuenta el TransientError del 503 y no reintentan
el 413. Una sentencia rechazada en la admisión, porque el tope ya se había
alcanzado cuando llegó, también es un 503 memory_pressure; desde 3.2.1 su
cuerpo lleva code, neo4j_code y gql_status como cualquier otro error del
ejecutor.
Cómo dimensionarlo
- Mantén
autosalvo que tengas un motivo. Sigue al tope: conNAMIDB_MEMORY_MAX_BYTES=autobajodocker run --memory=4g, el tope es de unos 3,6 GiB, una consulta puede usar unos 1,8 GiB y todas las consultas en ejecución juntas unos 2,7 GiB. - Bájalo (una cantidad exacta de bytes) cuando importan más muchas consultas concurrentes que una muy grande: un presupuesto más chico detiene antes a una consulta descontrolada y deja más pool para las demás.
- Súbelo solo hasta el pool (75% del tope); un valor mayor se recorta. Dar más memoria a las consultas significa subir el tope y el límite del contenedor a la vez.
- Corrige la consulta antes de subir el presupuesto. Una consulta que
recibe el 413 lo recibe en cada ejecución. Pagínala con
ORDER BY … SKIP … LIMITo con un rango de claves, retorna menos columnas o columnas más angostas, y agrega en la consulta (count(*),sum()) en lugar de retornar filas crudas o juntarlas concollect(). - Desactívalo con
NAMIDB_QUERY_MEMORY_MAX_BYTES=0. La admisión en el tope se mantiene; una consulta en ejecución puede entonces crecer hasta que el límite del sistema operativo la detenga.
Vigila namidb_query_memory_stops_total{reason} y
namidb_query_memory_pool_bytes{kind="peak"} frente a {kind="capacity"}
(Monitoreo).
Detenciones pool frecuentes significan que las consultas grandes
concurrentes no caben juntas; las detenciones process significan que otra
cosa (cachés, memtables, trabajo en segundo plano) está tomando la memoria.
Limitaciones conocidas
- Las estimaciones son por operador, no exactas. Una expansión factorizada se mide por las filas que empuja, no por su contabilidad interna por camino; la comprobación al terminar el operador cubre el resto.
- Un cliente Bolt que deja sin pedir un resultado grande conserva su parte del
pool hasta que lo pide, lo descarta, reinicia la sesión o se desconecta. Es
la memoria que de verdad ocupan las filas en el buffer, pero un cliente
inactivo puede hacer que otras consultas reciban el
memory_pressurereintentable mientras tanto. Consume o cierra los resultados sin demora. - El presupuesto pertenece a
namidb-server. Los clientes embebidos de Python y Rust y la CLI no instalan ninguno; quien llama desde Rust puede acotar unnamidb_query::QueryMemoryBudgetconwith_query_memory.
Caché de rangos
Las lecturas de índices, propiedades y adyacencias obtienen rangos de bytes pequeños y alineados de archivos inmutables y los guardan en caché como páginas:
| Variable | Por defecto | Significado |
|---|---|---|
NAMIDB_RAM_PAGE_CACHE_MAX_BYTES | 64 MiB solicitados, escalados junto con los otros niveles | Caché de páginas en RAM, reservada dentro de NAMIDB_CACHE_MAX_BYTES (nunca se suma a él); 0 la desactiva |
NAMIDB_NVME_CACHE_PATH | sin definir | Directorio para un nivel de caché local persistente. Requiere las dos variables siguientes. |
NAMIDB_NVME_CACHE_MAX_BYTES | sin definir | Capacidad exacta del nivel NVMe (nunca un porcentaje del disco) |
NAMIDB_RANGE_CACHE_NAMESPACE | obligatoria con NVMe | Un nombre estable y no secreto para este despliegue y este bucket, que se mezcla en cada clave de caché para que un directorio de caché reutilizado nunca sirva datos de otro bucket |
NAMIDB_RANGE_CACHE_PAGE_BYTES | 256 KiB | Tamaño de página de lectura y de caché |
NAMIDB_RANGE_CACHE_MAX_ENTRY_BYTES | 4 MiB | Rango más grande que se admite |
NAMIDB_NVME_CACHE_BLOCK_BYTES | 16 MiB | Unidad de desalojo NVMe (el dispositivo debe contener al menos ocho) |
NAMIDB_NVME_CACHE_WRITE_BUFFER_BYTES | ¼ del nivel RAM, como máximo 16 MiB | Cada uno de los dos buffers de escritura NVMe |
El directorio NVMe es exclusivo de un proceso y es solo una caché; bórralo cuando quieras y las lecturas empezarán en frío. Apúntalo a un disco local rápido.
Memoria de búsqueda
| Variable | Por defecto | Significado |
|---|---|---|
NAMIDB_SEARCH_WORKSPACE_MAX_BYTES | 256 MiB | Pool compartido de memoria transitoria de búsqueda (páginas decodificadas, heaps de candidatos). Las consultas esperan a que haya espacio; una que nunca puede caber falla con 503 search_workspace_capacity. |
NAMIDB_SEARCH_INDEX_CACHE_MAX_BYTES | parte proporcional | Reserva exacta dentro del tope de cachés para cuerpos decodificados de índices vectoriales / full-text en formatos anteriores (monolíticos). |
NAMIDB_SEARCH_MAX_RESULT_BYTES | 64 MiB | Tope para resultados full-text sin límite (sin k); superarlo es un 413 search_result_limit. |
NAMIDB_BM25_MAX_DOCUMENT_BYTES | 1 MiB | Documento más grande que puntúa la ruta BM25 exacta (413 search_document_limit por encima). |
Los formatos vectoriales y full-text actuales no cargan el corpus en RAM:
mantienen metadatos de enrutamiento acotados y leen páginas a través de la
caché de rangos. Por eso un namespace de diez millones de vectores no
necesita una caché de diez millones de vectores; los ajustes más pequeños
cambian latencia en caliente por más lecturas de rangos, no exactitud. Si
un índice válido de un formato anterior no cabe en su pool, la consulta
falla con un 503 reintentable search_index_cache_capacity en lugar de
escanear el corpus en silencio.
Buffers de Bolt
NAMIDB_BOLT_MEMORY_BUDGET_BYTES limita la memoria que usan los mensajes
Bolt autenticados entre todas las conexiones (por defecto: la mitad del
tope de memoria, o cerca de 1 GiB sin tope). Un mensaje que no se puede
admitir falla de forma reintentable; usa lotes más pequeños. Consulta los
límites de Bolt.
Spool en disco
El flush y la compactación pasan datos intermedios grandes (salidas Parquet, valores de registros exactos, entradas de compactación remotas, ejecuciones de construcción de índices) por archivos temporales en lugar de RAM:
| Variable | Por defecto | Significado |
|---|---|---|
NAMIDB_SPOOL_DIR | /var/tmp (binario solo en Unix), /var/tmp/namidb-spool (imagen oficial), <root>/.namidb-spool (Python con file://) | Spool para el flush y la compactación |
NAMIDB_INDEX_BUILD_SPOOL_DIR | el spool de compactación, luego NAMIDB_SPOOL_DIR | Spool para construir índices vectoriales / full-text |
NAMIDB_INDEX_BUILD_MEMORY_BYTES | 256 MiB para reconstrucciones completas, 64 MiB para deltas por flush | Presupuesto en memoria de los constructores de índices (un valor explícito reemplaza ambos) |
NAMIDB_SIDECAR_SORT_MEMORY_BYTES | 8 MiB | Buffer de ordenamiento por constructor de side-car de índice |
Dimensiona el spool para una compactación completa: unas tres veces los
datos de nodos vivos compactados (aproximadamente de 12 a 15 GiB por cada
millón de vectores de 1024 dimensiones), más margen. Usa un disco real,
nunca un /tmp respaldado por RAM ni un tmpfs. Los archivos de spool se
eliminan automáticamente al terminar bien, al fallar y al salir.
Recetas
Un contenedor de 4 GiB
docker run --memory=4g \ -e NAMIDB_MEMORY_MAX_BYTES=auto \ -e NAMIDB_CACHE_MAX_BYTES=1073741824 \ -v namidb-spool:/var/tmp/namidb-spool \ …Un corpus vectorial grande en un object store
NAMIDB_CACHE_MAX_BYTES=4294967296 # 4 GiB of shared cachesNAMIDB_RAM_PAGE_CACHE_MAX_BYTES=1073741824 # 1 GiB of it for range pagesNAMIDB_NVME_CACHE_PATH=/mnt/nvme/namidb-cacheNAMIDB_NVME_CACHE_MAX_BYTES=107374182400 # 100 GiB persistent cacheNAMIDB_RANGE_CACHE_NAMESPACE=prod-graphs-us-east-1NAMIDB_SEARCH_WORKSPACE_MAX_BYTES=1073741824NAMIDB_SPOOL_DIR=/mnt/nvme/namidb-spoolUn sidecar pequeño con poca memoria
NAMIDB_CACHE_MAX_BYTES=134217728 # 128 MiBNAMIDB_SEARCH_WORKSPACE_MAX_BYTES=67108864NAMIDB_MEMORY_MAX_BYTES=auto # with a container memory limit