ClickHouse / ClickHouse/ClickHouse
Docs: document `ALTER TABLE` cost class (metadata / async mutation / sync rewrite)
- Dominant language
- C++
- Stars
- 49.9k
- Forks
- 9k
- Avg merge
- 21h 32m
- Merged PRs (30d)
- 515
Description
## What's missing
The docs cover individual `ALTER TABLE` operations and the mutations concept, but there is no single comparative table mapping each operation to:
- **cost class** — metadata-only / async mutation / sync part rewrite
- **whether it blocks the statement**
- **how it propagates on `SharedMergeTree`** (instant via Keeper vs. background sync)
- **typical duration**
Today operators read the source or hit the wall in production. The `SharedMergeTree` propagation axis in particular is not documented anywhere.
## Why it matters
Every team running migrations against ClickHouse needs to answer "is this safe during business hours?" before each new migration. With so many migrations in our codebase, this is a recurring research tax — and on Cloud / `SharedMergeTree` there is genuinely no public answer for several operations.
## What I'd like
One docs table along these lines (rows the maintainers can refine):
| operation | class | blocks statement | SMT propagation | typical duration |
| --------------------------------- | ----------------- | ---------------- | -------------------------------- | ---------------- |
| `ADD COLUMN` | metadata-only | no | instant via Keeper | μs |
| `RENAME COLUMN` | metadata-only | no | instant via Keeper | μs |
| `MODIFY COLUMN` (compatible type) | metadata-only | no | instant via Keeper | μs |
| `MODIFY COLUMN` (type conversion) | sync part rewrite | yes | per-replica rewrite | minutes–hours |
| `DELETE WHERE` | async mutation | no | background; use `mutations_sync` | minutes–hours |
| `UPDATE WHERE` | async mutation | no | background; use `mutations_sync` | minutes–hours |
A queryable `system.alter_operations` view exposing the same mapping would be a nice follow-up for migration tooling, but the docs table is the primary ask.
## Severity
Operational / documentation. The behaviour is correct; the gap is discoverability.
Contributor guide
Assessment
This issue has not been assessed yet.