ClickHouse / ClickHouse/ClickHouse

Docs: document `ALTER TABLE` cost class (metadata / async mutation / sync rewrite)

Open
#105,539 3 comments 0 reactions 1 assignee Claimed by @Blargian View on GitHub
comp-documentation usability
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.