Flush, compactación y sweep
La ruta de escritura
- Commit. Una escritura se agrega al write-ahead log (WAL) y se publica con una escritura condicional del puntero del manifest. Una vez que la llamada retorna, la escritura es durable.
- Tabla en memoria. Los datos confirmados también están en una tabla en memoria (la memtable) que consultan las lecturas.
- Flush. La memtable se escribe como archivos de datos inmutables de nivel 0 (L0) más side-cars (índices, filtros, búsquedas exactas de registros). Los segmentos del WAL que cubría pasan a ser recuperables.
- Compactación. Los archivos L0 se fusionan en archivos más grandes y sin solapamiento en niveles más profundos, y los cuerpos de los índices vectoriales y full-text se reconstruyen o se extienden. Menos archivos y más grandes significan menos lecturas por consulta.
- Sweep. Los objetos que ya no referencia ninguna versión viva del manifest (archivos fusionados, segmentos del WAL retirados, versiones viejas del manifest) se borran cuando tienen suficiente antigüedad.
El servidor ejecuta los pasos 3 a 5 en segundo plano. El cliente de Python
embebido los ejecuta en línea desde flush(); consulta
Embebido (Python).
Flush
| Ajuste | Por defecto | Efecto |
|---|---|---|
--flush-interval | 30s | Flush por temporizador. 0s desactiva el temporizador. |
--memtable-flush-bytes | 64 MiB | Flush en cuanto un commit lleva la memtable por encima de este tamaño. 0 desactiva. |
--memtable-stall-bytes | 256 MiB | Por encima de este tamaño, los commits se ralentizan hasta que el flush se pone al día (backpressure frente a los cargadores masivos). 0 desactiva. |
Flush a demanda:
curl -s -X POST localhost:8080/v0/admin/flush -H "Authorization: Bearer $ADMIN_TOKEN"# {"ssts_written":1,"bloom_sidecars_written":0,"manifest_version":2}El flush administrativo se serializa en todo el proceso, ignora el timeout de la petición HTTP, termina aunque el cliente se desconecte y sigue disponible cuando el tope de memoria está rechazando consultas nuevas, así que también sirve como válvula de alivio de presión.
Compactación
| Ajuste | Por defecto | Efecto |
|---|---|---|
--compaction-interval | 300s | Temporizador de compactación y sweep en segundo plano. 0s desactiva todo el mantenimiento en segundo plano. |
--compaction-l0-trigger | 8 | Compacta en cuanto un flush deja un bucket con esta cantidad de archivos L0. 0 desactiva el disparador reactivo. |
--write-stall-l0 | 24 | Por encima de esta cantidad de archivos L0 en un bucket, cada commit se retrasa --write-stall-delay para que los writers no superen a la compactación. 0 desactiva. |
--write-stall-delay | 50ms | El retraso que se aplica durante el stall. |
NAMIDB_COMPACTION_BASE_BYTES | 8 MiB | Presupuesto de tamaño del nivel 1; los niveles más profundos crecen según la proporción siguiente. |
NAMIDB_COMPACTION_LEVEL_RATIO | 10 | Proporción de tamaño entre niveles (mínimo 2). |
La compactación en segundo plano es incremental: un bucket por ciclo, lo que es adecuado en régimen estable. Después de una carga masiva, vacía L0 explícitamente; si no, la siguiente carga vuelve a leer una pila alta de L0 y se ejecuta mucho más lento:
curl -s -X POST localhost:8080/v0/admin/compact -H "Authorization: Bearer $ADMIN_TOKEN"# {"passes":1,"l0_before":5,"l0_after":0,"source_ssts_removed":5,"new_ssts_written":1,# "manifest_version":11,"truncated":false}Bloquea hasta que el vaciado se completa (puede tardar minutos con un
backlog grande e ignora el timeout de la petición HTTP), comparte un único
permiso para todo el proceso (un segundo llamador recibe 503) y necesita un
token de lectura y escritura. truncated: true significa que se detuvo en
su límite de 128 pasadas; vuelve a llamarlo. En modo multi-tenant usa
/:namespace/v0/admin/compact.
La compactación prepara su trabajo sin tener el lock del writer, así que las lecturas y las escrituras continúan mientras se ejecuta; solo toma el lock brevemente para instalar el resultado.
Segmentos de los índices de búsqueda
Los índices vectoriales y full-text se mantienen como una base más segmentos delta: cada flush agrega como máximo un delta, y la compactación los consolida.
| Variable | Por defecto | Efecto |
|---|---|---|
NAMIDB_SEARCH_LSM_MAX_SEGMENTS | 8 (2–32) | Segmentos vivos por índice. Un flush que necesita otro delta espera a la compactación. |
NAMIDB_SEARCH_LSM_COMPACT_SEGMENTS | max(MAX − 2, 2) | Deltas fusionados en una pasada rutinaria. |
NAMIDB_SEARCH_LSM_BASE_COMPACT_BYTES | 8 GiB | Reconstruye la base cuando los bytes de delta acumulados llegan a este valor. |
NAMIDB_SEARCH_LSM_BASE_STALE_PERCENT | 800 | Reconstruye la base cuando las mutaciones de delta llegan a este porcentaje del corpus vivo. |
NAMIDB_SEARCH_LSM_FORCE_BASE_COMPACTION | false | Una sola vez: reconstruye la base si hay alguna deuda de deltas. |
Sweep
| Ajuste | Por defecto | Efecto |
|---|---|---|
--sweep-min-age | 24h | Solo borra objetos sin referencias con al menos esta antigüedad. |
--sweep-delete | true | false convierte el sweep en un dry run que solo registra lo que liberaría. |
Los lectores están protegidos con exactitud: no se borra nada que todavía necesite un lector vivo, el lease de un backup, el lease de un cliente de solo lectura o la ventana de puntos de restauración. La ventana de antigüedad es una segunda protección para un objeto subido justo antes de que se completara su commit; bájala solo si entiendes esa carrera en tu object store.
Por cada commit se escriben un cuerpo de manifest inmutable y un puntero,
así que una carga larga acumula cientos de versiones pequeñas. Es historial
temporal normal, que el sweep recupera cuando supera --sweep-min-age
(siempre que el mantenimiento esté habilitado y --sweep-delete sea true).
Con --restore-point-retention el sweep conserva ese historial a propósito
durante la ventana de retención, para que se pueda hacer backup de
cualquier instante dentro de ella; ver
Puntos de restauración.
Rutinas recomendadas
| Situación | Haz |
|---|---|
| Tráfico estable | Nada; los valores por defecto dan abasto. |
| Carga masiva por Cypher o Bolt | Agrupa con UNWIND $rows, sube o quita --write-timeout para la carga, y luego POST /v0/admin/compact. |
| Carga masiva desde Python | put_nodes / merge_edges / load_parquet_*, commit(), flush(), compact(), y luego sweep(). |
| El disco se llena en el spool | Dale más espacio a NAMIDB_SPOOL_DIR; consulta Memoria y cachés. |
| Ejecutas la compactación en otro lugar | Define --compaction-interval 0s y programa admin/compact por tu cuenta. Sin mantenimiento no se hace sweep de nada. |
Salud del writer
Un writer puede quedar degradado: bloqueado (fenced) por otro proceso
que reclama el namespace, o envenenado por un commit o un flush fallido.
Las lecturas siguen funcionando desde el snapshot publicado, las escrituras
fallan, y /v0/health retorna 503 con writer: "degraded" y un
writer_error.
- Con
--fence-policy steal(por defecto) el writer se reabre automáticamente y recupera el namespace. - Con
--fence-policy yieldun writer bloqueado queda degradado hasta que el proceso (o, en modo multi-tenant, el namespace) se vuelve a abrir; úsalo cuando un controlador externo decide qué servidor es dueño de cada namespace. --writer-lock-timeout(30 s) limita cuánto espera al writer una escritura, una sentencia DDL, un flush administrativo o unBEGINde Bolt antes de retornar 503.