Saltearse al contenido

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 overhead

El 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=0

Las 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):

ValorSignificado
0 (por defecto)Desactivado
Una cantidad de bytesEse tope
auto90% 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_pressure reintentable (Bolt: Neo.TransientError.General.DatabaseUnavailable), y /v0/health informa memory_pressure: true, hasta que la memoria baje;
  • POST /v0/admin/flush y 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.

ValorSignificado
auto (por defecto)50% de --memory-max-bytes; desactivado cuando ese tope es 0
Una cantidad de bytesEse presupuesto para cada consulta, con o sin tope
0Desactivado

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-cap no 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=271790898

Lo que ven los clientes

Se detiene porqueHTTPcodeBoltgql_statusReintento
La consulta necesita más que su propio presupuesto413query_memory_limitNeo.ClientError.Statement.ResourceLimitExceeded54000No: vuelve a fallar igual
El pool compartido está lleno, o el proceso llegó a su tope503memory_pressureNeo.TransientError.General.DatabaseUnavailable53000Sí, 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 auto salvo que tengas un motivo. Sigue al tope: con NAMIDB_MEMORY_MAX_BYTES=auto bajo docker 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 … LIMIT o 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 con collect().
  • 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_pressure reintentable 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 un namidb_query::QueryMemoryBudget con with_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:

VariablePor defectoSignificado
NAMIDB_RAM_PAGE_CACHE_MAX_BYTES64 MiB solicitados, escalados junto con los otros nivelesCaché de páginas en RAM, reservada dentro de NAMIDB_CACHE_MAX_BYTES (nunca se suma a él); 0 la desactiva
NAMIDB_NVME_CACHE_PATHsin definirDirectorio para un nivel de caché local persistente. Requiere las dos variables siguientes.
NAMIDB_NVME_CACHE_MAX_BYTESsin definirCapacidad exacta del nivel NVMe (nunca un porcentaje del disco)
NAMIDB_RANGE_CACHE_NAMESPACEobligatoria con NVMeUn 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_BYTES256 KiBTamaño de página de lectura y de caché
NAMIDB_RANGE_CACHE_MAX_ENTRY_BYTES4 MiBRango más grande que se admite
NAMIDB_NVME_CACHE_BLOCK_BYTES16 MiBUnidad de desalojo NVMe (el dispositivo debe contener al menos ocho)
NAMIDB_NVME_CACHE_WRITE_BUFFER_BYTES¼ del nivel RAM, como máximo 16 MiBCada 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

VariablePor defectoSignificado
NAMIDB_SEARCH_WORKSPACE_MAX_BYTES256 MiBPool 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_BYTESparte proporcionalReserva exacta dentro del tope de cachés para cuerpos decodificados de índices vectoriales / full-text en formatos anteriores (monolíticos).
NAMIDB_SEARCH_MAX_RESULT_BYTES64 MiBTope para resultados full-text sin límite (sin k); superarlo es un 413 search_result_limit.
NAMIDB_BM25_MAX_DOCUMENT_BYTES1 MiBDocumento 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:

VariablePor defectoSignificado
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_DIRel spool de compactación, luego NAMIDB_SPOOL_DIRSpool para construir índices vectoriales / full-text
NAMIDB_INDEX_BUILD_MEMORY_BYTES256 MiB para reconstrucciones completas, 64 MiB para deltas por flushPresupuesto en memoria de los constructores de índices (un valor explícito reemplaza ambos)
NAMIDB_SIDECAR_SORT_MEMORY_BYTES8 MiBBuffer 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

Ventana de terminal
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

Ventana de terminal
NAMIDB_CACHE_MAX_BYTES=4294967296 # 4 GiB of shared caches
NAMIDB_RAM_PAGE_CACHE_MAX_BYTES=1073741824 # 1 GiB of it for range pages
NAMIDB_NVME_CACHE_PATH=/mnt/nvme/namidb-cache
NAMIDB_NVME_CACHE_MAX_BYTES=107374182400 # 100 GiB persistent cache
NAMIDB_RANGE_CACHE_NAMESPACE=prod-graphs-us-east-1
NAMIDB_SEARCH_WORKSPACE_MAX_BYTES=1073741824
NAMIDB_SPOOL_DIR=/mnt/nvme/namidb-spool

Un sidecar pequeño con poca memoria

Ventana de terminal
NAMIDB_CACHE_MAX_BYTES=134217728 # 128 MiB
NAMIDB_SEARCH_WORKSPACE_MAX_BYTES=67108864
NAMIDB_MEMORY_MAX_BYTES=auto # with a container memory limit