NamiDB se configura con flags de línea de comandos (solo el servidor) y
variables de entorno (todos los puntos de entrada). Cada flag del servidor
tiene una variable de entorno; cuando se definen ambos, gana el flag.
Un número entero exacto de bytes (1073741824). Los sufijos como 1GB se rechazan. Las variables que terminan en _MIB se expresan en mebibytes.
Flag booleano
--no-auth y --multi-tenant aceptan 1/0/true/false/yes/no/on/off como --flag=value o variable de entorno; el flag solo significa true. Los valores inválidos son errores.
Variable on/off
NAMIDB_SST_CACHE, NAMIDB_NODE_CACHE: cualquier valor salvo 0 activa. NAMIDB_ADJACENCY, NAMIDB_FACTORIZE, NAMIDB_WCOJ: solo 1/true/yes/on activa.
Tiempo real por sentencia de lectura (HTTP y Bolt). 0s = sin límite.
--write-timeout
NAMIDB_WRITE_TIMEOUT
60s
Tiempo real por sentencia de escritura. 0s = sin límite.
--query-row-cap
NAMIDB_QUERY_ROW_CAP
1000000
Filas que cualquier operador de lectura puede materializar. 0 = ilimitado.
--http-request-timeout
NAMIDB_HTTP_REQUEST_TIMEOUT
derivado
Tope para la petición completa (408). Sin definir: max(120s, largest budget + 30s). 0s desactiva.
--writer-lock-timeout
NAMIDB_WRITER_LOCK_TIMEOUT
30s
Espera por el lock del writer antes de un 503. 0s = sin límite.
--bolt-tx-timeout
NAMIDB_BOLT_TX_TIMEOUT
30s
Tiempo de inactividad antes de hacer rollback de una transacción Bolt abierta. 0s = nunca.
--bolt-max-message-bytes
NAMIDB_BOLT_MAX_MESSAGE_BYTES
67108864 (64 MiB)
Mensaje Bolt autenticado más grande. Debe ser positivo.
--slow-query-threshold
NAMIDB_SLOW_QUERY_THRESHOLD
1s
Registra en WARN las sentencias que igualan o superan este valor. 0s desactiva.
--memory-max-bytes
NAMIDB_MEMORY_MAX_BYTES
0 (desactivado)
Tope de RSS del proceso: bytes, o auto (90% del límite del cgroup).
--query-memory-max-bytes
NAMIDB_QUERY_MEMORY_MAX_BYTES
auto
Memoria de trabajo de una sentencia en ejecución (413 query_memory_limit si la supera). auto es el 50% de --memory-max-bytes, desactivado cuando ese valor es 0; una cantidad exacta de bytes también funciona sin tope; 0 lo desactiva. Con un tope, las sentencias en ejecución comparten además un pool del 75% de él (503 memory_pressure). Ver Memoria.
Ruta de escritura y mantenimiento
Flag
Variable de entorno
Por defecto
Significado
--flush-interval
NAMIDB_FLUSH_INTERVAL
30s
Temporizador del flush en segundo plano. 0s desactiva.
--memtable-flush-bytes
NAMIDB_MEMTABLE_FLUSH_BYTES
67108864 (64 MiB)
Hace flush cuando la memtable supera este tamaño. 0 desactiva.
--memtable-stall-bytes
NAMIDB_MEMTABLE_STALL_BYTES
268435456 (256 MiB)
Ralentiza los commits por encima de este tamaño de memtable. 0 desactiva.
--group-commit-window
NAMIDB_GROUP_COMMIT_WINDOW
0s
Agrupa escrituras concurrentes en un solo commit (prueba 2ms–5ms).
--compaction-interval
NAMIDB_COMPACTION_INTERVAL
300s
Temporizador de compactación y sweep en segundo plano. 0s desactiva el mantenimiento.
--compaction-l0-trigger
NAMIDB_COMPACTION_L0_TRIGGER
8
Compacta cuando un flush deja esta cantidad de archivos L0 en un bucket. 0 desactiva.
--write-stall-l0
NAMIDB_WRITE_STALL_L0
24
Ralentiza los commits por encima de esta cantidad de archivos L0. 0 desactiva.
--write-stall-delay
NAMIDB_WRITE_STALL_DELAY
50ms
Retraso por commit mientras hay stall por L0.
--sweep-min-age
NAMIDB_SWEEP_MIN_AGE
24h
Antigüedad mínima antes de borrar un objeto sin referencias.
--sweep-delete
NAMIDB_SWEEP_DELETE
true
false = sweep en modo dry-run.
--restore-point-retention
NAMIDB_RESTORE_POINT_RETENTION
0s (desactivado)
Conserva restaurable cada versión confirmada durante este tiempo (24h, 7d) para un backup a un punto en el tiempo (as_of). El almacenamiento crece según lo que el namespace escribe en la ventana. Requiere --compaction-interval mayor que cero; si no, el servidor se niega a arrancar. Ver Puntos de restauración.
--backup-target-uri
NAMIDB_BACKUP_TARGET_URI
desactivado
Habilita los endpoints de backup y restore y restringe sus ubicaciones (allowlist).
Variables solo del servidor
Sin flag; se leen una vez al arrancar.
Variable
Por defecto
Significado
NAMIDB_HTTP_MAX_CONCURRENCY
1024
Peticiones HTTP en curso entre todas las rutas.
NAMIDB_MAX_CONCURRENT_QUERIES
núcleos de CPU, mínimo 4
Sentencias de lectura concurrentes. 0 desactiva el control.
NAMIDB_MAX_CONCURRENT_QUERIES_PER_NAMESPACE
0 (desactivado)
Multi-tenant: lecturas concurrentes por namespace.
NAMIDB_MAX_CONCURRENT_SCANS
4
Sentencias concurrentes cuyo plan contiene un full scan. 0 desactiva.
NAMIDB_QUERY_ADMISSION_WAIT_MS
5000
Cuánto puede esperar una lectura su admisión antes de un 503.
NAMIDB_BOLT_MAX_CONNECTIONS
1024
Conexiones Bolt concurrentes.
NAMIDB_BOLT_MAX_TX_LIFETIME
5m
Vida máxima de una transacción explícita de Bolt.
NAMIDB_BOLT_MEMORY_BUDGET_BYTES
la mitad del tope de memoria; si no, 1075838976
Presupuesto compartido para decodificar mensajes Bolt autenticados.
NAMIDB_BOLT_PARTIAL_MESSAGE_TIMEOUT
120s
Plazo para un mensaje Bolt recibido parcialmente. 0s desactiva.
NAMIDB_BOLT_SERVER_AGENT
Neo4j/5.13.0
Server agent anunciado a los clientes Bolt.
RUST_LOG
info
Filtro de logs, p. ej. info,namidb_storage=debug.
Variables del motor
Las leen el servidor, el cliente de Python, la CLI y el servidor MCP. La
mayoría se leen la primera vez que el motor las necesita, así que defínelas
antes de que arranque el proceso. El servidor valida al arrancar las
variables de caché expresadas en bytes y rechaza los valores mal formados.
Cachés
Variable
Por defecto
Significado
NAMIDB_CACHE_MAX_BYTES
1073741824 (1 GiB)
Tope para todas las cachés compartidas en el proceso. 0 las desactiva.
NAMIDB_SEARCH_INDEX_CACHE_MAX_BYTES
proporcional
Reserva exacta dentro del tope para cuerpos vectoriales / full-text decodificados. 0 desactiva ese pool.
NAMIDB_SST_CACHE
activado
Cachés de cuerpos de archivos de datos y decodificadas (0 = desactivado).
NAMIDB_NODE_CACHE
activado
Caché de vistas de nodos entre consultas (0 = desactivado).
NAMIDB_ADJACENCY
desactivado
Caché de adyacencia (CSR) en RAM; mantiene tipos de relación completos en memoria.
NAMIDB_SNAPSHOT_NODE_CACHE_MAX_BYTES
min(1 MiB, ceiling / 64)
Caché de vistas de nodos por consulta. 0 desactiva.
NAMIDB_SNAPSHOT_ROW_GROUP_CACHE_MAX_BYTES
min(1 MiB, ceiling / 64)
Row groups decodificados por consulta (dos como máximo).
NAMIDB_SNAPSHOT_EDGE_READER_CACHE_MAX_BYTES
min(1 MiB, ceiling / 64)
Metadatos de lectores de relaciones por consulta (32 archivos como máximo).
Espacio temporal en disco para flush y compactación.
NAMIDB_INDEX_BUILD_SPOOL_DIR
spool de compactación, luego NAMIDB_SPOOL_DIR
Espacio temporal en disco para construir índices vectoriales / full-text.
NAMIDB_COMPACTION_SPOOL_DIR
—
Alias que se usa para construir índices cuando NAMIDB_INDEX_BUILD_SPOOL_DIR no está definida.
NAMIDB_INDEX_BUILD_MEMORY_BYTES
256 MiB (reconstrucción completa), 64 MiB (delta por flush)
Memoria del constructor de índices; un valor reemplaza ambos.
NAMIDB_SIDECAR_SORT_MEMORY_BYTES
8388608 (8 MiB, mín. 64 KiB)
Buffer de ordenamiento por constructor de side-car de unicidad / igualdad / label.
NAMIDB_NODE_PROPERTY_SORT_MEMORY_BYTES
8388608 (8 MiB)
Buffer de ordenamiento para páginas de propiedades de nodos.
NAMIDB_FLUSH_BUILD_GATE_TIMEOUT_SECS
600
Cuánto espera un flush el slot de construcción del proceso antes de fallar (y reintentarse).
Búsqueda
Variable
Por defecto
Significado
NAMIDB_SEARCH_WORKSPACE_MAX_BYTES
268435456 (256 MiB)
Memoria transitoria compartida para búsquedas.
NAMIDB_SEARCH_MAX_RESULT_BYTES
67108864 (64 MiB)
Tope para resultados full-text sin límite (sin k).
NAMIDB_BM25_MAX_DOCUMENT_BYTES
1048576 (1 MiB)
Documento más grande en la puntuación BM25 exacta.
NAMIDB_VECTOR_FILTER_ID_CANDIDATE_CAP
8192
Ids de side-car que se usan cuando un índice vectorial no puede aplicar un filtro. 0 desactiva.
NAMIDB_HYBRID_TEXT_FILTER_CANDIDATE_CAP
65536
Candidatos BM25 que se hidratan en una búsqueda híbrida filtrada antes del fallback exacto.
NAMIDB_SEARCH_LSM_MAX_SEGMENTS
8 (2–32)
Segmentos vivos por índice de búsqueda.
NAMIDB_SEARCH_LSM_COMPACT_SEGMENTS
max(MAX − 2, 2)
Deltas consolidados por pasada rutinaria.
NAMIDB_SEARCH_LSM_BASE_COMPACT_BYTES
8589934592 (8 GiB)
Bytes de delta que disparan una reconstrucción de la base.
NAMIDB_SEARCH_LSM_BASE_STALE_PERCENT
800
Mutaciones de delta (% del corpus) que disparan una reconstrucción de la base.
NAMIDB_SEARCH_LSM_FORCE_BASE_COMPACTION
false
Reconstrucción única de la base cuando hay deuda de deltas.
NAMIDB_VECTOR_PAGE_ROWS
512
Vectores por página del índice al construirlo.
NAMIDB_VECTOR_BRANCH_FACTOR
8
Ramificación del árbol de enrutamiento del índice vectorial.
NAMIDB_VECTOR_PAGE_ZSTD_LEVEL
3
Nivel de compresión de las páginas vectoriales.
Los postings de filtro dentro de un índice vectorial tienen un límite fijo
de 4.096 valores distintos por propiedad (no configurable); su construcción
usa el spool de índices con NAMIDB_INDEX_BUILD_MEMORY_BYTES.
Ruta de escritura, compactación y archivos de datos
Variable
Por defecto
Significado
NAMIDB_COMPACTION_BASE_BYTES
8388608 (8 MiB)
Presupuesto de tamaño del nivel 1.
NAMIDB_COMPACTION_LEVEL_RATIO
10 (mín. 2)
Proporción de tamaño entre niveles.
NAMIDB_COMPACTION_MERGE_CHUNK_ROWS
16384
Filas por chunk de salida en el merge de compactación.
NAMIDB_NODE_SST_ROW_GROUP_ROWS
131072
Filas por row group de Parquet en los archivos de datos de nodos.
NAMIDB_MEMTABLE_SNAPSHOT_EVERY
0 (desactivado)
Escribe un snapshot de la memtable cada N commits (acelera el replay del WAL al abrir).
NAMIDB_CORRELATED_WRITE_CHUNK_ROWS
128 (máx. 1024)
Filas por chunk para actualizaciones puntuales UNWIND … MATCH … SET.
NAMIDB_LEGACY_PROPERTY_INDEX_MAX_BYTES
sin definir: se escribe, sin tope
Side-car de propiedades en formato anterior, que se conserva para poder volver a lectores previos a la paginación. 0 deja de escribirlo; un valor positivo lo limita (más allá del tope solo se escribe el formato actual).
NAMIDB_EDGE_POINT_MAX_ENTRY_BYTES
0 (ilimitado)
Tope por registro de relación en el side-car exacto de relaciones; superar un tope positivo hace fallar la construcción.
NAMIDB_EDGE_POINT_MAX_SST_BYTES
0 (ilimitado)
Tope por side-car exacto de relaciones; misma regla.
NAMIDB_EDGE_DECODE_MAX_BYTES
67108864 (64 MiB)
Bloque de adyacencia más grande que se decodifica de una vez en archivos de relaciones antiguos.
NAMIDB_EDGE_IN_MEMORY_FINISH_MAX_BYTES
67108864 (64 MiB)
Tope para APIs auxiliares que construyen un archivo de relaciones en memoria (no lo usan el flush ni la compactación).
NAMIDB_NODE_PROPERTY_PAGE_TARGET_BYTES
1048576 (1 MiB)
Tamaño objetivo de una página de propiedades.
NAMIDB_NODE_PROPERTY_MAX_VALUE_BYTES
67108864 (64 MiB)
Valor de propiedad más grande.
NAMIDB_NODE_PROPERTY_MAX_PAGE_BYTES
68157440 (65 MiB)
Página de propiedades decodificada más grande.
NAMIDB_NODE_PROPERTY_MAX_CATALOG_BYTES
16777216 (16 MiB)
Catálogo de propiedades más grande por archivo.
NAMIDB_NODE_PROPERTY_MAX_PROPERTIES
65536
Nombres de propiedad distintos por archivo.
NAMIDB_NODE_PROPERTY_MAX_VALUE_DEPTH
32
Profundidad de anidamiento de un valor.
NAMIDB_NODE_PROPERTY_MAX_VALUE_ELEMENTS
1000000
Elementos en un valor.
NAMIDB_NODE_PROPERTY_MAX_NAME_BYTES
1024
Longitud de un nombre de propiedad.
NAMIDB_NODE_PROPERTY_MAX_INDEX_QUERY_BYTES
16777216 (16 MiB)
Lectura de sondeo de índice más grande para una consulta de propiedad.
NAMIDB_NODE_PROPERTY_MAX_QUERY_ROWS
1000000
Filas que puede retornar una consulta de índice de propiedades.
Ejecución de consultas
Variable
Por defecto
Significado
NAMIDB_BATCH_LOOKUP_CHUNK
8192
Ids de nodos resueltos por pasada de búsqueda por lotes.
NAMIDB_EXPAND_TARGET_VIEW_BUDGET
250000
Vistas de extremos precargadas por salto de expansión antes de pasar a lecturas por relación.
NAMIDB_NUMERIC_RANGE_MAX_CANDIDATES
65536
Tope de candidatos para rangos numéricos servidos por índice. 0 desactiva esa ruta.
Las credenciales de cada backend usan las variables estándar de su
proveedor (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN,
AWS_DEFAULT_REGION, GOOGLE_APPLICATION_CREDENTIALS,
AZURE_STORAGE_ACCOUNT_NAME, AZURE_STORAGE_ACCOUNT_KEY, …); consulta
URIs de almacenamiento.
Embedders
Los leen namidb load-vault --embed y namidb-mcp. El embedder remoto
requiere una compilación con --features namidb-markdown/remote-embedder;
consulta CLI.
Variable
Por defecto
Significado
NAMIDB_EMBEDDER
local
remote cambia a un proveedor remoto.
NAMIDB_EMBED_PROVIDER
openai
openai, voyage, cohere, gemini, jina.
NAMIDB_EMBED_MODEL
según el proveedor
Nombre del modelo.
NAMIDB_EMBED_DIM
1024
Dimensión de salida.
NAMIDB_EMBED_API_KEY
variable del proveedor
API key; si no está, usa OPENAI_API_KEY, VOYAGE_API_KEY, CO_API_KEY, GEMINI_API_KEY / GOOGLE_API_KEY, JINA_API_KEY.