> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-1d264819.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > COLUMN に関するドキュメント # カラム操作 テーブル構造を変更するための一連のクエリ。 構文: ```sql theme={null} ALTER [TEMPORARY] TABLE [db].name [ON CLUSTER cluster] ADD|DROP|RENAME|CLEAR|COMMENT|{MODIFY|ALTER}|MATERIALIZE COLUMN ... ``` クエリでは、カンマ区切りで 1 つ以上のアクションのリストを指定します。 各アクションは、カラムに対して実行する操作です。 サポートされているアクションは次のとおりです。 * [ADD COLUMN](#add-column) — テーブルに新しいカラムを追加します。 * [DROP COLUMN](#drop-column) — カラムを削除します。 * [RENAME COLUMN](#rename-column) — 既存のカラム名を変更します。 * [CLEAR COLUMN](#clear-column) — カラムの値をリセットします。 * [COMMENT COLUMN](#comment-column) — カラムにテキストコメントを追加します。 * [MODIFY COLUMN](#modify-column) — カラムの型、デフォルト式、有効期限 (TTL)、およびカラム設定を変更します。 * [MODIFY COLUMN REMOVE](#modify-column-remove) — カラムのプロパティの 1 つを削除します。 * [MODIFY COLUMN MODIFY SETTING](#modify-column-modify-setting) - カラム設定を変更します。 * [MODIFY COLUMN RESET SETTING](#modify-column-reset-setting) - カラム設定をリセットします。 * [MATERIALIZE COLUMN](#materialize-column) — カラムが存在しないパーツで、そのカラムを materialize します。 これらのアクションについては、以下で詳しく説明します。
## ADD COLUMN
```sql theme={null} ADD COLUMN [IF NOT EXISTS] name [type] [default_expr] [codec] [AFTER name_after | FIRST] ``` 指定した `name`、`type`、[`codec`](/ja/reference/statements/create/table#column_compression_codec)、および `default_expr` を持つ新しいカラムをテーブルに追加します ([デフォルト式](/ja/reference/statements/create/table#default_values) のセクションを参照) 。 `IF NOT EXISTS` 句が含まれている場合、カラムがすでに存在していてもクエリはエラーを返しません。`AFTER name_after` (別のカラム名) を指定すると、そのカラムはテーブルのカラム一覧で指定したカラムの直後に追加されます。カラムをテーブルの先頭に追加する場合は、`FIRST` 句を使用します。それ以外の場合、カラムはテーブルの末尾に追加されます。一連の操作では、`name_after` に前のいずれかの操作で追加されたカラム名を指定することもできます。 カラムの追加ではテーブル構造が変更されるだけで、データに対する操作は行われません。`ALTER` の後も、データはディスクに書き込まれません。テーブルの読み取り時にカラムのデータが存在しない場合は、デフォルト値で補完されます (デフォルト式があればそれを実行し、なければゼロまたは空文字列が使用されます) 。このカラムがディスク上に現れるのは、データパーツのマージ後です ([MergeTree](/ja/reference/engines/table-engines/mergetree-family/mergetree) を参照) 。 この方法により、古いデータ量を増やすことなく、`ALTER` クエリを即座に完了できます。 例: ```sql theme={null} ALTER TABLE alter_test ADD COLUMN Added1 UInt32 FIRST; ALTER TABLE alter_test ADD COLUMN Added2 UInt32 AFTER NestedColumn; ALTER TABLE alter_test ADD COLUMN Added3 UInt32 AFTER ToDrop; DESC alter_test FORMAT TSV; ``` ```text theme={null} Added1 UInt32 CounterID UInt32 StartDate Date UserID UInt32 VisitID UInt32 NestedColumn.A Array(UInt8) NestedColumn.S Array(String) Added2 UInt32 ToDrop UInt32 Added3 UInt32 ```
## DROP COLUMN
```sql theme={null} DROP COLUMN [IF EXISTS] name ``` 名前が `name` のカラムを削除します。`IF EXISTS` 句が指定されている場合、カラムが存在しなくてもクエリはエラーを返しません。 ファイルシステムからデータを削除します。ファイル全体を削除するため、クエリはほぼ瞬時に完了します。 カラムが [materialized view](/ja/reference/statements/create/view) から参照されている場合は、削除できません。削除しようとすると、エラーが返されます。 例: ```sql theme={null} ALTER TABLE visits DROP COLUMN browser ```
## RENAME COLUMN
```sql theme={null} RENAME COLUMN [IF EXISTS] name to new_name ``` カラム `name` の名前を `new_name` に変更します。`IF EXISTS` 句が指定されている場合、カラムが存在しなくてもクエリはエラーを返しません。名前の変更は基になるデータを伴わないため、クエリはほぼ即座に完了します。 **注**: テーブルのキー式 (`ORDER BY` または `PRIMARY KEY`) で指定されているカラムの名前は変更できません。これらのカラムの変更を試みると、`SQL Error [524]` が発生します。 例: ```sql theme={null} ALTER TABLE visits RENAME COLUMN webBrowser TO browser ```
## CLEAR COLUMN
```sql theme={null} CLEAR COLUMN [IF EXISTS] name IN PARTITION partition_name ``` 指定したパーティション内のカラムのすべてのデータをリセットします。パーティション名の設定方法について詳しくは、[パーティション式の設定方法](/ja/reference/statements/alter/partition#how-to-set-partition-expression)のセクションを参照してください。 `IF EXISTS` 句を指定した場合、カラムが存在しなくてもクエリはエラーを返しません。 例: ```sql theme={null} ALTER TABLE visits CLEAR COLUMN browser IN PARTITION tuple() ```
## COMMENT COLUMN
```sql theme={null} COMMENT COLUMN [IF EXISTS] name 'Text comment' ``` カラムにコメントを追加します。`IF EXISTS` 句が指定されている場合、カラムが存在しなくてもクエリはエラーを返しません。 各カラムには 1 つのコメントを付けられます。カラムにすでにコメントがある場合は、新しいコメントで以前のコメントが上書きされます。 コメントは、[DESCRIBE TABLE](/ja/reference/statements/describe-table) クエリが返す `comment_expression` カラムに保存されます。 例: ```sql theme={null} ALTER TABLE visits COMMENT COLUMN browser 'This column shows the browser used for accessing the site.' ```
## MODIFY COLUMN
```sql theme={null} MODIFY COLUMN [IF EXISTS] name [type] [default_expr] [codec] [TTL] [settings] [AFTER name_after | FIRST] ALTER COLUMN [IF EXISTS] name TYPE [type] [default_expr] [codec] [TTL] [settings] [AFTER name_after | FIRST] ``` このクエリは、`name` カラムの以下のプロパティを変更します。 * 型 * デフォルト式 * 圧縮コーデック * 有効期限 (TTL) * カラムレベル設定 カラムの圧縮 CODEC の変更例については、[カラム圧縮コーデック](/ja/reference/statements/create/table#column_compression_codec) を参照してください。 カラムの TTL の変更例については、[カラム TTL](/ja/reference/engines/table-engines/mergetree-family/mergetree#mergetree-column-ttl) を参照してください。 カラムレベル設定の変更例については、[カラムレベルの設定](/ja/reference/engines/table-engines/mergetree-family/mergetree#column-level-settings) を参照してください。 `IF EXISTS` 句が指定されている場合、カラムが存在しなくても、このクエリはエラーを返しません。 型を変更する場合、値は [toType](/ja/reference/functions/regular-functions/type-conversion-functions) 関数を適用した場合と同様に変換されます。デフォルト式のみを変更する場合、このクエリは複雑な処理を行わず、ほぼ瞬時に完了します。 例: ```sql theme={null} ALTER TABLE visits MODIFY COLUMN browser Array(String) ``` カラム型の変更だけが複雑な操作であり、データを含むファイルの内容も変更されます。大規模なテーブルでは、これに時間がかかる場合があります。 このクエリでは、`FIRST | AFTER` clause を使用してカラムの順序を変更することもできます。詳しくは [ADD COLUMN](#add-column) の説明を参照してください。ただし、この場合はカラム型の指定が必須です。 例: ```sql theme={null} CREATE TABLE users ( c1 Int16, c2 String ) ENGINE = MergeTree ORDER BY c1; DESCRIBE users; ┌─name─┬─type───┬ │ c1 │ Int16 │ │ c2 │ String │ └──────┴────────┴ ALTER TABLE users MODIFY COLUMN c2 String FIRST; DESCRIBE users; ┌─name─┬─type───┬ │ c2 │ String │ │ c1 │ Int16 │ └──────┴────────┴ ALTER TABLE users ALTER COLUMN c2 TYPE String AFTER c1; DESCRIBE users; ┌─name─┬─type───┬ │ c1 │ Int16 │ │ c2 │ String │ └──────┴────────┴ ``` `ALTER` クエリはアトミックです。MergeTree テーブルでは、ロックフリーでもあります。 カラムを変更するための `ALTER` クエリはレプリケートされます。指示は ZooKeeper に保存され、その後各レプリカで適用されます。すべての `ALTER` クエリは同じ順序で実行されます。クエリは、他のレプリカで必要な処理が完了するまで待機します。ただし、レプリケートテーブルのカラムを変更するクエリは途中で中断される場合があり、すべての処理は非同期に実行されます。 Nullable カラムを Non-Nullable に変更する際は、十分注意してください。NULL 値が含まれていないことを確認してください。含まれていると、そのカラムの読み取り時に問題が発生します。その場合の回避策は、mutation を Kill し、カラムを Nullable 型に戻すことです。
## MODIFY COLUMN REMOVE
カラムのプロパティのいずれか 1 つ (`DEFAULT`、`ALIAS`、`MATERIALIZED`、`CODEC`、`COMMENT`、`TTL`、`SETTINGS`) を削除します。 構文: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name REMOVE property; ``` **例** 有効期限 (TTL) を削除する: ```sql theme={null} ALTER TABLE table_with_ttl MODIFY COLUMN column_ttl REMOVE TTL; ``` **関連項目** * [REMOVE TTL](/ja/reference/statements/alter/ttl).
## MODIFY COLUMN MODIFY SETTING
カラム設定を変更します。 構文: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING name=value,...; ``` **例** カラムの `max_compress_block_size` を `1MB` に変更します。 ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING max_compress_block_size = 1048576; ```
## MODIFY COLUMN RESET SETTING
カラム設定をリセットします。また、テーブルのCREATEクエリ内のカラム式から設定の宣言も削除します。 構文: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING name,...; ``` **例** カラム設定 `max_compress_block_size` をデフォルト値に戻します: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING max_compress_block_size; ```
## MATERIALIZE COLUMN
`DEFAULT` または `MATERIALIZED` の値式を持つカラムをマテリアライズします。`ALTER TABLE table_name ADD COLUMN column_name MATERIALIZED` を使用してマテリアライズドカラムを追加した場合、マテリアライズされた値を持たない既存の行は自動的には補完されません。`MATERIALIZE COLUMN` ステートメントは、`DEFAULT` または `MATERIALIZED` 式を追加または更新した後に、既存のカラムデータを書き換えるために使用できます (この操作で更新されるのはメタデータのみで、既存データ自体は変更されません) 。なお、ソートキーに含まれるカラムをマテリアライズすることは、ソート順序が壊れる可能性があるため無効な操作です。 これは [mutation](/ja/reference/statements/alter#mutations) として実装されています。 新規または更新された `MATERIALIZED` 値式を持つカラムでは、既存のすべての行が書き換えられます。 新規または更新された `DEFAULT` 値式を持つカラムでは、動作は ClickHouse のバージョンによって異なります。 * ClickHouse \< v24.2 では、既存のすべての行が書き換えられます。 * ClickHouse >= v24.2 では、`DEFAULT` 値式を持つカラムの行の値が、挿入時に明示的に指定されたものか、それとも `DEFAULT` 値式から計算されたものかを区別します。値が明示的に指定されていた場合、ClickHouse はそのまま保持します。値が計算されたものだった場合、ClickHouse はそれを新しい、または更新された `MATERIALIZED` 値式に変更します。 構文: ```sql theme={null} ALTER TABLE [db.]table [ON CLUSTER cluster] MATERIALIZE COLUMN col [IN PARTITION partition | IN PARTITION ID 'partition_id']; ``` * PARTITION を指定すると、指定したパーティションに対してのみカラムがマテリアライズされます。 **例** ```sql theme={null} DROP TABLE IF EXISTS tmp; SET mutations_sync = 2; CREATE TABLE tmp (x Int64) ENGINE = MergeTree() ORDER BY tuple() PARTITION BY tuple(); INSERT INTO tmp SELECT * FROM system.numbers LIMIT 5; ALTER TABLE tmp ADD COLUMN s String MATERIALIZED toString(x); ALTER TABLE tmp MATERIALIZE COLUMN s; SELECT groupArray(x), groupArray(s) FROM (select x,s from tmp order by x); ┌─groupArray(x)─┬─groupArray(s)─────────┐ │ [0,1,2,3,4] │ ['0','1','2','3','4'] │ └───────────────┴───────────────────────┘ ALTER TABLE tmp MODIFY COLUMN s String MATERIALIZED toString(round(100/x)); INSERT INTO tmp SELECT * FROM system.numbers LIMIT 5,5; SELECT groupArray(x), groupArray(s) FROM tmp; ┌─groupArray(x)─────────┬─groupArray(s)──────────────────────────────────┐ │ [0,1,2,3,4,5,6,7,8,9] │ ['0','1','2','3','4','20','17','14','12','11'] │ └───────────────────────┴────────────────────────────────────────────────┘ ALTER TABLE tmp MATERIALIZE COLUMN s; SELECT groupArray(x), groupArray(s) FROM tmp; ┌─groupArray(x)─────────┬─groupArray(s)─────────────────────────────────────────┐ │ [0,1,2,3,4,5,6,7,8,9] │ ['inf','100','50','33','25','20','17','14','12','11'] │ └───────────────────────┴───────────────────────────────────────────────────────┘ ``` **関連項目** * [MATERIALIZED](/ja/reference/statements/create/view#materialized-view)。
## 制限事項
`ALTER` クエリでは、ネストされたデータ構造内の個別の要素 (カラム) は作成および削除できますが、ネストされたデータ構造全体は作成または削除できません。ネストされたデータ構造を追加するには、`name.nested_name` のような名前と `Array(T)` 型を持つカラムを追加します。ネストされたデータ構造は、ドットの前に同じプレフィックスを持つ複数の配列カラムと等価です。 名前にドットを含むカラムの名前変更は、部分的にサポートされています。ドットは [Nested](/ja/reference/data-types/nested-data-structures) のサブカラムアクセス用に予約されているため、プレフィックス (親名) は同じままでなければなりません。変更できるのは接尾辞 (サブカラム名) だけです。たとえば、`a.b` は `a.c` に名前変更できますが、`a.b` を `b.d` に名前変更することはできません。これは Nested の親プレフィックスが変わってしまうためです。 主キーまたは sampling key (`ENGINE` 式で使用されるカラム) に含まれるカラムの削除はサポートされていません。主キーに含まれるカラムの型変更は、その変更によってデータの変更が発生しない場合にのみ可能です (たとえば、Enum に値を追加したり、型を `DateTime` から `UInt32` に変更したりすることは許可されています) 。 必要なテーブル変更を行うのに `ALTER` クエリだけでは不十分な場合は、新しいテーブルを作成し、[INSERT SELECT](/ja/reference/statements/insert-into#inserting-the-results-of-select) クエリを使ってそこにデータをコピーし、その後 [RENAME](/ja/reference/statements/rename#rename-table) クエリでテーブルを切り替え、古いテーブルを削除できます。 `ALTER` クエリは、そのテーブルに対するすべての読み取りと書き込みをブロックします。つまり、`ALTER` クエリの実行時に長時間実行される `SELECT` がある場合、`ALTER` クエリはその完了を待機します。同時に、同じテーブルに対する新しいクエリも、この `ALTER` の実行中は待機します。 データ自体を格納しないテーブル ([Merge](/ja/reference/statements/alter) や [Distributed](/ja/reference/statements/alter) など) の場合、`ALTER` はテーブル構造を変更するだけで、従属するテーブルの構造は変更しません。たとえば、`Distributed` テーブルに対して ALTER を実行する場合は、すべてのリモートサーバー上のテーブルに対しても `ALTER` を実行する必要があります。