As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Adicionar uma tabela ou coluna do ClickHouse
O estado do ClickHouse no Loom são tabelas nos bancos de dados loom e loom_telemetry; sob a autoridade de memória do Postgres, a memória ativa, o estado de conhecimento e os registros associados ficam no Postgres. A página autoridade de armazenamento lista as tabelas do Postgres. O schema do ClickHouse muda apenas por meio de migrations numeradas e aditivas, porque duas builds servem o mesmo schema durante um deploy. Cada regra abaixo é garantida por um teste. ClickHouse explica as famílias de tabelas.
flowchart TD
A["schemas/migrations/NNN_name.sql"] --> B["make migrate<br/>(local ClickHouse)"]
B --> C["make schema-dump<br/>schemas/schema.sql"]
C --> D{"table holds memory content?"}
D -->|yes| E["erasure saga step<br/>+ _CENSUS row"]
D -->|derived, no read path| F["STEP_ONLY_TABLES"]
D -->|no| G["NO_MEMORY_CONTENT + reason"]
C --> H{"column on loom.memory / shared / memory_embeddings?"}
H -->|yes| I["row builders + memory_versions mirror"]
1. Escreva a migration e regenere o schema
Migrações define as regras: numeração, o que conta como aditivo, diretivas do runner, reconstruções da chave de ordenação e make schema-dump / make schema-check contra o ClickHouse fixado. Em resumo:
- Adicione
schemas/migrations/<NNN>_<what>.sqlcom o próximo número livre. O comentário do cabeçalho diz para que serve a mudança e o que as linhas antigas e as builds antigas enxergam. - Referencie as tabelas como
loom.<table>e escrevaIF NOT EXISTS/IF EXISTS. A telemetria derivada das tabelas do próprio Loom vai emloom_telemetry(por quê); o preflight já verifica as permissões dela, e o censo de apagamento nomeia a tabela junto com seu banco de dados. - Nunca edite nem apague uma migration já mergeada. Corrija um erro com um novo arquivo.
- Execute
make migrate,make schema-dumpe depoispython scripts/codegen/docs_reference.pypara que a referência do schema liste a tabela.
Até que um deployment aplique a migration, a proteção de schema do cliente recusa uma leitura ou escrita que cite uma tabela que uma migration pendente criaria, com SCHEMA_PENDING.
2. Espelhe todas as colunas nos caminhos de escrita do ReplacingMergeTree
loom.memory, loom.shared e loom.memory_embeddings são tabelas ReplacingMergeTree(version) lidas com FINAL. Todo handler que grava uma nova linha de versão (set, tombstone, restore, touch, update_by_id, bulk_set, promote, demote) carrega todas as colunas persistidas para a frente. Uma coluna omitida em uma versão posterior é lida como zero com FINAL.
Ao adicionar uma coluna a uma dessas tabelas:
- Adicione-a à lista canônica de colunas em
server/memory/store/rows.py(MEMORY_PERSISTED_COLSouEMBEDDING_PERSISTED_COLS). - Inclua-a nos builders desse arquivo (
build_memory_version_row,build_revision_row,build_first_version_row,build_embedding_row) e em toda projeção que os alimenta (oSELECTque carrega a linha existente). - Nunca monte uma linha de versão manualmente em um handler; chame os builders.
tests/unit/test_memory_write_path_mirror.py e tests/unit/test_embedding_mirror_carry.py verificam os caminhos de escrita secundários.
O espelho do histórico. loom.memory_versions é um gêmeo somente de acréscimo (append-only) de loom.memory, preenchido pela view materializada memory_versions_mv. memory.history, memory.redact e namespace.rollback leem dela, porque as mesclagens (merges) descartam do ReplacingMergeTree as linhas substituídas. Adicione uma nova coluna de loom.memory a loom.memory_versions e ao SELECT da view na mesma migração. tests/unit/test_memory_versions_schema.py compara as duas listas de colunas em schema.sql com MEMORY_PERSISTED_COLS.
Todo novo caminho de escrita define actor e source_class carimbados pelo servidor (server.memory.domain.provenance), nunca valores vindos do corpo da requisição.
3. Classificar a tabela para o apagamento
O apagamento é uma saga (server/erasure/app/saga.py). Seu último passo é um censo de resíduos sobre cada tabela que os caminhos de leitura acessam; qualquer linha ativa no escopo faz a saga falhar de forma fechada. tests/unit/test_every_table_is_classified.py falha para qualquer CREATE TABLE em schema.sql que não esteja em exatamente uma das três listas em server/erasure/store/census.py:
| Lista | Coloque a tabela aqui quando | Você também adiciona |
|---|---|---|
_CENSUS |
Ela pode conter conteúdo de memória servido por um caminho de leitura. | Um passo da saga que remove as linhas no escopo e um Substrate(table, live, user_pred, ns_step, user_step) que nomeia esse passo para cada escopo. |
STEP_ONLY_TABLES |
Um passo da saga a modifica, mas o censo não a conta (ledgers derivados, mapas de alias), com o motivo no comentário acima do dict. | O passo, indexado pelo seu nome. |
NO_MEMORY_CONTENT |
Ela não contém conteúdo de memória no escopo (contagens, cursores, caches de dados públicos). | Um motivo de uma linha. |
Para uma tabela em _CENSUS:
liveé o predicado que uma linha ativa satisfaz (tombstoned_at IS NULL, ou"1"quando toda linha conta);user_predéuser_id = {uid:String}quando a tabela tem um eixo de usuário, eNonepara uma tabela apenas de namespace (nesse caso ela só é contada em apagamentos com escopo de namespace).- O passo é uma função em
server/erasure/store/steps_*.py, listada com o seu nome de passo em cada tabela da saga que se aplique (NAMESPACE_STEPS,USER_STEPSemserver/erasure/app/saga_steps.py), efinal=FalsenoSubstratepara umMergeTreesimples (FINAL não é permitido nele). - Uma saga retomada executa novamente o passo responsável por qualquer tabela em que o último censo encontrou linhas (
steps_to_reopen), então o passo deve ser idempotente. - Uma tabela do plano de código com chave
(org, namespace)normalmente pertence aCODE_INDEX_STEP_ONLY_TABLES(removida pelo passocode_index.purgeda saga); um teste unitário mantém essa tupla alinhada com o schema.
Teste o formato da instrução do passo com um cliente stub, como fazem tests/unit/test_erasure_repo.py e tests/unit/test_erasure_late_steps.py.
4. Classifique qualquer mutation
Um ALTER TABLE loom.<t> UPDATE|DELETE é uma mutation do ClickHouse: ela reescreve as parts de forma assíncrona e não é transacional. tests/unit/test_clickhouse_mutation_inventory.py conta todas as mutations visíveis em server/ e compara com _EXPECTED_MUTATIONS. Uma nova mutation faz o teste falhar até que você a adicione ali, com um comentário explicando o motivo.
Prefira uma nova linha de versão em uma ReplacingMergeTree, uma coluna de tombstone ou um DELETE FROM leve. Nunca use uma mutation como um claim ou lock pelo qual uma requisição espera; a caixa de entrada de tarefas faz o claim por meio de uma tabela de lease KeeperMap.
Lista de verificação
- Novo
schemas/migrations/<NNN>_<what>.sql, aditivo e idempotente; nenhum arquivo já mesclado é editado. -
make schema-dumpcontra um ClickHouse fixado e novo;make schema-checksem pendências. -
python scripts/codegen/docs_reference.pypara a referência do schema. - Colunas RMT: lista de colunas em
rows.py, builders, projeções;memory_versionsememory_versions_mvna mesma migration. - Classificação de apagamento:
_CENSUS+ etapa da saga,STEP_ONLY_TABLES, ouNO_MEMORY_CONTENTcom um motivo. - Toda nova mutação listada no teste de inventário.
- Uma linha em layout de armazenamento, na tabela da sua família
para uma tabela do ClickHouse (a seção das tabelas
_para um nome que começa com_), com todas as colunas preenchidas.tests/unit/test_storage_layout_rows.pyverifica que a linha existe (e, para uma tabela do ClickHouse, que ela some quando a tabela é removida; a linha de uma tabela Postgres removida é apagada manualmente), e, para uma linha do ClickHouse, que a célula Today corresponde ao schema, a célula Erasure ao census, e que suas citações nomeiam a tabela; com o dump do schema pendente, ele falha até que o dump seja incluído. -
make test-unit(os testes de aditividade, numeração, espelho, classificação e inventário).