diff --git a/i18n/.pending/es/docs/development/migrations.md b/i18n/.pending/es/docs/development/migrations.md new file mode 100644 index 0000000000..59bf277b6c --- /dev/null +++ b/i18n/.pending/es/docs/development/migrations.md @@ -0,0 +1,151 @@ + +> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md), que prevalece. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md), which is authoritative. + + + +# Migraciones + +Esta página contiene las reglas para escribir una migración. La forma en que un despliegue las aplica, y los pasos de actualización y reversión, están en [actualizaciones](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md#how-migrations-run). [`schemas/README.md`](https://github.com/ClickHouse/loom/blob/main/schemas/README.md) describe el directorio `schemas/` y enumera las herramientas del operador. + + + +## El journal y el ledger + +- El esquema es un journal de archivos SQL numerados en `schemas/migrations/`, aplicados en + orden de prefijo numérico por `server/core/schema/migrate.py`. `000_migrations.sql` crea el ledger; + `016_baseline.sql` es el esquema inicial; cada archivo posterior es un delta. +- Cada archivo aplicado se registra en `loom._migrations` con el SHA-256 de su contenido. + Una nueva ejecución aplica solo los archivos nuevos. Un archivo modificado es **checksum drift** (deriva de checksum) y un archivo que el + repositorio ya no tiene es una **fila solo del ledger**; `loom migrate --dry-run --strict` + (un paso de CI y la verificación previa al despliegue) falla en ambos casos. Un archivo renombrado con su texto + sin cambios no es una fila solo del ledger: su SHA-256 lo identifica, y se registra con el nuevo + nombre sin ejecutarse de nuevo. +- Cada archivo usa `loom.` y `loom_telemetry.
`. El runner los asigna + a `LOOM_CH_DATABASE` y `LOOM_CH_TELEMETRY_DATABASE` al enviar cada sentencia + (`server/core/ch_names.py`), de modo que el checksum se calcula sobre el archivo tal como está escrito. Una base de datos + se compara por valor como `currentDatabase()` o un nombre enlazado, nunca como un literal `'loom'` + (`tests/unit/test_ch_names.py`). Un archivo que cambia la clave o el TTL de una tabla cuyo + nombre empieza con `_`, o que renombra o intercambia una, también actualiza su fila en [disposición del + almacenamiento](https://github.com/ClickHouse/loom/blob/main/docs/architecture/storage-layout.md) y la protección de remodelado de + `tests/unit/test_storage_layout_rows.py`. + + + +## Numeración + +Un archivo se llama `NNN_description.sql`. El runner ordena por el prefijo entero, no por el +nombre (`server/core/schema/journal.py`, `migration_order`), de modo que `1030_x.sql` se ejecuta después de `220_y.sql`. Toma el siguiente número libre, revisando `main` +y los pull requests abiertos, y consérvalo: dos archivos con el mismo número se aplican igualmente, pero en el +orden léxico de sus sufijos, que no es el orden que nadie pretendía, y un rebase +que renombra uno no vuelve a aplicar nada. `tests/unit/test_migration_numeric_order.py` falla si +se comparte un número. + + + +## Reglas para escribir una migración + +- **Nunca edites ni elimines una migración ya fusionada.** Los registros de los despliegues guardan su hash. Una corrección es un archivo nuevo. +- **Solo cambios aditivos.** Añade tablas, columnas, índices, projections y vistas; elimina un índice de omisión (skip index) o una projection que ningún código bajo `server/`, `scripts/`, `bench/` o `dev/` nombre (la compilación anterior pierde una optimización, nunca una columna); cambia codecs, valores por defecto o ajustes de tabla; amplía tipos; extiende un enum. Nunca elimines ni renombres una tabla o una columna, y nunca intercambies tablas. `tests/unit/test_migrations_additive.py` lo hace cumplir. De las vistas y las tablas, solo permite `DROP VIEW IF EXISTS` de una vista materializada que actúa al insertar y `DROP TABLE IF EXISTS` de una tabla reemplazada, en cada caso cuando ningún archivo bajo `server/`, `scripts/`, `bench/` o `dev/` la nombra: ni una compilación en servicio ni una herramienta de operador (que se ejecutan contra el servicio de producción) la lee. Restringir un tipo queda como cuestión de revisión, ya que una expresión regular no puede distinguirlo de una ampliación. +- **Retira una columna en dos versiones.** Primero publica una versión cuyo código ya no la lea ni la escriba; elimínala solo cuando ninguna compilación en servicio la nombre. +- **Todo escritor lleva una columna nueva.** Añadir una columna a `loom.memory` o `loom.shared` implica actualizar los constructores de filas en `server/memory/store/rows.py` (`build_memory_version_row`, `build_embedding_row`) y cada projection que los alimenta en el mismo cambio: son tablas `ReplacingMergeTree(version)` que se leen con `FINAL`, y una fila de versión que omite una columna la pone a cero en silencio para todos los lectores. Una columna nueva de `loom.memory` también debe añadirse a `loom.memory_versions` y al `SELECT` de la vista `memory_versions_mv` en la misma migración; de lo contrario, el historial deja de registrarla (`tests/unit/test_memory_versions_schema.py` compara las listas de columnas). +- **Una tabla que pueda contener contenido de memoria** necesita además un paso en la saga de borrado y una fila en el censo de residuos (`server/erasure/store/census.py`, `_CENSUS`); `tests/unit/test_every_table_is_classified.py` falla ante una tabla nueva que no figure en ninguna lista ([añadir una tabla](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-table.md)). +- **DDL portable entre motores.** Declara las columnas vectoriales como `Array(BFloat16) CODEC(NONE)`; donde el codec `Quantized` pueda estar activo, el runner las crea ya codificadas ([ajustes restringidos](../architecture/clickhouse.md#gated-clickhouse-settings)). Usa nombres de motor `MergeTree` simples, que ClickHouse Cloud ejecuta como `SharedMergeTree`. + +**Por qué aditivo.** La compilación que estaba en servicio antes de ejecutar una migración debe poder seguir leyendo y escribiendo después todas las tablas que conocía. Eso convierte un rollback blue/green en un cambio de proxy en lugar de un rollback de esquema, y permite que el color anterior siga sirviendo mientras el nuevo aplica las migraciones al arrancar. El precio se paga aquí: dos versiones para retirar una columna y reconstrucciones en lugar de `ALTER` para los cambios de clave. + + + +## Directivas del runner + +Un archivo de migración puede llevar directivas en comentarios que el runner lee: + +| Directiva | Efecto | +| ----------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `-- loom: tolerate-error ` | el archivo sobrevive a un error del servidor con nombre (por ejemplo, un setting que solo aceptan algunos servidores) | +| `-- loom: rebuild-if-empty
` | declara una clave de ordenación o de partición objetivo para `
` (abajo) | +| `-- loom: baseline covers N` | el archivo reemplaza a todos los archivos numerados N o menos que el repositorio ya no incluye | + +**Baselines.** Un baseline lleva el número N, posterior al del archivo más reciente que reemplaza. Una base de datos nueva lo ejecuta. Una base de datos cuyo ledger contiene el archivo N lo registra sin ejecutarlo y conserva las filas reemplazadas, que el modo estricto informa como reemplazadas (superseded) y no como errores. Así, una compactación (squash) no requiere editar a mano ningún ledger, y una compilación anterior a ella sigue encontrando aplicados todos sus propios archivos. Una base de datos cuyo ledger contiene algunos archivos reemplazados pero no el archivo N se detuvo a medio camino: `loom migrate` la rechaza (`stranded`) y no cambia nada, ya que ejecutar el baseline omitiría los archivos que le faltan y registrarlo daría por hecho su esquema. Aplica los archivos que faltan con una compilación anterior a la compactación y vuelve a migrar. Compacta en una versión, no en cada cambio; la compactación construye el baseline a partir de `schemas/schema.sql` (el cuerpo del volcado sin los objetos que crean los archivos que conserva) y lo comprueba en un servidor nuevo, en un ledger totalmente migrado y en uno a medio migrar. + +El runner también adapta sentencias al aplicarlas sin cambiar los archivos ni sus checksums: elimina el flag experimental de NLP donde el servidor lo prohíbe, crea las columnas vectoriales con el códec `Quantized` donde puede estar activo, quitando un códec general encadenado después de él donde `allow_suspicious_codecs` no puede estarlo (`server/core/schema/vector_codec_ddl.py`), crea cada vista con el usuario que ejecuta la migración (`DEFINER = CURRENT_USER`: el volcado nombra a su propio usuario, que otro servidor puede no tener) y espera a que termine cada mutación que emite un archivo antes de registrarlo (`LOOM_MIGRATE_MUTATION_WAIT_S`). + +**Verificaciones previas.** Un archivo que no debe ejecutarse mientras los datos contengan algo que el archivo por sí solo no puede ver registra una verificación en `server/core/schema/prechecks.py`, indexada por su nombre sin el número, de modo que un archivo renumerado la conserva. El runner ejecuta la verificación antes del archivo, también en una ejecución de prueba (dry run); una verificación que rechaza detiene la ejecución con su mensaje y no ejecuta nada del archivo. `097_mirror_names_reserved.sql` usa una: rechaza mientras un espacio de nombres con la forma reservada de espejo esté registrado o contenga filas vivas. + + + +## Cambiar una clave de ordenación o una clave de partición + +ClickHouse no cambia ninguna de las dos en el lugar, así que una migración declara el destino y la tabla se reconstruye, nunca se altera: + +```sql +-- loom: rebuild-if-empty code_test_facets +CREATE TABLE loom.code_test_facets ( ...every column, unchanged... ) ... ORDER BY (...); +``` + +Esa sentencia es la única copia del DDL de destino. El runner (`server/core/schema/table_rebuild.py`) compara el `sorting_key` y el `partition_key` de la tabla en vivo con ella: si coinciden, registra el archivo; una tabla vacía (una instalación nueva) se intercambia al instante por una gemela con el DDL de destino; y una tabla con filas hace fallar el arranque con un mensaje que nombra la herramienta. Un arranque nunca copia filas. En un despliegue con datos, el operador ejecuta primero la herramienta, una tabla a la vez: + +```bash +python -P -m scripts.ops.table_rebuild --table code_test_facets --dry-run +python -P -m scripts.ops.table_rebuild --table code_test_facets --yes +``` + +Toda acción que modifica algo (`--yes` solo, `--rollback`, `--drop-pre-rebuild`) imprime el ClickHouse con el que se comunica y su plan, y no cambia nada sin `--yes`. La herramienta copia todas las filas (sin FINAL) a `loom._rebuild` en lotes acotados, copia las partes escritas entretanto, comprueba el número de filas bajo FINAL y la versión más reciente de una muestra de claves, intercambia con `EXCHANGE TABLES` y conserva la tabla antigua como `loom._pre_rebuild` para `--rollback` hasta `--drop-pre-rebuild`. Se niega a intercambiar, conservando la gemela, cuando un `ALTER` cambió la tabla en vivo durante la copia: sale con 6 si ClickHouse lo ejecuta como mutación (eliminar, renombrar o cambiar el tipo de una columna, eliminar un índice, un TTL) y con 3 si solo mueve el tiempo de sus metadatos (un índice, un ajuste, el valor por defecto o el códec de una columna). Una columna añadida hace fallar la copia (salida 1, sin intercambio), o la ejecución sale con 3 tras la última pasada de verificación. Una reconstrucción no arrastra un `ALTER`: vuelve a expresarlo en la sentencia de destino y ejecuta de nuevo con `--restart`. Además, rechaza una tabla que ninguna migración declara. +`loom migrate --dry-run --strict` falla mientras una tabla declarada siga teniendo filas en la disposición antigua, de modo que la comprobación previa al despliegue detecta un paso omitido. + +El destino conserva las columnas de la tabla (así el intercambio es aditivo), y su clave de ordenación conserva las columnas de la clave antigua, reordenadas: esa clave es también la que usa un `ReplacingMergeTree` para fusionar. Una clave con otras columnas fusiona otras filas y se lista con su motivo en `tests/unit/test_migrations_additive.py`. Nombra la reconstrucción en las notas de la versión como un paso del operador ([proceso de publicación](https://github.com/ClickHouse/loom/blob/main/docs/development/release-process.md#release-notes)). + + + +## Migraciones de Postgres + +Los archivos `schemas/pg_migrations/NNN_*.sql` siguen las mismas reglas: están numerados, son aditivos, nunca se editan una vez fusionados, y cada `CREATE`, `ALTER` o `DROP` de una tabla nombra `loom.
`, salvo el nombre nuevo de un renombrado, donde Postgres no admite esquema (`tests/unit/test_storage_layout_rows.py`). Un arranque los aplica bajo un bloqueo consultivo (advisory lock) de Postgres, cada archivo en una transacción junto con su fila del registro. Una migración espera como máximo 5 s a un bloqueo de tabla (`lock_timeout`, y luego reintenta), de modo que un `ALTER` nunca deja en cola todas las consultas de la tabla detrás de una transacción larga. Una compilación sirve con un registro que contiene archivos de una compilación posterior, con una advertencia que los nombra; un archivo del registro que no incluye, numerado igual o por debajo de su propio último archivo, o uno cuyo checksum cambió, rechaza el arranque. + +Cada archivo se ejecuta en una transacción, por lo que una migración no crea índices en una tabla grande: la creación bloquearía las escrituras de la tabla, y cada commit respondería 503, hasta que termine. Un índice así necesita `CREATE INDEX CONCURRENTLY` fuera de una transacción, y un arranque que espera el bloqueo consultivo entra en interbloqueo con él (una sesión en espera mantiene un snapshot que la creación debe esperar a que termine): un cambio que añade un archivo de ese tipo también toma el bloqueo reintentando `pg_try_advisory_lock`. Cuando la primera versión que escribe en una tabla incluye el archivo, la tabla es pequeña dondequiera que se ejecute el archivo, y su índice puede crearse en la transacción del archivo (`010_revision_delivered_at.sql`). + + + +## Volcado y verificación del esquema + +`schemas/schema.sql` es el resultado volcado de aplicar todas las migraciones: léelo para +entender la forma actual, nunca lo edites a mano. Después de cambiar una migración, regénéralo +contra un ClickHouse nuevo de la versión que prueba CI (`clickhouse/clickhouse-server:latest`): + +```bash +bash dev/ci_start_clickhouse.sh # that image with Loom's server config +make migrate +make schema-dump # rewrites schemas/schema.sql only when the dump differs +make schema-check # exit 1 with the head of the diff; writes nothing +``` + +Si el volcado falla, el archivo queda como estaba. Otra versión de ClickHouse, un servidor donde el +códec `Quantized` o su cadena `LZ4` no se pueden activar, o una base de datos que contiene gemelas de reconstrucción producen un volcado +distinto, y por eso importa el contenedor fijado. Las tablas internas (`_migrations`, nombres que empiezan por `_` o `.`) +se excluyen. El job `schema-check` de CI reproduce todas las migraciones en un servidor nuevo, ejecuta +la prueba en seco estricta y después `make schema-check`. + +CI sigue `latest`, así que una nueva versión de ClickHouse que imprima el DDL de otra forma pone +`schema-check` en rojo sin ningún cambio en Loom. Lee la diferencia que imprime el job: cuando solo es +de formato, ejecuta los cuatro comandos anteriores (descargan la nueva versión) y confirma +`schemas/schema.sql` por separado. Un cambio de significado (un tipo, un valor por defecto, un ajuste +del motor) es un cambio de comportamiento de ClickHouse que conviene investigar antes de volcar encima; +`LOOM_CLICKHOUSE_IMAGE=clickhouse/clickhouse-server:A.B.C.D` ejecuta los comandos anteriores sobre la +última versión que se volcó sin diferencias, para comparar. + + + +## Lista de verificación + +1. Toma el siguiente número libre; escribe el archivo de forma aditiva. +2. Actualiza los constructores de filas, `loom.memory_versions`, el censo de borrado y los casos del analizador si el cambio los afecta. +3. Ejecuta `make migrate` contra un ClickHouse local, luego `make schema-dump` y confirma `schemas/schema.sql` junto con la migración. +4. Ejecuta `make test-unit` (las pruebas de aditividad, numeración y clasificación del esquema) y la suite de integración para las rutas que leen la nueva forma. +5. Anota cualquier paso del operador (una reconstrucción, un backfill) para las notas de la versión. + + + +## Relacionado + +- [Actualizaciones](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md): cómo el runner aplica los archivos en un despliegue +- [ClickHouse](../architecture/clickhouse.md) +- [Referencia del esquema](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md) diff --git a/i18n/.pending/es/docs/features/memory/retention-and-erasure.md b/i18n/.pending/es/docs/features/memory/retention-and-erasure.md new file mode 100644 index 0000000000..710b294d5e --- /dev/null +++ b/i18n/.pending/es/docs/features/memory/retention-and-erasure.md @@ -0,0 +1,292 @@ + +> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md), que prevalece. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/retention-and-erasure.md), which is authoritative. + + + +# Retención y borrado + +Loom no elimina ninguna memoria a menos que lo solicite quien la escribió, el propietario del espacio de nombres o el operador. La memoria no tiene una vida útil por defecto. Los datos salen de tres maneras: una expiración o eliminación hecha por quien escribe, una retención que configuró un propietario u operador, y un borrado que elimina un ámbito en todos los lugares donde Loom lo guarda. + + + +## Qué se conserva y por cuánto tiempo + +Ninguna tabla de memoria, embeddings, historial de versiones, conversaciones, entidades, resúmenes, memoria de trabajo o conocimiento tiene un TTL en `schemas/schema.sql`, y ningún worker retira filas por antigüedad. +Las tablas de enlaces `entity_triple_rows` y `entity_edge_rows` siguen a `entity_triples` y +`entity_edges`: sin TTL. Una eliminación definitiva (erasure) borra los enlaces de las memorias que elimina, y +`loom erasure-re-verify --completed-since … --resume` borra los enlaces huérfanos que dejó la eliminación de una compilación anterior. +Una fila sale del conjunto servido solo cuando: + +- **la elimina quien la escribió**: `memory.delete`, una reescritura con la misma clave que la sustituye, + `memory.apply`, `memory.clear`, `conflicts.resolve`, `blacklist.add(sweep=true)`; +- **quien la escribió definió una caducidad**: `ttl_seconds` o `valid_to` en `memory.set`, + `memory.touch`, `run.complete(retain="expire")`, el `expires_in_days` de una reflexión; +- **el propietario o el operador configuró una**: consulta la [retención configurada](#configured-retention). + +Las tablas operativas (telemetría, cachés, colas) tienen TTL fijos: `loom.search_trace_log` +y `loom.memory_exposures` 180 días; `loom.erasure_requests` y +`loom.policy_decisions` 90 días; `loom.memory_drops`, `loom.memory_extraction_queue`, +`loom.events` y `loom.embedding_cache` 30 días; `loom.llm_response_cache` 7 días. La +[referencia del esquema](https://github.com/ClickHouse/loom/blob/main/docs/reference/schema.md) lista el TTL de cada tabla. + +Un worker elimina datos según un temporizador: `namespace_gc` purga los espacios de nombres de +`kind = 'bench'` (identificados por `LOOM_NAMESPACE_BENCH_PREFIXES` en el registro automático) sin +escrituras durante `LOOM_NAMESPACE_GC_IDLE_HOURS`, mediante una saga de eliminación definitiva. Nunca toca +otros tipos. Consulta [espacios de nombres y uso compartido](https://github.com/ClickHouse/loom/blob/main/docs/features/namespaces-and-sharing.md). + + + +### Borrar no es eliminar definitivamente + +Una lápida (tombstone) es una nueva versión con `tombstoned_at` definido. Las lecturas dejan de servirla de inmediato, pero +la fila y sus versiones anteriores en `loom.memory_versions` siguen en disco: + +- `memory.restore` revive una clave con lápida dentro de 14 días (después responde + `expired=true`). También revierte una sustitución automática. +- `memory.clear` (admin) pone una lápida a todas las memorias de un agente o usuario en un espacio de nombres; + `confirm_subject` debe repetir el `user_id` o `agent` concreto (ni `'*'` ni `'-'` + confirman). `agent="*"` con un `user_id` borra las filas de ese usuario bajo cualquier agente, y + `user_id="*"` con un `agent` borra las filas de ese agente para todos los usuarios. Se rechaza un alcance que no nombre a nadie + salvo `'-'`, igual que un borrado de todo el espacio de nombres. Las filas bloqueadas permanecen y se cuentan en + `locked_skipped`. Las claves borradas se reviven del mismo modo. + +Para eliminar los bytes, usa una [eliminación definitiva](#erasure). Para quitar un valor pero conservar la fila y el +rastro de auditoría, usa [`memory.redact`](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md#scrubbing-history-memoryredact). + + + +### Caducidad definida por el escritor + +Una fila se oculta de las lecturas en el momento en que pasa su `expires_at`. Después, el worker +`memory_expiry_sweep` aplica el `on_expire` del escritor como una nueva versión: + +| `on_expire` | Efecto | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `tombstone` (predeterminado) | Se le pone lápida, con la ventana de restauración de 14 días. | +| `demote` | Se borra la caducidad; confianza × `LOOM_MEMORY_EXPIRY_DEMOTE_FACTOR` (0.5), nunca por debajo de `LOOM_MEMORY_EXPIRY_DEMOTE_FLOOR` (0.05). | +| `anonymize` | El valor se reemplaza por un marcador y se descartan los embeddings; la fila permanece como prueba de que existió. | + +`memory.touch` cambia solo la caducidad de una fila, para una clave o hasta 1,000 (`memory_keys`): un +nuevo `ttl_seconds`, `clear_expiry=true` o un nuevo `on_expire`. `memory.sweep_expired` +(admin) ejecuta un barrido para un espacio de nombres bajo demanda, con `dry_run`. Una edición de otros campos +mantiene una caducidad vigente. + + + +### Retención configurada + +Todo está desactivado de forma predeterminada (0 = conservar siempre). + +| Dónde | Se define con | Efecto | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Un tipo de memoria en un espacio de nombres | `retention_days` en una entrada `tag_registry` de `namespace.register` | Una fila que `memory.set` escribe sin caducidad vigente, `ttl_seconds` ni `clear_expiry` recibe `expires_at = now + N days`; una fila `read_only` reafirmada no recibe ninguna. | +| Filas sensibles | `LOOM_MEMORY_SENSITIVE_RETENTION_DAYS`, `LOOM_MEMORY_SENSITIVE_ON_EXPIRE` (predeterminado `anonymize`) | Las filas nuevas de sensibilidad `medium` / `high` reciben una caducidad; prevalece una caducidad más corta del llamante. | +| Las escrituras de una ejecución | `LOOM_MEMORY_RUN_COMPLETE_RETAIN` (`keep`, `demote`, `expire`), `LOOM_MEMORY_RUN_COMPLETE_EXPIRE_DAYS` (7) | Lo que `run.complete` hace con las filas de la ejecución cuando la llamada no lo indica. Las filas fijadas, verificadas, promovidas, bloqueadas, episódicas y de reflexión siempre se conservan. | +| Un espacio de nombres completo | `retention_days`, `warm_days` en `namespace.register` | Un TTL de tabla (y traslado al nivel cálido) para las filas de ese espacio de nombres. | +| El despliegue | `LOOM_RETENTION_
_DAYS`, `LOOM_TIERING_
_WARM_DAYS` | Un TTL de tabla (y traslado al nivel cálido) en `audit_log`, `agent_events`, `memory`, `memory_embeddings`, `conversations`, `chunks`, `documents`. | + +Bajo la autoridad de Postgres, ninguna de las dos últimas filas pone un TTL de retención en +`memory`, `memory_embeddings` ni `documents`: eliminaría la copia en ClickHouse de filas que +Postgres aún sirve, por lo que el arranque rechaza `LOOM_RETENTION_MEMORY_DAYS`, +`LOOM_RETENTION_MEMORY_EMBEDDINGS_DAYS` y `LOOM_RETENTION_DOCUMENTS_DAYS` +([autoridad de almacenamiento](../../architecture/storage-authority.md)). El +`retention_days` de un espacio de nombres tampoco afecta a `chunks`, de modo que un documento que permanece conserva los fragmentos con los que la búsqueda lo encuentra; `LOOM_RETENTION_CHUNKS_DAYS` sigue aplicándose. + +El worker `retention_reconcile` aplica las dos últimas filas como un `ALTER TABLE … MODIFY TTL` idempotente por tabla, por `(org, namespace)` cuando existen sobrescrituras, y +elimina el TTL de una tabla cuando ya no queda ningún espacio de nombres ni ventana de despliegue sobre ella. En +`loom.memory` el TTL se basa en `coalesce(expires_at, created_at)`, de modo que la caducidad del escritor +prevalece. + +- **Un TTL de tabla elimina físicamente** en la siguiente fusión (merge) de la parte. No hay ventana de restauración, y las lápidas caducan junto con las filas que ocultan. +- **Un Undo se mantiene mientras se mantenga su registro.** El resolutor de conflictos respeta el Undo de una persona + sobre una retirada mediante su fila `memory.unsupersede` en `audit_log`. Con un TTL de `audit_log` + más corto que la vida de un par, un Undo caducado deja de mantenerse, y el resolutor puede juzgar + y retirar ese par de nuevo. +- **El almacenamiento por niveles necesita un volumen.** `LOOM_TIERING_WARM_VOLUME_NAME` debe nombrar un volumen de la + política de almacenamiento, y la antigüedad cálida debe ser menor que la antigüedad de retención. + + + +## Borrado + +`erasure.request` borra un ámbito en todos los lugares donde Loom lo conserva, y responde cuando puede demostrar que no queda nada del ámbito. Para borrar todo lo que un id de usuario tiene en la organización, un administrador de la organización solicita el ámbito `user_id`, que borra las filas del usuario en todos los espacios de nombres de la organización (`purge=true` las elimina en lugar de marcarlas con una lápida; lo que deja se enumera más abajo). `memory.clear` marca con una lápida las memorias de un agente o de un usuario solo en un espacio de nombres ([eliminar no es borrar](#delete-is-not-erase)). + +| `scope_type` | `scope_value` | Quién puede solicitarlo | +| ---------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------- | +| `user_id` | El id de usuario, en todos los espacios de nombres de la organización | Un administrador de la organización | +| `namespace` | Un espacio de nombres | Un administrador de ese espacio de nombres (o de la organización) | +| `namespace_list` | Un arreglo JSON de 1–500 espacios de nombres, o `{"namespaces": [...], "purge": bool}` | Un administrador de la organización | + +La op se puede invocar con un token de escritor, pero el handler exige permisos de administrador sobre el destino (de lo contrario, 403 `AUTH_INSUFFICIENT`). + +Los vínculos de categoría (`loom.memory_categories`) no llevan usuario, así que un borrado de `user_id` los deja, junto con las filas de auditoría de `memory.import` que los enumeran. Para un elemento importado, la clave del vínculo es `import:` más un resumen (digest) de su texto, que permite confirmar un texto adivinado; un borrado de `namespace` elimina los vínculos. + +Un borrado de `user_id` elimina los chunks literales marcados con el usuario y los chunks sin usuario (`-`) bajo alguno de los pares `(namespace, key)` del usuario, sea de quien sea la memoria a la que pertenezcan: un chunk `-` puede contener texto del usuario, y la ruta de escritura también los retira como del escritor. Los chunks marcados con otro usuario permanecen. + +Un borrado de `user_id` también retira los resúmenes consolidados construidos a partir de las memorias del usuario, con la identidad que los haya escrito ([cuáles](../../architecture/memory-architecture.md#background-passes)), junto con lo derivado de ellos: su historial de versiones, sus chunks literales y vectores de entidades, las filas del grafo extraídas de ellos y las copias a nivel de espacio de nombres promovidas a partir de ellos. También elimina las respuestas de `memory.ask` en caché y los precedentes que los citaban. + + + +### La saga + +```mermaid +flowchart TD + R["erasure.request"] --> L["ledger row in loom.erasure_requests
(in_progress)"] + L --> S["Loom steps: memory, embeddings, versions,
chunks, evidence, summaries, graph,
conversations, blobs, briefs, runs, tasks, ..."] + S --> X["external backends:
Langfuse, ClickStack"] + X --> V["verify.residue census"] + V -->|no live rows| C["completed
(residue_count 0, verified_at)"] + V -->|rows left| F["failed
(residue per table)"] + S -->|step error| F + X -->|backend cannot confirm| F + F --> W["erasure_recovery worker
resumes from steps_completed"] + W --> S + W -->|5 attempts| A["failed + erasure.abandoned audit row"] +``` + +- **Pasos con puntos de control e idempotentes.** Cada paso terminado se registra en `steps_completed`. El worker `erasure_recovery` reanuda desde su punto de control una saga que quedó en `in_progress` o `failed`. Un paso espera hasta `LOOM_ERASURE_MUTATION_WAIT_S` a su mutación y, si no termina, falla nombrándola. +- **Las fuentes de documentos se detienen antes de que se vayan los documentos.** Un borrado de espacio de nombres retira las [fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#document-sources) del espacio de nombres en `knowledge_sources.retire`, su primer paso, y borra sus credenciales; luego espera a que termine el turno de sincronización de cada fuente que siga en ejecución (hasta 30 segundos en total; un turno que sigue en ejecución hace fallar el paso con `OVERLOADED`, y `erasure_recovery` reintenta la saga), de modo que ninguna sincronización vuelva a escribir un documento o una decisión extraída después de que los pasos posteriores los borren. +- **Los vínculos de código esperan al worker de vínculos.** `code_links.delete` toma el lease de cola del worker de vínculos de código, de modo que ninguna pasada publique un cursor que leyó antes del borrado: entre hosts con Keeper, dentro de un mismo proceso sin él. Espera hasta 15 minutos a que termine una pasada; pasado ese tiempo el paso falla con `LeaseBusy` y `erasure_recovery` lo reintenta. +- **Lápida o purga.** De forma predeterminada, las tablas de borrado lógico (memoria, embeddings, chunks, resúmenes, vínculos) se marcan con una lápida, y `memory.restore` todavía puede revivirlas dentro de la ventana; `erasure.list` informa esas reanimaciones como `reversals_count`. `purge=true` elimina las filas en su lugar (un `DELETE FROM` ligero en las tablas anchas). Un ámbito que contiene un espacio de nombres que alguna vez tuvo un mirror se purga entero, todos los espacios de nombres que contiene, de modo que ninguno tiene esa ventana ([fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror)). Un borrado de usuario encuentra lo que las memorias del usuario alimentaron a través de sus claves, así que en una purga sus filas de `loom.memory` y los resúmenes consolidados construidos a partir de ellas se marcan primero con una lápida y se eliminan en `memory.retire`, después de todos los pasos que leen esas claves; hasta entonces `memory.restore` puede revivirlos (las filas propias del usuario cuentan como una reversión, los resúmenes no), y `memory.retire` elimina lo que `memory.restore` revivió. +- **Originales subidos** de documentos de conocimiento: primero se eliminan las filas del espacio de nombres en `loom.document_blobs` y se registra `blob_erased_at`. Un borrado de usuario elimina los originales que ese usuario subió y que no comparte ningún documento activo de otro escritor, encontrados a través de `loom.blob_uploads` (una fila por subida de cada usuario final, ya que la versión del documento que nombraba un original pudo haber sido reemplazada y fusionada) y a través de sus documentos; después se van sus filas de `loom.blob_uploads`. El censo cuenta ambas tablas. Los originales guardados en un bucket compatible con S3 (`LOOM_DOCUMENT_OBJECT_STORE=s3`) se eliminan antes que sus filas: un borrado de espacio de nombres elimina todos los objetos del ámbito bajo su prefijo y el censo cuenta lo que queda allí (`objects.document_originals`); un borrado de usuario elimina todos los objetos que contienen bytes de los originales propios del usuario, los nombre una fila o no, vuelve a listar sus prefijos y hace fallar el paso si el almacén conservó alguno, luego elimina las filas y después elimina lo que esos prefijos aún contienen y ninguna fila nombra, de modo que la propia subida del usuario de esos bytes, cuya fila se llevó el borrado, también pierde su objeto. Una subida de esos bytes que siga en curso cuando se ejecuta el paso, de cualquier escritor (su objeto almacenado, su fila aún no insertada), pierde su objeto, y su fila, una vez insertada, responde `410 BLOB_GONE`. Cada lote de originales se vuelve a leer justo antes de eliminarse, así que un original que el documento de otro escritor haya nombrado desde entonces permanece; otro escritor que almacene los mismos bytes en el mismo espacio de nombres después de esa lectura puede perderlos, igual que en el almacén de ClickHouse. Una fila que nombra un objeto mientras no hay bucket configurado, o uno fuera del bucket y prefijo configurados, hace fallar el paso en lugar de dejar los bytes. En cualquiera de los dos almacenes, un borrado de usuario elimina las filas en el menor número de mutaciones en que caben sus originales (cada una enlaza tantos como un parámetro de ClickHouse puede llevar). Mover originales de ClickHouse al bucket (`loom knowledge migrate-originals`) está protegido por este ledger: no mueve un original que cubra un borrado sin terminar, y un movimiento que un borrado alcanza termina como ese borrado decida ([dónde se almacenan los originales](https://github.com/ClickHouse/loom/blob/main/docs/features/knowledge.md#where-originals-are-stored)). +- **Las cancelaciones de ingesta.** Un borrado de usuario elimina las filas de ingesta del usuario, entre ellas las cancelaciones. Una cancelación que el usuario pidió sobre el trabajo de otro escritor que sigue pendiente o en procesamiento se conserva primero como una fila sin identidad (`agent`, `user_id` y `session_id` en `'-'`, `actor` vacío), de modo que ese trabajo siga cancelado. +- **Cachés de toda la organización.** `loom.idempotency` (respuestas reproducidas) y `loom.embedding_cache` (vectores de consultas, nunca su texto) llevan la organización pero no un espacio de nombres ni un usuario final, así que un borrado en cualquiera de los dos ámbitos elimina todas las filas de la organización en ambas tablas. El costo son fallos de caché. El censo cuenta `loom.idempotency` en toda la organización pero no `loom.embedding_cache`, que cualquier búsqueda de la organización vuelve a llenar; la caché de vectores en el proceso de cada réplica expira dentro de `LOOM_EMBEDDING_CACHE_TTL_S`. +- **Aprendizajes de reglas del bot.** Las palabras de un usuario en la cola de aprendizajes viven solo en sus filas de `loom.learnings_supporters`, que un borrado de usuario elimina. Un candidato a regla que se queda sin ningún respaldo se elimina entonces si está pendiente, o conserva su decisión con la regla en blanco ([extracción](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/extraction.md#rules-the-assistant-states-about-itself)). El censo cuenta esos candidatos sin respaldo en toda la organización, no solo los del usuario borrado, por lo que una saga puede fallar por un candidato que otro borrado de la organización dejó a medio paso; su paso reabierto lo limpia. + + + +### La cascada federada + +Los datos que Loom envió a otros sistemas se borran en la misma saga. Los pasos externos fallan en modo cerrado: un backend que no puede confirmar el borrado (5xx, timeout, caída de red, una respuesta de salud de Langfuse sin versión) hace fallar el paso, y el worker reintenta. "Nada que borrar" (cero filas coincidentes, o una tabla de ClickStack que el servicio no tiene) cuenta como éxito. + +| Backend | Configurado por | Borra | +| ---------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| Langfuse | `LOOM_LANGFUSE_URL` + `LOOM_LANGFUSE_ADMIN_TOKEN` | Trazas encontradas por `userId` dentro de la etiqueta de la organización, o por el par de etiquetas `org:` + `namespace:`. | +| ClickStack | `LOOM_CLICKSTACK_DATABASE`, `LOOM_CLICKSTACK_USER_ID_KEYS` | Filas OTel en el mismo servicio de ClickHouse, que coinciden con las claves de atributo del id de usuario o con el espacio de nombres. | + +Un borrado de espacio de nombres en ClickStack solo coincide con una fila `loom.namespace` cuando lleva el `loom.org` de la organización que borra, de modo que las métricas propias de Loom de ops y de dominio, que no llevan organización, conservan la etiqueta del espacio de nombres ([borrado en ClickStack](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md#erasure)). + +Un backend sin configurar registra la intención y no borra nada. Solo un borrado de `namespace_list` puede pasar `external=false`; los borrados de `user_id` y `namespace` siempre incluyen los backends. `LOOM_EXTERNAL_ERASURE_TIMEOUT_S` limita cada llamada. Configuración: [Langfuse](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/langfuse.md) y [ClickStack](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/clickstack.md). + + + +### El censo de residuos + +El último paso, `verify.residue`, cuenta las filas activas del ámbito en todas las tablas que tocan las rutas de lectura. Cualquier fila restante hace fallar la saga; la fila terminal lleva `residue_count`, `residue` (por tabla), `verified_at` y `census` (todos los conteos, más abajo). Una saga reanudada vuelve a ejecutar el paso que es dueño de cualquier tabla en la que el último censo encontró filas, aunque su punto de control diga que terminó, y siempre vuelve a contar. + + + +### El comprobante + +`erasure.status` (y la respuesta de `erasure.request`) lleva el comprobante del censo de la última ejecución. `census` es null cuando la última fila del ledger no contiene un censo que haya contado todos los almacenes: una ejecución en curso, un censo que no pudo ejecutarse o dejó un almacén sin contar, o una fila escrita por una compilación que no guarda censo. Los campos del comprobante: + +- `census`: cada sustrato que el censo contó y su conteo, incluidos los ceros. Las claves son nombres de tabla, `pg:
` para la autoridad de Postgres, `objects.document_originals` para el bucket de documentos en un ámbito de espacio de nombres, y `provider_rebuild_copies` sumado sobre las copias de una reconstrucción de proveedor, 0 cuando no existe ninguna (contado en todo el despliegue cuando una copia no tiene columna de organización). Un conteo son las filas que el censo cuenta como residuo en este ámbito: filas activas, o todas las filas cuando la saga purga o la tabla no conserva lápidas ([las reglas del censo](../../architecture/memory-architecture.md#erasure-saga)). `objects.document_originals` cuenta una primera página de listado, así que se lee como "al menos". +- `purge`: el modo de eliminar o marcar con lápida del ámbito (el de un solo espacio de nombres es lápida, se haya pedido lo que se haya pedido); un ámbito que contiene un mirror ([fuentes de documentos](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-sources.md#the-mirror)) se elimina digan lo que digan estos valores. Sin purga, una fila con lápida conserva sus bytes en su parte hasta que la tabla se fusiona; con purga las filas se eliminan, y sus bytes permanecen en disco hasta que una fusión o el worker de recuperación de espacio los elimina. +- El sujeto y el momento son `org`, `scope_type`, `scope_value` y `verified_at` del estado. + +El comprobante es el conteo de Loom. Conserve la respuesta: `erasure.status` sirve la fila del ledger durante 89 días después de la solicitud, y la fila de auditoría `erasure.completed`, que también lleva el censo, se escribe después de la fila completada, en la medida de lo posible, y se conserva durante `LOOM_RETENTION_AUDIT_LOG_DAYS`. Cuando quien lo solicitó no recibió respuesta (una saga que terminó el worker de recuperación, una ejecutada en segundo plano, una llamada que agotó el tiempo), lea `erasure.status` dentro de los 89 días. + + + +#### Verificar usted mismo un borrado + +Un operador que tenga la concesión de la superficie SQL de la organización con `--namespaces '*'`, o `--all` ([superficie SQL](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#access)), puede volver a contar tres de las claves del censo, `loom.memory`, `loom.memory_versions` y `loom.conversations`, y revisar el ledger de solicitudes (la cuarta sentencia, más abajo). Enlace el id borrado y el momento del censo como parámetros. ClickHouse igualmente escribe los valores enlazados en `system.query_log`, como hace con las sentencias del propio borrado (más abajo), así que ejecute la verificación desde `clickhouse-client` en lugar de hacerlo a través de `pg_clickhouse`, cuyo texto delegado un registro de sentencias de Postgres conservaría como una copia más: + +```bash +read -r uid # the erased id, typed at the prompt so it stays out of the shell history +clickhouse-client --param_org='' --param_uid="$uid" --param_at='' \ + --multiquery --query " +SELECT count() FROM loom.sql_v1_memories WHERE org = {org:String} + AND user_id = {uid:String} AND created_at <= {at:DateTime64(6, 'UTC')}; +SELECT count() FROM loom.sql_v1_memory_history WHERE org = {org:String} + AND user_id = {uid:String} AND created_at <= {at:DateTime64(6, 'UTC')}; +SELECT count() FROM loom.sql_v1_conversations WHERE org = {org:String} + AND user_id = {uid:String} AND ts <= {at:DateTime64(6, 'UTC')}; +SELECT count() FROM loom.sql_v1_agent_events WHERE org = {org:String} + AND user_id = {uid:String} AND ts <= {at:DateTime64(6, 'UTC')};" +``` + +El filtro `org` limita al org de la eliminación una concesión que cubre más de un org (`--all`). +Cada sentencia sigue leyendo todo el alcance de la concesión antes de filtrar ([qué cuesta una lectura](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#what-a-read-costs)), de modo que en un org grande o con una concesión `--all` una sentencia puede detenerse en los límites del usuario SQL (`LOOM_CH_ANALYSIS_MAX_ROWS_TO_READ`, `_MAX_EXECUTION_S`) con un error en lugar de un recuento; súbelos para la comprobación. Para un alcance de espacio de nombres, pasa `--param_ns=''` y filtra las tres primeras por `namespace = +{ns:String}` en lugar de `user_id`; para un `namespace_list`, ejecútalo una vez por cada nombre en los `namespaces` de su `scope_value`; la sentencia `sql_v1_agent_events` es solo para un alcance de usuario, ya que una eliminación de espacio de nombres conserva las filas del registro de solicitudes del espacio de nombres. Cada recuento es 0 después de una eliminación completada, con estas diferencias respecto al censo: las vistas excluyen los espacios de nombres restringidos, `sql_v1_memories` excluye las filas rechazadas y con tombstone, y `sql_v1_memory_history` excluye las versiones rechazadas (conserva las que tienen tombstone), y un resumen consolidado a partir de las memorias del usuario lleva otro `user_id`, que el censo cuenta y estas consultas no. El recuento del registro de solicitudes es una comprobación aparte, fuera del recibo: una eliminación depura las filas del registro de solicitudes de un usuario a `` en lugar de borrarlas, y la vista del registro de solicitudes contiene solo su ventana ([`sql_v1_agent_events`](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md#sql_v1_agent_events)), así que confirma la depuración solo para las filas dentro de ella. Cualquier otra clave del censo es solo el recuento de Loom. + +Lo que el recibo no cubre: + +- copias de seguridad, recuperación a un punto en el tiempo, WAL y standbys de cualquiera de los dos servicios; +- copias hechas fuera de Loom, como una tabla creada en el Postgres propio de un org a partir de la [superficie SQL](https://github.com/ClickHouse/loom/blob/main/docs/reference/sql-surface.md); +- filas que un worker escribe después del censo a partir de una lectura que hizo antes ([autoridad de almacenamiento](../../architecture/storage-authority.md#erasure)); +- un `namespace.restore` desde una instantánea tomada antes de la eliminación, que recupera filas: ejecuta la eliminación de nuevo, y su censo es el nuevo recibo; +- para un alcance de usuario, los originales de documentos en el bucket, que el censo cuenta solo para un alcance de espacio de nombres. + +El id eliminado permanece donde la prueba de eliminación lo necesita: en la fila del registro (hasta que el TTL de la tabla la descarta, 90 días después de la solicitud), en la auditoría, en `loom.erasure_reversals` y en los logs propios del despliegue de las sentencias que lo nombraron (el log de mutaciones de ClickHouse, `system.query_log` y `system.text_log` para una sentencia que lo escribió, y los logs de sentencias de Postgres con `log_statement` o `log_min_duration_statement` activados). + + + +### Sagas abandonadas + +Tras 5 intentos el worker marca la solicitud como `failed` de forma definitiva y escribe una fila de auditoría `erasure.abandoned`, con `failure_reason` y `steps_completed`. Entonces una persona debe escalar el caso. `loom erasure-re-verify` vuelve a comprobar las sagas terminales; `--resume` vuelve a ejecutar las fallidas desde su punto de control (`--skip-external` para una saga `namespace_list` cuyo paso externo sigue fallando). `--completed-since ` vuelve a comprobar las sagas completadas verificadas desde entonces en lugar de las fallidas, para las eliminaciones que ejecutó una versión anterior durante una actualización; con `--resume` borra solo los vínculos de filas huérfanas ([mantenimiento](https://github.com/ClickHouse/loom/blob/main/docs/operations/maintenance.md#erasure)). Consulta la [resolución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md). + + + +### Operaciones + +| Op | Rol | Qué hace | +| ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `erasure.request` | writer (admin sobre el destino) | Ejecuta la saga para un alcance. `urgency` `normal` o `urgent`; `purge`; `external`. | +| `erasure.status` | viewer | El estado de una solicitud, el paso actual, el motivo del fallo y el censo. La eliminación de un usuario solo la responde un admin del org o un admin de plataforma de su org. No figura en los toolsets de MCP. | +| `erasure.list` | viewer | Solicitudes recientes (filtra por `status`), con `steps_completed_count`, `reversals_count`, `residue_count`. | +| `erasure.export` | admin | Los datos de un sujeto como JSON: `memory`, `knowledge`, `conversations` (turnos de transcripción y mensajes guardados), `conversation_threads`, `agent_events`, `audit_log`, cada uno limitado por `section_limit` (por defecto 10,000; `truncated` si se supera), y `conversations` también por `LOOM_ERASURE_EXPORT_CONVERSATION_MAX_BYTES` de texto. Incluye por defecto las filas con tombstone. | + +`erasure.status` y `erasure.list` leen una fila del registro durante 89 días; el TTL de la tabla la descarta a los 90. Listas de campos: [referencia de operaciones](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md#erasure). + + + +### Ejemplo + +```python +from loom import Agent + +async with Agent(org="acme", namespace="support", agent="privacy-desk") as admin: + out = await admin.erasure.request_user_id("u-42", requester="dpo@acme.example") + print(out["status"], out["residue_count"], out["verified_at"]) + if out["status"] != "completed": + print(out["failure_reason"], out["residue"]) +``` + +El `request` del SDK no expone `purge` ni `external`; envíalos por HTTP: + +```bash +curl -sX POST "$LOOM_BASE_URL/v1/erasure.request" \ + -H "Authorization: Bearer $LOOM_API_KEY" -H "Content-Type: application/json" \ + -d '{"org":"acme","scope_type":"namespace_list", + "scope_value":"[\"bench-a\",\"bench-b\"]", + "requester":"ops@acme.example","purge":true,"external":false}' +``` + + + +### Para colaboradores + +Una tabla nueva que pueda contener contenido de memoria necesita un paso de la saga y una entrada del censo (un `Substrate(...)` en `server/erasure/store/census.py` `_CENSUS`), o una línea en `STEP_ONLY_TABLES` con su motivo; si no, falla una prueba unitaria. La saga es `server/erasure/app/saga.py` (`run_saga`), los backends `server/erasure/app/backends.py`, el worker `server/erasure/workers/recovery.py`. + + + +## Límites + +- **No es una garantía de cumplimiento normativo.** La saga, el censo y los hashes de auditoría son primitivas de ingeniería; que cumplan o no una obligación es decisión tuya. +- **Un borrado es lento.** Cada paso espera a una mutación; calcula varios minutos en un ámbito grande. El SDK espera hasta 120 segundos la primera respuesta; después de eso, consulta periódicamente `erasure.status`. +- **No existe el ámbito `org`.** Borra los espacios de nombres de una organización con `namespace_list`. +- **No se puede restaurar desde los TTL de tabla.** Usa la expiración definida por el escritor con `on_expire` cuando el fin de vida deba ser reversible. +- **Las copias de seguridad quedan fuera de la saga**; consulta + [copia de seguridad y recuperación](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md). +- **El bucket de exportación de analítica queda fuera de la saga.** Sus archivos contienen nombres hasheados de organización, espacio de nombres y agente, y recuentos de uso, nunca contenido de la memoria; consulta + [nombres hasheados](https://github.com/ClickHouse/loom/blob/main/docs/operations/analytics-export.md#hashed-names). + + + +## Relacionado + +- [Historial y procedencia](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/history-and-provenance.md): `memory.history`, `memory.redact`. +- [Escritura de memoria](https://github.com/ClickHouse/loom/blob/main/docs/features/memory/writing.md): `ttl_seconds`, `valid_to`, `on_expire` en una escritura. +- [Ejecuciones](https://github.com/ClickHouse/loom/blob/main/docs/features/runs.md): `retain` en `run.complete`. diff --git a/i18n/.pending/es/docs/operations/postgres.md b/i18n/.pending/es/docs/operations/postgres.md new file mode 100644 index 0000000000..52fcb9b963 --- /dev/null +++ b/i18n/.pending/es/docs/operations/postgres.md @@ -0,0 +1,246 @@ + +> Esta página es una traducción automática de la [página en inglés](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md), que prevalece. +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/postgres.md), which is authoritative. + + + +# Autoridad de memoria en Postgres + +Esta guía configura un despliegue de Loom cuyas memorias activas y cabeceras de documentos de conocimiento se almacenan en Postgres, ya sea en ClickHouse Managed Postgres o en un Postgres autoalojado, y explica qué comprobar antes de ponerlo en servicio. El funcionamiento interno se describe en [autoridad de almacenamiento](../architecture/storage-authority.md). + +La autoridad se elige una sola vez, en el primer arranque de un despliegue. Un ClickHouse que ya contiene memorias conserva la autoridad de ClickHouse; inicie un despliegue con Postgres sobre un ClickHouse vacío. + + + +## Requisitos + +- Postgres 16 o superior. No se necesita ninguna extensión. +- Una base de datos y un rol que sea su propietario (Loom crea en ella el esquema `loom`). +- El rol puede ejecutar `pg_logical_emit_message` (por defecto el público puede; de lo contrario, el arranque se rechaza y nombra el `GRANT`). +- Para `LOOM_PG_DURABILITY=synchronous` (el valor por defecto): al menos un standby síncrono + en otro dominio de fallo, de modo que una escritura confirmada sobreviva a la pérdida del primario. +- `wal_level = logical` si la base de datos también alimentará una herramienta de replicación; Loom en sí + no lo necesita. + + + +## Configuración + +| Ajuste | Valor | +| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `LOOM_STORAGE_AUTHORITY` | `postgres` | +| `LOOM_PG_DSN` | `postgres://loom:@:5432/?sslmode=verify-full&sslrootcert=`, el endpoint directo, nunca un pooler de transacciones | +| `LOOM_PG_POOL_MIN_SIZE`, `LOOM_PG_POOL_MAX_SIZE` | conexiones por proceso de Loom (2 y 20); dimensione `max_connections` para cada proceso de cada réplica | +| `LOOM_PG_DURABILITY` | `synchronous` (se niega a iniciar sin un standby síncrono) o `local` | + +Indique la autoridad de certificación del servidor y exija `sslmode=verify-full`: +comprueba el certificado y el nombre del host, de modo que nada en la ruta pueda +hacerse pasar por la autoridad ni leer la memoria o la contraseña. `require` y los +modos inferiores cifran sin comprobar con quién se habla, y son solo para un servidor +de desarrollo local. + +Loom gestiona su propio pool de conexiones. Apunte `LOOM_PG_DSN` más allá de cualquier +pooler que entregue al cliente una conexión de servidor distinta por transacción +(transaction pooling): las migraciones de Loom mantienen un bloqueo advisory de sesión +y su driver prepara sentencias, y un pooler de ese tipo no conserva ninguna de las dos +cosas entre transacciones. El `LOOM_PG_DSN` de una [celda](../architecture/cells.md) +apunta directamente a Postgres, sin ningún pooler de ningún modo: sus procesos marcan +cada sesión con el parámetro de inicio `loom.tenancy_checked`, que un pooler de sesión +rechaza o descarta (entonces sus triggers de org rechazan las escrituras del propio +Loom para una org de la que la celda no tiene ninguna fila, y la protección +`loom.tenancy` rechaza su fila de tenencia para cada org recién asignada), y +`loom doctor` señala la sesión que lo perdió. Los scripts y los cargadores masivos +nunca deben establecer `session_replication_role = replica` en una celda: omite los +triggers de org y la protección. + +Todas las réplicas del despliegue, y su proceso worker, usan los mismos valores. La +lista completa, con los ajustes de admisión y de entrega, está en la +[referencia de configuración](https://github.com/ClickHouse/loom/blob/main/docs/reference/configuration.md). + + + +## Postgres administrado de ClickHouse + +1. Crea el servicio con **dos standbys de HA**. Con un solo standby el servicio replica de forma asíncrona, y una escritura confirmada se puede perder junto con el primario. +2. Crea la base de datos y el rol, concede al rol `pg_read_all_stats` para que Loom pueda ver qué standbys están conectados, y toma la cadena de conexión **directa**, en el puerto 5432, de los detalles de conexión del servicio, no la del pooler: el pooler del servicio funciona en modo de transacción. +3. Define los [ajustes](#settings) e inicia Loom. Comprueba que `GET /v1/health?include=postgres` informe `postgres.standby` `synchronous`: el arranque rechaza un `synchronous_standby_names` vacío y emite una advertencia cuando hay menos standbys conectados de los que nombra ([qué comprueba el arranque](#what-the-boot-checks)). + +La conmutación por error, la ubicación de los standbys y el aislamiento del antiguo primario son responsabilidad del servicio. En Kubernetes, los valores `postgres` del chart definen los [ajustes](#settings) ([ClickHouse Cloud y Postgres administrado](https://github.com/ClickHouse/loom/blob/main/docs/operations/clickhouse-cloud.md)). + + + +## Postgres autoalojado + +Ejecute Postgres bajo un gestor de HA que mantenga un standby síncrono, aísle (fence) al primario anterior en la promoción y promueva solo un standby que contenga todos los commits confirmados. +Configúrelo en su modo síncrono estricto: se requiere al menos un standby síncrono, y las escrituras se rechazan en lugar de ser confirmadas solo por el primario cuando no hay ninguno conectado. Un gestor que no es estricto vacía `synchronous_standby_names` cuando su standby se desconecta, y entonces el primario confirma los commits por sí solo. + +Loom comprueba la configuración del standby al arrancar, y `GET /v1/health?include=postgres` informa `postgres.standby` mientras está en servicio: `synchronous` cuando los standbys que un commit espera (`n` de `FIRST n`, `ANY n` o `n (...)`, y si no, uno) están conectados; `primary_only` cuando no se nombra ninguno, de modo que solo el primario confirma los commits; `waiting` cuando hay menos conectados, de modo que los commits esperan hasta que lo estén; `null` cuando no se pudo leer el estado, porque Postgres no respondió o el rol no puede ver `pg_stat_replication`. + +Apunte `LOOM_PG_DSN` al endpoint primario del gestor (el servicio o la dirección que sigue al líder), nunca a un único host, de modo que una promoción mueva a Loom con ella. + +Un primario con un standby y sin gestor, como lo inicia `dev/ci_start_postgres.sh` para las pruebas, muestra la configuración: + +```text +synchronous_commit = on +synchronous_standby_names = 'FIRST 1 (loom_standby)' +``` + + + +## Qué comprueba el arranque + +| Comprobación | Se niega a arrancar cuando | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Conexión | `LOOM_PG_DSN` está vacío o Postgres no responde | +| Migraciones | se editó un archivo ya aplicado de `schemas/pg_migrations/`, o falta en esta compilación uno anterior al último aplicado | +| Durabilidad | con `LOOM_PG_DURABILITY=synchronous`, `synchronous_standby_names` está vacío; con cualquier valor, el rol no puede ejecutar `pg_logical_emit_message` | +| Autoridad | el despliegue registró la autoridad de ClickHouse, este ClickHouse contiene memoria bajo ella, o este Postgres pertenece a otro despliegue | +| Estado de la celda | falla la primera lectura de las filas de estado de la celda (`loom.cell_first`, `loom.tenancy_mode`, `loom.cell_self`, `loom.tenancy`); con migraciones de Postgres pendientes, el proceso arranca bloqueado y no listo hasta que una lectura se completa ([solución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md#a-process-with-loom_cell-unset-is-gated)) | + +Una migración espera como máximo 5 s a un bloqueo de tabla y se intenta cinco veces; un +arranque que registra `Postgres migration waited too long for a lock` cuatro +veces y después falla con `LockNotAvailableError` encontró una transacción larga que +retiene la tabla: termínela (`pg_stat_activity` la nombra) y vuelva a arrancar. Un +arranque que encuentra a otro arranque migrando lo espera, sin límite, y arranca cuando +sus migraciones terminan. + +Cada conexión de Loom establece `synchronous_commit = on` por sí misma, sea cual sea el +valor por defecto del servidor. El arranque emite una advertencia cuando hay menos +standbys conectados de los que un commit espera, y cuando su rol no puede ver +`pg_stat_replication`. Mientras no estén conectados, un commit los espera, hasta +`LOOM_PG_STATEMENT_TIMEOUT_MS` más un segundo, y luego responde 503 +`POSTGRES_UNAVAILABLE` con `outcome_unknown`: la espera cancelada deja el commit solo en +el primario. El worker de entrega lo publica en ClickHouse únicamente cuando los standbys +lo contienen, de modo que una conmutación por error intermedia no deja nada de él en +ClickHouse +([autoridad de almacenamiento](../architecture/storage-authority.md#only-durable-revisions-are-published)). +Un publicador que envía el commit de otra sesión lo vuelve a leer en una transacción que +confirma un mensaje lógico transaccional con el prefijo `loom.durable`, por lo que un +consumidor de captura de cambios de la base de datos recibe uno por cada lectura de ese +tipo; el arranque rechaza un rol que no puede escribir uno. + +`GET /v1/health` informa `storage_authority` y, con Postgres, `pg_ok`; con +`?include=postgres` también un bloque `postgres` con `standby`, `parked_deliveries`, +`parked_audits`, `parked_knowledge_deliveries` y `backlog` (las entregas pendientes y +aparcadas de cada fuente, contadas hasta `LOOM_PG_BACKLOG_COUNT_CAP`, `capped` más allá, +la antigüedad de la más antigua y la de la lectura, +[SLO del pipeline](https://github.com/ClickHouse/loom/blob/main/docs/operations/monitoring.md#pipeline-slos)), sentencias que la respuesta por defecto omite en una sonda de +liveness. `pg_ok` es false cuando una consulta en el pool de peticiones no obtuvo +respuesta en dos segundos, incluida la situación en que todas las conexiones del pool +están ocupadas. `/v1/health/ready` no espera a Postgres: una réplica que no puede +alcanzarlo sigue sirviendo los planos que no lo usan. Responde 503 +`POSTGRES_UNAVAILABLE` para las operaciones de memoria, para toda operación de knowledge +que lee la fila actual de un documento desde su cabeza o la confirma, para la búsqueda y +las lecturas que comprueban cabezas (`knowledge.search`, `knowledge.outline`, +`knowledge.synthesize`), y para las operaciones de datasets, que allí leen o confirman el +catálogo de datasets (`knowledge.dataset_get`, `knowledge.dataset_approve`, +`knowledge.query`). Las operaciones de knowledge que leen o escriben solo en ClickHouse, +como `knowledge.list` y `knowledge.dedup_resolve`, siguen sirviendo. +`knowledge.ingest`, `knowledge.ingest_status` y `knowledge.ingest_cancel` también +responden 503, ya que cada una lee o confirma su trabajo allí (`loom.knowledge_jobs`); una +ejecución detenida por una caída cuenta ese intento y se ejecuta de nuevo cuando Postgres +responde. + +`parked_deliveries` cuenta cada entrega de memoria con un arrendamiento sin fin: +revisiones confirmadas en Postgres que ClickHouse rechazó `LOOM_PG_DELIVERY_MAX_ATTEMPTS` +veces, las versiones reemplazadas cuyo payload borrado no dejó nada que enviar (abajo), y +las entregas que `loom reconcile` retiene (`last_error` `held by loom reconcile`) hasta +que las libera. Una cuyo `targets` no contiene ninguno de 1, 2 y 4 tiene su fila de +memoria en ClickHouse (también su documento de búsqueda cuando le corresponde), su fila de +auditoría allí o en `loom.audit_outbox`, y solo debe retiradas: 8, el registro de su +decisión eliminada, que `decision.chain` sigue sirviendo hasta que se retira; 16, los +vectores de la versión que reemplazó, que la búsqueda sigue encontrando hasta que se +retiran (para una fila `high`, su valla oculta mientras tanto los vectores del modelo en +servicio). Una que agotó sus intentos no se reintenta; su `last_error` en +`loom.memory_deliveries` contiene el tipo del error y su código de ClickHouse, estado HTTP +o SQLSTATE de Postgres, nunca su texto, que podría citar la memoria. Esta sentencia +reintenta una (nunca una retención de reconcile, que `loom reconcile` libera por sí +mismo): + +```sql +UPDATE loom.memory_deliveries SET attempts = 0, held = false, lease_until = now() WHERE … +``` + +Una vez que se ha ejecutado la pasada de [borrado de payloads](../architecture/storage-authority.md#payload-clearing), +una compilación sin `010_revision_delivered_at.sql` no puede enviar una revisión cuyo +payload fue borrado: mientras esa compilación sirve, un reintento las excluye, añadiendo +esto a su `WHERE` (una sonda de clave primaria por entrega): + +```sql +AND NOT EXISTS (SELECT 1 FROM loom.memory_revisions r + WHERE r.org = memory_deliveries.org + AND r.namespace = memory_deliveries.namespace + AND r.seq = memory_deliveries.seq + AND r.row IS NULL) +``` + +Una publicación que termina el proceso del worker (falta de memoria con un valor enorme) +cuenta como un intento cuando la siguiente pasada toma su reclamo (`last_error` +`stopped mid-publish`): al llegar al límite la revisión se aparca o, cuando lo único que +aún debe es su documento de búsqueda, recibe un stub que el worker de embeddings rellena. + +Una publicación que supera el plazo de sentencia de ClickHouse cuenta como fallo propio de +las filas, ya que ClickHouse aún responde: tras una ralentización que aparcó revisiones +sanas, la sentencia de reintento anterior con `WHERE attempts >= …` las reintenta todas. + +Una aparcada con `last_error` `payload cleared, nothing to send` es una versión cuyo +payload borró la pasada de [borrado de payloads](../architecture/storage-authority.md#payload-clearing) +y que una versión posterior de su clave ha reemplazado: ClickHouse sirve la cabeza de la +clave, y el contenido de esa versión ya no existe (una restauración que omitió el +[procedimiento operativo](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md#the-postgres-journal-and-a-clickhouse-restore)). Su fila de +auditoría tampoco se envía de nuevo: permanece en el `audit` de la revisión en +`loom.memory_revisions`. Reintentar la entrega no puede tener éxito; una vez anotada, +elimine su fila: + +```sql +DELETE FROM loom.memory_deliveries +WHERE lease_until = 'infinity' AND last_error = 'payload cleared, nothing to send'; +``` + +El worker de entrega de knowledge publica una entrega a la vez, cada retirada por +separado: hasta dos inserciones por entrega y `LOOM_PG_DELIVERY_BATCH_ROWS` entregas por +pasada, dentro de un arrendamiento de `LOOM_PG_DELIVERY_LEASE_SECONDS`, que con un backlog +suele terminar la pasada antes. Una pasada que el fin del arrendamiento interrumpe libera +el resto sin contarlo, y la siguiente pasada las toma. + +`parked_knowledge_deliveries` cuenta los documentos de knowledge confirmados en Postgres +cuya fila de `loom.documents` ClickHouse rechazó `LOOM_PG_DELIVERY_MAX_ATTEMPTS` veces: la +cabeza sirve `knowledge.get` y la búsqueda, que omite los fragmentos de la versión +anterior que ClickHouse lee como vigentes hasta que se ejecuta la retirada de la entrega +([búsqueda de knowledge](../architecture/storage-authority.md#knowledge-search)). La +retirada de un borrado aparcado se ejecuta antes que su fila: `knowledge.get` lo responde +como borrado, la búsqueda no sirve ninguno de sus fragmentos, y `knowledge.restore` +responde 503 mientras una publicación de la fuente aún pueda llegar: hasta que la entrega +aterriza, y durante el límite de inserción después. El barrido de originales conserva el +original que nombra un documento vigente aparcado, y también lo hace el borrado de un +usuario distinto de su autor. Su `last_error` en `loom.knowledge_deliveries` contiene el +tipo y el código del error. Una entrega de un alcance que una compilación anterior borró +durante una actualización progresiva no se reintenta: ejecute primero ese borrado de nuevo +([actualizaciones progresivas](../architecture/rolling-upgrades.md)). Esta sentencia +reintenta una: + +```sql +UPDATE loom.knowledge_deliveries SET attempts = 0, lease_until = now() WHERE … +``` + +`parked_audits` cuenta las filas de `loom.audit_outbox` que ClickHouse rechazó el mismo +número de veces, dejadas allí con su `last_error`: las filas de auditoría de un borrado, y +las que un reclamo aplazó porque el titular al que reemplazó aún puede insertarlas. Esta +sentencia reintenta una: + +```sql +UPDATE loom.audit_outbox SET attempts = 0, due_at = now() WHERE … +``` + + + +## Actualizaciones continuas y rollback + +Cada réplica debe ejecutar una compilación que registre la autoridad. Un despliegue de la autoridad de Postgres no puede volver a una compilación que no la incluya: dicha compilación no lee ningún registro y escribe en `loom.memory` directamente ([actualizaciones continuas](../architecture/rolling-upgrades.md)). + + + +## Copia de seguridad + +Haz la copia de seguridad de Postgres con las herramientas del proveedor o del gestor, y la de ClickHouse con las suyas. Una restauración es de un solo almacén, seguida de `loom reconcile`, que vuelve a ejecutar en él lo que el otro almacén registró después del punto de restauración ([restaurar un solo +almacén](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md#restoring-one-store)). Un Postgres de otro despliegue se niega a iniciar. diff --git a/i18n/.pending/ja/docs/operations/backup-and-recovery.md b/i18n/.pending/ja/docs/operations/backup-and-recovery.md new file mode 100644 index 0000000000..995881e2d0 --- /dev/null +++ b/i18n/.pending/ja/docs/operations/backup-and-recovery.md @@ -0,0 +1,261 @@ + +> このページは[英語の原文](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md)の機械翻訳です。内容は英語の原文が優先されます。 +> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/operations/backup-and-recovery.md), which is authoritative. + + + +# バックアップとリカバリ + +Loom のバックアップは ClickHouse のバックアップです。カタログのいずれかの行がドキュメントバケット内のオブジェクトを指している間は、そのバケットも対象に含めます。Postgres をオーソリティとして使う場合は、Postgres のバックアップも必要です。 +ClickHouse には、元ドキュメントのカタログ(`loom.document_blobs`。デフォルトのストアではそのバイト列も)、トークンの署名鍵(`loom.signing_keys`)、管理者のランタイムオーバーライド(`loom.runtime_overrides`)が保存されています。次のものは ClickHouse の外にあります。 + +- `LOOM_JWT_SECRET`:ルートシークレットです。保存された認証情報と署名鍵を暗号化しているため、これなしで復元したバックアップでは、どちらも開けません。env 設定とともに保管してください。 +- `var/code_repos` 配下のコードインデックスの git ミラー:ClickHouse に記録されたリモートのキャッシュです。ミラーのないホストは、再度クローンします。 +- `LOOM_DOCUMENT_S3_BUCKET`:`LOOM_DOCUMENT_OBJECT_STORE=s3` の間に書き込まれた元ドキュメントのバイト列を保持します(設定を戻しても、バイト列はそこに残ります)。各オブジェクトの場所は ClickHouse が保持します。 + + + +## バックアップの選び方 + +| 方法 | 対象 | 一貫したスナップショット | 用途 | +| ----------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | +| ClickHouse Cloud のバックアップ | サービスのすべてのテーブル | あり(サービス単位) | Cloud でのディザスタリカバリ | +| `BACKUP DATABASE loom TO Disk(...)` / `S3(...)`、または `clickhouse-backup` | すべての `loom.*` テーブル | あり | セルフマネージドの OSS でのディザスタリカバリ | +| `BACKUP DATABASE loom_telemetry TO ...` | SLI ロールアップ(`loom_telemetry.sli_minute`) | あり | 台帳の再フォールドで復元できる 31 日を超えて SLO 履歴を保持する | +| `dev/backup_loom.py` ポータブルダンプ | すべての Loom テーブル(下記) | テーブルごと。テーブル間ではなし | デプロイメント、組織、名前空間の移行(元データはバケット内:[下記](#the-portable-dump))、コールドコピー | +| `namespace.snapshot` | 1 つの名前空間のキュレーション済みメモリ、型、権限付与、監査ログの末尾 | 1 回の呼び出し | API 経由での名前空間のコピーまたは凍結 | + + + +## ポータブルダンプ + +`dev/backup_loom.py` はテーブルごとに 1 つの `JSONEachRow` ファイルを書き出し、続いて `manifest.json` を書き出します。manifest には元のデータベースと、テーブルごとのファイル、行数、バイトサイズ、SHA-256、`CREATE` 文(失敗した場合は停止の原因となったエラー)が記録されます。終了コード 1 はテーブルの失敗(`complete: false`)を、終了コード 2 は不正な引数、ClickHouse の接続先がないこと、または出力先ディレクトリに既にバックアップがあることを表します。 + +データベースのすべての MergeTree ファミリーのテーブルを `system.tables` から読み取ってダンプします。マイグレーションランナーの `_` で始まるテーブル、`.inner` テーブル、KeeperMap のリース(データではなくライブの協調状態)、および `loom migrate` が作成するビューは対象外です。manifest の `backup_version` は 3 です。`--org` は `org` 列を持つすべてのテーブルを絞り込み、その列を持たないテーブル(`idempotency`、`signing_keys` など)はスキップします。これらのテーブルにはすべての org の行が入っています。 + +`dev/restore_loom.py` は、すべてのファイルを manifest と照合して検証し(サイズ、行数、SHA-256)、計画を表示し、記録された `CREATE` 文から対象のデータベースと不足しているテーブルを作成します。その後、各ファイルをそのテーブルのステージングコピーに読み込み、ステージされたパーツをテーブルにアタッチします。アタッチではマテリアライズドビューが発火しないため、復元された行は、バックアップが同じく復元するテーブルに再度コピーされません(そうでなければ `memory_versions` はすべてのバージョンを 2 重に保持します)。また、ビューはライブデータベースへの書き込みに対しては動作し続けます。復元先は、`loom migrate` が準備したデータベース(ビューが存在する)か、スクラッチデータベース(テーブルは記録された DDL から作成される)にしてください。コード化されたベクトルテーブル(記録された `CREATE` に `Quantized(` を含む)を持つバックアップは、何かを書き込む前に拒否されます(`--dry-run` も同様)。これは、復元先のコーデック設定を読み取れない場合、または `enable_quantized_codec` を有効にできない場合です。有効にできる場合でも、`allow_suspicious_codecs` を有効にできないときは、テーブルから `Quantized` の後の汎用コーデックが外されます([制限付き設定](https://github.com/ClickHouse/loom/blob/main/docs/architecture/clickhouse.md#gated-clickhouse-settings))。挿入は `optimize_on_insert = 0` で実行されるため、`ReplacingMergeTree` キーの重複を含め、ダンプされたすべての行が書き込まれ、テーブルは自身のマージで重複をまとめます。各テーブルは、アタッチの前に `… attaching
` を、後に `✓` を表示します。実行が途中で打ち切られた場合、最後の行がそのときのテーブルを示します。`--into-nonempty` で再実行する前に、そのテーブルの件数を確認してください。再実行すると同じ行が再び追加されます。 + +manifest には、挿入で発火する各マテリアライズドビューのソーステーブルとターゲットテーブルが記録されます。アタッチではビューが発火しないため、復元は、ビューの片方の端だけを含む選択を拒否します。`memory` を `memory_versions`(および `memory_code_link_queue`)なしで復元すると、`memory.history`、`memory.redact`、`namespace.rollback` が復元されたバージョンを認識できなくなります。`code_term_freq` を `code_chunks` なしで復元すると、コードの再取り込み時に再び埋められることになります。`documents` と `document_blobs` を結ぶビューはありませんが、復元は片方だけの選択も拒否します。原本のない documents は、ダウンロードのたびに 410 を返します。documents のない原本は、原本スイープが削除する対象です。両ツールは `documents` を他のどのテーブルよりも先に処理するため、`--into-live` でワーカーが動いていても、スイープは、それを参照する document より先に復元された原本の行を見ることがありません(バケットのオブジェクトについては後述)。両方の端を選択するか、復元先に既に行がある場合は `--allow-view-split` を渡してください。`dev/backup_loom.py --exclude t1,t2` は、パスが再構築するテーブルと、ビューがそれらから埋めるすべてのテーブルを除外します(`code_chunks` を除外すると `code_term_freq` と `code_doc_stats` も除外されます)。`restore_loom.py --exclude` はバックアップのテーブルを除外します。 + +ドキュメントの原本(`document_blobs`)はバイナリです。ダンプはそれを生のバイト列として書き出し、`output_format_json_validate_utf8 = 0` を自身で設定するため、UTF-8 を検証するプロファイルでも置き換えられることはありません。バイナリの原本は、ダンプ内で元のサイズの約 1.6 倍になります。 + +`LOOM_DOCUMENT_OBJECT_STORE=s3` で書き込まれた行にはオブジェクトの場所だけが入り、バイト列はバケットにあります。バケットは、そのバケット自身のバージョニングまたはレプリケーションでバックアップしてください。復元は、オブジェクトを参照する ClickHouse バックアップの後に、同じ名前のバケット(各行がその名前を保持しています)へ行うか、両方が戻るまで `LOOM_DOCUMENT_BLOB_GC_ENABLED=false` にして行います。復元されたオブジェクトは古い更新時刻を保持することがあり(復元方法に依存します)、その場合、バケットの走査は、`document_blobs` の行がまだ反映されていないオブジェクトをすべて削除してしまいます。 + +バージョニングされたバケットは、削除されたオブジェクトをすべて非現行バージョンとして保持し、レプリケーションは既定では削除をレプリケートしません。そのため、消去およびスイープされた原本は、ライフサイクルルール(`NoncurrentVersionExpiration`、およびレプリカ側の有効期限)が削除するまで、バケット(またはそのレプリカ)に残ります。このルールの期間が、消去された原本をまだ復元できる期間であり、これは ClickHouse バックアップの保持期間が行に対して持つ意味と同じです。 + +ダンプにはこのような行の原本のバイト列が含まれないため、移行できません。別のデプロイメントに復元された行は元のバケットを指したままで、その消去はバケットとプレフィックスの外にあるものとして拒否され、元のデプロイメントのスイープは、元の行がなくなるとオブジェクトを削除します。また、元のバケットとプレフィックスを指すターゲットは、そのカタログが参照していない元のオブジェクトをすべてスイープしてしまいます。移すには、ターゲットにドキュメントを再アップロードするか、元を停止してデプロイメント全体を移動してください。 + +ステージングコピーはテーブルのエンジンを繰り返しますが、`Replicated` ではないデータベース内のレプリケートエンジンは、同じパラメータのローカル形式になります(コピーがテーブルの Keeper パスを再び要求してしまうためです)。その後、アタッチによってパーツがレプリケートされます。復元が作成するレプリケートテーブルは、記録された Keeper パスを、バックアップ元と同じデータベースでのみ、かつそのパスでレプリケートしているものが他になくなった後でのみ保持します(ライブのレプリカが残っている間は拒否されます)。別のデータベースでは独立したパスになります。サーバーの `default_replica_path` の下に新しい UUID を付けたもの、または Replicated データベースではそのデータベース独自のパスです。その既定値に必要なマクロがサーバーにない場合は拒否されます。 +各実行は、ステージングテーブルを `_restore__
` と名付け、最初に run id を表示し、自分のものだけを削除します。1 つのデータベースへの復元(たとえば 2 つの org)は 1 度に 1 つずつ実行されます。実行は `default._loom_restore_lock_` を要求し(他の実行の要求を最大 5 分待ちます)、ターゲットをもう一度調べ、前の実行が残したものに以下の拒否を適用します。そのため、同じスコープの 2 回目の復元は、最初の行に折り込まれてしまう行をアタッチせずに、拒否されます。この要求は `default` 内のテーブルなので、セルフマネージドクラスタでは同じサーバー経由の実行の順序づけだけを行います。すべての復元を 1 台に向けてください。クラッシュした実行は、ステージングテーブルと要求を残します。その実行のプロセスが残っていなければ、`restore_loom.py --database --drop-staging ` で削除できます。 +挿入のステップより前には何も書き込まれません。`--dry-run` は計画の後で停止します。次のものは拒否されます。 + +- `--into-live` なしでのライブデータベース(`loom`、またはサーバー設定が指定するデータベース) +- `--into-nonempty` なしでの、バックアップのスコープ内で既に行を持つテーブル。挿入は追記なので、通常の MergeTree テーブル(`audit_log`、`agent_events`)はすべての行を 2 重に保持することになります。 + +両ツールはサーバーと同様に ClickHouse の接続先を解決し(環境変数または `.env` の `LOOM_CH_*`。それぞれ `--host`、`--port`、`--user`、`--database`、`--secure` で上書きできます)、ホストが指定されていない場合は実行を拒否し、パスワードは `LOOM_CH_PASSWORD` からのみ読み取ります。 + +```bash +python dev/backup_loom.py --out-dir ./backups/$(date +%F) [--org acme] [--tables memory,namespaces] +python dev/restore_loom.py --in-dir ./backups/ --database loom_restore --dry-run +python dev/restore_loom.py --in-dir ./backups/ --database loom_restore --skip-idempotency +python dev/restore_loom.py --in-dir ./backups/ --into-live \ + --tables memory,memory_versions,memory_code_link_queue # one end of a view needs the other +./scripts/ops/backup_drill.sh [--full-restore] # round-trip check into a scratch database +``` + +`scripts/ops/backup_drill.sh` はライブデータベースを一時ディレクトリにダンプし、manifest を行数のスナップショットと照合します。`--full-restore` を付けるとスクラッチデータベース `_drill` に復元し、すべてのテーブルの行数を比較し、終了時にスクラッチデータベースを削除します。同じキーの行をまとめるテーブル(`ReplacingMergeTree`、`AggregatingMergeTree` など)は、アタッチの直後にスクラッチデータベース内でマージされることがあります。そこでの行数の減少は、マージが実行された後なら警告、そうでなければ失敗です。このスクリプトはライブデータベースを読み取るだけです。ドリルは定期的に実行してください。 + +ダンプはテーブルごとのもので、テーブル間のスナップショットではありません。クラスタ間でデータを移すために使い、ディザスタリカバリには使わないでください。 + + + +## リストア後の監査ログの検証 + +`python dev/verify_audit_chain.py [--org X] [--ts-since YYYY-MM-DD] [--json]` は、すべての `audit_log` 行のコンテンツハッシュを再計算します。不一致があれば終了コード 1 で終了し、検証を実行できなかった場合(不正な引数、対象なし、クエリの失敗)は 2、それ以外は 0 で終了します(行が 0 件の場合も成功として扱います)。不一致のレポートでは、行をパーティション、タイムスタンプ、リクエスト ID で示し、アクター、サブジェクト、名前空間は示しません。`audit_verifier` ワーカーは、同じ行単位のチェックをスケジュールに従って実行します。このチェックは行単位の改ざん検出であり、行にわたるハッシュチェーンではありません。1 時間ごとのチェックポイントは別途チェーンされています([監査](https://github.com/ClickHouse/loom/blob/main/docs/features/observability/audit.md))。 + + + +## 名前空間内の変更の取り消し + +これらの操作は、誤った書き込み、誤動作したエージェント、誤ったインポートを、ClickHouse のリストアなしで取り消します。いずれも 1 つの名前空間を対象とします。`namespace.snapshot`、`namespace.restore`、`namespace.rollback` は MCP の `all` 一覧に含まれません。名前を指定するか HTTP 経由で呼び出すか、[ダッシュボード](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md)の Health → Repairs タブを使用してください。このタブでは、名前空間の管理者がスナップショットのダウンロード、リストア、ロールバックを行えます。 + +| 操作 | ロール | 内容 | +| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `memory.restore` | `WRITER` | トゥームストーン化された 1 つのキーを元に戻します | +| `namespace.snapshot` | `ADMIN` | 名前空間のメモリ、型、グラント、監査ログの末尾(`include_audit_tail_n`、デフォルトは 1000)を JSON ペイロードとして固定します。`include_embeddings=false`(デフォルト)の場合、ターゲット側は自身のモデルで再埋め込みを行います | +| `namespace.restore` | 新規ターゲットでは `VIEWER`、既存ターゲットでは `ADMIN` | スナップショットのペイロードを `target_namespace` に書き込みます(任意で `rebind_agent` を指定できます)。`snapshot_id` により冪等です。行は `version`、`content_sha256`、およびアテステーションのカラムを保持するため、`verified_by` は残ります。カラムに格納できない値(UUID ではないメモリ ID など)がペイロードにある場合は 422 で拒否されます。コレクションは拒否されます。そのスナップショットは通常の名前空間にリストアします | +| `namespace.rollback` | `ADMIN` | すべてのメモリヘッド(または `memory_keys`)を `as_of` 時点のバージョンに戻します。古いバージョンを新しいヘッドとして復元し、それ以降に作成されたキーはトゥームストーン化します。デフォルトはドライランです(適用するには `dry_run=false`)。1 回の呼び出しで処理するのは最大 `max_keys` 件です(再度呼び出すべきかどうかは `truncated` が示します) | + +Postgres オーソリティの下では、消去によってターゲットから削除されたメモリは、その[削除エビデンス](../architecture/storage-authority.md)が保持されている間、リストアの対象から除外され、`counts.erased_skipped` に計上されます。エビデンスは、消去によってそのメモリが削除された名前空間のみを対象とします。そのため、消去前のスナップショットを別の場所にリストアすると、消去されたメモリが復活します。そのようなリストアの後は、同じ消去(そのスコープ)を再実行してください。 + +`namespace.rollback` と `memory.history` は `loom.memory_versions` を読み取ります。これは `loom.memory` へのすべての挿入を記録する追記専用のミラーです(マージでは、置き換えられたバージョンが `loom.memory` 自体から削除されます)。ロールバックの動作は次のとおりです。 + +- 名前空間の履歴より古い、または未来の `as_of` は拒否します。 +- ハード削除されたキーはスキップします(`skipped_no_head`)。 +- 復元されたヘッドの再埋め込みは、埋め込みワーカーに任せます。 + +```bash +AS_OF=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) # GNU date; the instant before the bad writes +curl -s -XPOST http://localhost:7777/v1/namespace.rollback -H "Authorization: Bearer $ADMIN_TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{"org":"acme","namespace":"support","as_of":"'"$AS_OF"'"}' | jq '{dry_run, reinstate, remove, truncated}' +``` + + + +## Postgres を権威とする場合 + +`LOOM_STORAGE_AUTHORITY=postgres` では、ライブメモリ、そのリビジョンジャーナル、ナレッジヘッド、取り込みジョブ、データセットカタログが Postgres にあり([ストレージ権威](../architecture/storage-authority.md))、デプロイメントでバックアップすべきストアは Postgres と ClickHouse の 2 つになります。 + +| ストア | 単独で保持するもの | RPO | バックアップ手段 | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| Postgres | すべてのメモリヘッドとリビジョン、ナレッジヘッド、取り込みジョブ、データセットカタログ、冪等性の応答 | 同期スタンバイへのフェイルオーバーをまたいでも、確認応答済みの書き込みについては 0。ポイントインタイムリストアでは、そのポイント以降の内容が失われます | HA マネージャーまたはサービスのベースバックアップと WAL アーカイブ | +| ClickHouse | 検索ドキュメントとベクトル、ナレッジドキュメントおよび長いメモリ値のチャンク、Postgres が保持する範囲を超えた履歴、アナリティクス、トレース、監査行 | ClickHouse のみが保持するものについては、最後のバックアップからの経過時間。Postgres が保持するメモリリビジョンとナレッジドキュメントは再公開されますが、そのチャンクとデータセットの行は再公開されません。`loom reconcile` は再チャンク化すべき各ナレッジソースを示し、20 を超える場合はその名前空間(`loom rechunk`)を示し、あわせて再取り込みすべき各ソースを示します。長いメモリ値は、再設定されるまで抜粋で検索可能です | 上記の方法 | + +リストアの復旧時間は、ストア自体のリストア時間に `loom reconcile` の実行時間を加えたものです。この実行は、リストアされたストアが失った、もう一方のストアの記録を再実行します。 + + + +### 片方のストアのリストア + +`LOOM_PG_PAYLOAD_CLEAR_ENABLED` を有効にした状態で ClickHouse をリストアする前に、ペイロードのクリアを停止し、[Postgres ジャーナルと ClickHouse のリストア](#the-postgres-journal-and-a-clickhouse-restore)の説明に従ってバックアップを選んでください。クリア処理が一度でも実行された場合は、手順 3 の `loom reconcile` を `010_revision_delivered_at.sql` を含むビルドで実行し、手順 4 でもそのビルドでデプロイメントを起動してください(ローリングアップグレードの[ルール 43](../architecture/rolling-upgrades.md#the-rules))。そのうえで次を行います。 + +1. デプロイメントのすべてのサーバーとワーカーを停止します。 +2. バックアップからストアをリストアし、バックアップ自体のメタデータからバックアップ時刻を控えます(ClickHouse では `BACKUP` の開始時刻、Postgres ではリカバリターゲット)。 +3. `loom reconcile --restored clickhouse --point