Saltearse al contenido

Flush, compactación y sweep

La ruta de escritura

  1. 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.
  2. Tabla en memoria. Los datos confirmados también están en una tabla en memoria (la memtable) que consultan las lecturas.
  3. 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.
  4. 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.
  5. 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

AjustePor defectoEfecto
--flush-interval30sFlush por temporizador. 0s desactiva el temporizador.
--memtable-flush-bytes64 MiBFlush en cuanto un commit lleva la memtable por encima de este tamaño. 0 desactiva.
--memtable-stall-bytes256 MiBPor 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:

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

AjustePor defectoEfecto
--compaction-interval300sTemporizador de compactación y sweep en segundo plano. 0s desactiva todo el mantenimiento en segundo plano.
--compaction-l0-trigger8Compacta en cuanto un flush deja un bucket con esta cantidad de archivos L0. 0 desactiva el disparador reactivo.
--write-stall-l024Por 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-delay50msEl retraso que se aplica durante el stall.
NAMIDB_COMPACTION_BASE_BYTES8 MiBPresupuesto de tamaño del nivel 1; los niveles más profundos crecen según la proporción siguiente.
NAMIDB_COMPACTION_LEVEL_RATIO10Proporció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:

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

VariablePor defectoEfecto
NAMIDB_SEARCH_LSM_MAX_SEGMENTS8 (2–32)Segmentos vivos por índice. Un flush que necesita otro delta espera a la compactación.
NAMIDB_SEARCH_LSM_COMPACT_SEGMENTSmax(MAX − 2, 2)Deltas fusionados en una pasada rutinaria.
NAMIDB_SEARCH_LSM_BASE_COMPACT_BYTES8 GiBReconstruye la base cuando los bytes de delta acumulados llegan a este valor.
NAMIDB_SEARCH_LSM_BASE_STALE_PERCENT800Reconstruye la base cuando las mutaciones de delta llegan a este porcentaje del corpus vivo.
NAMIDB_SEARCH_LSM_FORCE_BASE_COMPACTIONfalseUna sola vez: reconstruye la base si hay alguna deuda de deltas.

Sweep

AjustePor defectoEfecto
--sweep-min-age24hSolo borra objetos sin referencias con al menos esta antigüedad.
--sweep-deletetruefalse 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ónHaz
Tráfico estableNada; los valores por defecto dan abasto.
Carga masiva por Cypher o BoltAgrupa con UNWIND $rows, sube o quita --write-timeout para la carga, y luego POST /v0/admin/compact.
Carga masiva desde Pythonput_nodes / merge_edges / load_parquet_*, commit(), flush(), compact(), y luego sweep().
El disco se llena en el spoolDale más espacio a NAMIDB_SPOOL_DIR; consulta Memoria y cachés.
Ejecutas la compactación en otro lugarDefine --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 yield un 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 un BEGIN de Bolt antes de retornar 503.