> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ALTER に関するドキュメント

# ALTER

ほとんどの `ALTER TABLE` クエリでは、テーブル設定またはデータを変更します。

| 修飾子 |
| - |
| [COLUMN](/docs/ja/reference/statements/alter/column) |
| [PARTITION](/docs/ja/reference/statements/alter/partition) |
| [DELETE](/docs/ja/reference/statements/alter/delete) |
| [UPDATE](/docs/ja/reference/statements/alter/update) |
| [ORDER BY](/docs/ja/reference/statements/alter/order-by) |
| [SAMPLE BY](/docs/ja/reference/statements/alter/sample-by) |
| [INDEX](/docs/ja/reference/statements/alter/skipping-index) |
| [PROJECTION](/docs/ja/reference/statements/alter/projection) |
| [CONSTRAINT](/docs/ja/reference/statements/alter/constraint) |
| [TTL](/docs/ja/reference/statements/alter/ttl) |
| [STATISTICS](/docs/ja/reference/statements/alter/statistics) |
| [SETTING](/docs/ja/reference/statements/alter/setting) |
| [APPLY DELETED MASK](/docs/ja/reference/statements/alter/apply-deleted-mask) |
| [APPLY PATCHES](/docs/ja/reference/statements/alter/apply-patches) |

<Note>
  ほとんどの `ALTER TABLE` クエリは、[\*MergeTree](/docs/ja/reference/engines/table-engines/mergetree-family/index)、[Merge](/docs/ja/reference/engines/table-engines/special/merge)、および [Distributed](/docs/ja/reference/engines/table-engines/special/distributed) テーブルでのみサポートされています。
</Note>

以下の `ALTER` ステートメントはビューを操作します。

| ステートメント | 説明 |
| - | - |
| [ALTER TABLE ... MODIFY QUERY](/docs/ja/reference/statements/alter/view) | [materialized view](/docs/ja/reference/statements/create/view) の構造を変更します。 |

以下の `ALTER` ステートメントは、ロールベースのアクセス制御に関連するエンティティを変更します。

| ステートメント |
| - |
| [USER](/docs/ja/reference/statements/alter/user) |
| [ROLE](/docs/ja/reference/statements/alter/role) |
| [QUOTA](/docs/ja/reference/statements/alter/quota) |
| [ROW POLICY](/docs/ja/reference/statements/alter/row-policy) |
| [MASKING POLICY](/docs/ja/reference/statements/alter/masking-policy) |
| [SETTINGS PROFILE](/docs/ja/reference/statements/alter/settings-profile) |

| ステートメント | 説明 |
| - | - |
| [ALTER TABLE ... MODIFY COMMENT](/docs/ja/reference/statements/alter/comment) | 事前に設定されていたかどうかにかかわらず、テーブルのコメントを追加、変更、または削除します。 |
| [ALTER DATABASE ... MODIFY COMMENT](/docs/ja/reference/statements/alter/database-comment) | 事前に設定されていたかどうかにかかわらず、データベースのコメントを追加、変更、または削除します。 |
| [ALTER NAMED COLLECTION](/docs/ja/reference/statements/alter/named-collection) | [Named Collections](/docs/ja/concepts/features/configuration/server-config/named-collections) を変更します。 |

<h2 id="combining-actions">
  1つの `ALTER` で複数のアクションをまとめる
</h2>

1つの `ALTER TABLE` にはカンマ区切りで複数のアクションを指定できます。そのため、本来であれば複数のステートメントに分けて順に実行する処理を、1つのステートメントにまとめられます。

```sql theme={null}
ALTER TABLE visits DROP COLUMN browser, DROP COLUMN referrer;
```

各アクションは同じ種類である必要はありません。また、アクションは左から右へ順に適用されるため、後のアクションでは前のアクションが追加したものを利用できます：

```sql theme={null}
-- a new column and an index over it
ALTER TABLE visits ADD COLUMN duration UInt32, ADD INDEX idx_duration duration TYPE minmax GRANULARITY 4;

-- a type change together with a new column
ALTER TABLE visits MODIFY COLUMN browser LowCardinality(String), ADD COLUMN page_id UInt64;

-- three actions in one statement
ALTER TABLE visits DROP COLUMN page_id, MODIFY COLUMN duration UInt64, ADD COLUMN region_id UInt32;
```

クライアントが `ALTER` の完了を待機する場合、その待機をどの設定が制御するかは、ステートメントではなくアクションによって決まります。`MATERIALIZE INDEX` のようにミューテーションの実行パスで処理されるアクションには [`mutations_sync`](/docs/ja/reference/settings/session-settings/mutations#mutations_sync) が適用され、メタデータ系のアクションには [`alter_sync`](/docs/ja/reference/settings/session-settings/alter#alter_sync) が適用されます。したがって、両者を 1 つのステートメントにまとめても、単一の設定で制御できるようにはなりません。各設定がどのアクションに適用されるかについては [ALTERクエリの同期](#synchronicity-of-alter-queries) を、こうした混在ステートメントを `Replicated` データベースで実行する際の制約については [`MATERIALIZE INDEX` 句の組み合わせ](#combining-materialize-index-clauses) を参照してください。

<h2 id="mutations">
  ミューテーション
</h2>

テーブルデータの操作を目的とする `ALTER` クエリは、「ミューテーション」と呼ばれる仕組みによって実装されています。代表的なものとして、[ALTER TABLE ... DELETE](/docs/ja/reference/statements/alter/delete) や [ALTER TABLE ... UPDATE](/docs/ja/reference/statements/alter/update) があります。これらは、[MergeTree](/docs/ja/reference/engines/table-engines/mergetree-family/index) テーブルにおけるマージと同様、新しい「変更後」のパーツを生成する非同期のバックグラウンド処理です。

`*MergeTree` テーブルでは、ミューテーションは**データパーツ全体を書き換える**ことで実行されます。
アトミック性はありません。パーツは準備ができ次第、変更後のパーツに置き換えられるため、ミューテーションの実行中に開始された `SELECT` クエリでは、すでに変更済みのパーツのデータと、まだ変更されていないパーツのデータの両方が見えることがあります。

ミューテーションは作成順に完全に順序付けられ、その順序で各パーツに適用されます。また、`INSERT INTO` クエリに対しては部分的な順序関係もあります。ミューテーションの送信前にテーブルへ挿入されたデータは変更対象になりますが、その後に挿入されたデータは変更されません。なお、ミューテーションが insert をブロックすることはありません。

ミューテーションのクエリは、ミューテーションエントリが追加されるとすぐに返ります (レプリケートテーブルの場合は ZooKeeper に、非レプリケートテーブルの場合は filesystem に追加されます) 。ミューテーション自体は、システムの profile 設定を使用して非同期に実行されます。ミューテーションの進行状況を追跡するには、[`system.mutations`](/docs/ja/reference/system-tables/mutations) テーブルを使用できます。正常に送信されたミューテーションは、ClickHouse server が再起動しても実行が継続されます。いったん送信されたミューテーションをロールバックする方法はありませんが、何らかの理由で停止している場合は、[`KILL MUTATION`](/docs/ja/reference/statements/kill#kill-mutation) クエリでキャンセルできます。

完了したミューテーションのエントリはすぐには削除されません (保持するエントリ数は、ストレージエンジンのパラメータ `finished_mutations_to_keep` で決まります) 。古いミューテーションエントリは削除されます。

<h2 id="execution-cost-and-completion">
  実行コストと完了
</h2>

`ALTER TABLE` を計画する際は、メタデータの変更と、既存のデータパーツに対して必要となる処理とを区別してください。クライアントが完了を待機するかどうかは操作によって異なります。[`alter_sync`](/docs/ja/reference/settings/session-settings/alter#alter_sync) はメタデータ操作と `MODIFY COLUMN` (データを書き換える型変換を含む) を制御し、[`mutations_sync`](/docs/ja/reference/settings/session-settings/mutations#mutations_sync) は `UPDATE`、`DELETE`、`MATERIALIZE ...` などのバックグラウンドミューテーションを制御します。固定の所要時間を運用上の目安にはしないでください。コストは、メタデータの量、影響を受けるパーツ数とバイト数、変換コスト、および現在のバックグラウンド負荷によって変わります。

| 操作 | 既存データに対する処理 | デフォルトの完了動作 | 主なコスト要因 |
| - | - | - | - |
| `ADD COLUMN` | 書き換えは発生しません。古いパーツでは読み取り時にデフォルト値が補われます。 | メタデータの待機は `alter_sync` に従います。 | メタデータのサイズとレプリカの可用性。 |
| `RENAME COLUMN` | 行の書き換えは発生しませんが、先行するミューテーションに対する順序付けのバリアとして機能します。 | メタデータの待機は `alter_sync` に従います。 | 先行するミューテーションとレプリカの可用性。 |
| `DROP COLUMN` | カラムファイルを削除するため、純粋なメタデータ変更ではありません。 | メタデータとミューテーションの順序付けが適用されます。 | カラムファイルの数とサイズ。 |
| `MODIFY COLUMN` によるデフォルト値、コメント、または表現を維持する型の変更 | 即時の書き換えは発生しません。 | メタデータの待機は `alter_sync` に従います。 | メタデータのサイズとレプリカの可用性。 |
| その他の `MODIFY COLUMN` による型変更 | `READ_COLUMN` ミューテーションにより、既存パーツ内の該当カラムが書き換えられます。 | 待機動作は `alter_sync` に従います (デフォルトは `1`、Cloud のデフォルトは `0`) 。 | 影響を受けるパーツ数とバイト数、変換コスト、バックグラウンド負荷。 |
| `UPDATE`、`DELETE`、`MATERIALIZE ...` | バックグラウンドミューテーションにより、影響を受けるパーツが書き換えられます。 | デフォルトでは非同期です。待機は `mutations_sync` で制御します。 | 影響を受けるパーツ数とバイト数、バックグラウンド負荷。 |

<h2 id="synchronicity-of-alter-queries">
  ALTERクエリの同期
</h2>

デフォルトでは、非レプリケートテーブルに対する `ALTER` クエリは処理が完了するまで待機します。`alter_sync = 0` の場合、バックグラウンド処理を伴う `ALTER` は、その処理の完了を待たずに戻ることがあります。レプリケートテーブルでは、クエリは対応する操作の指示を `ZooKeeper` に追加し、操作自体はできるだけ早く実行されます。クエリはそれらの操作がすべてのレプリカで完了するまで待機できます。

ミューテーション実行パスを通じてミューテーションを作成する `ALTER` クエリ (`UPDATE`、`DELETE`、`MATERIALIZE INDEX`、`MATERIALIZE PROJECTION`、`MATERIALIZE COLUMN`、`APPLY DELETED MASK`、`APPLY PATCHES`、`CLEAR STATISTIC`、`MATERIALIZE STATISTIC` など。ただしこれらに限りません) については、同期性は [mutations\_sync](/docs/ja/reference/settings/session-settings/mutations#mutations_sync) 設定によって決まります。

`MODIFY COLUMN` による書き換えを含むその他の `ALTER` クエリについては、[alter\_sync](/docs/ja/reference/settings/session-settings/alter#alter_sync) によって待機動作が制御されます。

非アクティブなレプリカがすべての `ALTER` クエリを実行するまで、どれだけ長く (秒単位で) 待機するかは、[replication\_wait\_for\_inactive\_replica\_timeout](/docs/ja/reference/settings/session-settings/other#replication_wait_for_inactive_replica_timeout) 設定で指定できます。

<Note>
  すべての `ALTER` クエリについて、`alter_sync = 2` であり、かつ一部のレプリカが `replication_wait_for_inactive_replica_timeout` 設定で指定された時間を超えて非アクティブな場合は、`UNFINISHED` 例外がスローされます。`alter_sync = 3` の場合は非アクティブなレプリカを待機しないため、例外はスローされません。
</Note>

<h3 id="concurrent-alter-assignment-on-one-table">
  1 つのテーブルに対する `ALTER` の同時割り当て
</h3>

レプリケートテーブルでは、同じテーブルに対して複数の個別の `ALTER` ステートメントを短時間に連続して送信すると、`CANNOT_ASSIGN_ALTER` (コード 517) で失敗することがあります。レプリケートパスでは、レプリカが以前の `ALTER` の一部をまだ適用していない場合にこのエラーが発生します (メタデータバージョンが共通メタデータより遅れている状態です。サーバーは、レプリカについて「still not applied some of previous alters」または「Probably too many alters executing concurrently」と表示することがあります) 。以前の `ALTER` がすでに割り当てられた後でも、この状態が続くことがあります。これは **メタデータ `ALTER` とミューテーションの一般的な同時実行状態** であり、ミューテーションのみを行うステートメントに限定されません。通常の同時メタデータ変更 (`ADD` / `DROP` / `MODIFY` など) でも、同じ再試行可能なコードが発生する場合があります (例として、`tests/queries/0_stateless/03518_alter_logical_race.sh` で対象となっている再試行パスを参照してください) 。

競合を回避する方法:

* 文法で許可される場合は、[1 つの `ALTER` で複数のアクションをまとめる](#combining-actions)で説明しているように、独立したメタデータ操作を **1 つの** 複数句 `ALTER` にまとめます (たとえば、複数の `ADD INDEX` 句) 。
* `ALTER` ステートメントを直列化し、以前の `ALTER` がレプリカに適用されるまで、コード 517 が発生した場合は再試行します。
* ミューテーションを生成する `ALTER` では、次の `ALTER` を送信する前に、[`mutations_sync`](/docs/ja/reference/settings/session-settings/mutations#mutations_sync) や [`system.mutations`](/docs/ja/reference/system-tables/mutations) の `is_done` など、ドキュメント化された確認手段を使用して、以前のミューテーションが完了するのを待ちます。

<h3 id="combining-materialize-index-clauses">
  `MATERIALIZE INDEX` 句の組み合わせ
</h3>

1 つの `ALTER` に複数の `MATERIALIZE INDEX` 句を含めることができます。ツリー内でテスト対象となっているのは、複数の `ADD INDEX` 句と、それらの新しい索引に対する `MATERIALIZE INDEX` を 1 つのステートメントにまとめるケースです (`tests/queries/0_stateless/02911_add_index_and_materialize_index.sql` を参照) 。この `ADD INDEX` + `MATERIALIZE INDEX` をまとめた形式では、`AlterCommand` セグメントと `MutationCommand` セグメントが混在するため、**`DatabaseReplicated` では `QUERY_IS_PROHIBITED` により拒否されます** (`InterpreterAlterQuery::validateReplicatedDatabaseSegments`) 。通常の (非 `DatabaseReplicated`) データベースでは、`02911` の例は有効です。`DatabaseReplicated` では、メタデータの変更とマテリアライズのミューテーションを別々のステートメントに分けてください。

現在の実装では、各 `MATERIALIZE INDEX` 句はミューテーションの準備時にテーブルのメタデータスナップショットに対して解決されます。そのため、既存の索引に対するマテリアライズのみの複数句形式も同じ準備パスをたどります (ミューテーションのみであるため、1 つのセグメント内に収まります) 。この正確な形式は、まだ専用のステートレステストでカバーされていません。そのようなテストが追加されるまでは、個別に保証された契約ではなく、現在の実装上の動作として扱ってください。

ミューテーションを順序どおりに適用する必要がある場合は、引き続きステートメントごとに 1 つの `MATERIALIZE INDEX` を実行し、[`mutations_sync`](/docs/ja/reference/settings/session-settings/mutations#mutations_sync) で完了を待機できます。

<h2 id="related-content">
  関連コンテンツ
</h2>

* ブログ: [ClickHouseでの更新と削除の処理](https://clickhouse.com/blog/handling-updates-and-deletes-in-clickhouse)