Column Manipulations

A set of queries that allow changing the table structure.

Syntax:

In the query, specify a list of one or more comma-separated actions. Each action is an operation on a column.

The following actions are supported:

• ADD COLUMN — テーブルに新しいカラムを追加します。
• DROP COLUMN — カラムを削除します。
• RENAME COLUMN — 既存のカラムの名前を変更します。
• CLEAR COLUMN — カラムの値をリセットします。
• COMMENT COLUMN — カラムにテキストコメントを追加します。
• MODIFY COLUMN — カラムの型、デフォルト式、TTL、およびカラム設定を変更します。
• MODIFY COLUMN REMOVE — カラムのプロパティの1つを削除します。
• MODIFY COLUMN MODIFY SETTING - カラム設定を変更します。
• MODIFY COLUMN RESET SETTING - カラム設定をリセットします。
• MATERIALIZE COLUMN — カラムが欠落しているパーツでカラムをマテリアライズします。

これらのアクションについては、以下で詳細に説明します。

ADD COLUMN

指定された name、type、codec および default_expr（デフォルト式のセクションを参照）を使用して、テーブルに新しいカラムを追加します。

IF NOT EXISTS 句が含まれている場合、そのカラムがすでに存在する場合はエラーが返されません。AFTER name_after（他のカラムの名前）を指定した場合、指定したカラムの後にカラムが追加されます。テーブルの最初にカラムを追加したい場合は FIRST 句を使用します。そうでなければ、カラムはテーブルの終わりに追加されます。アクションのチェーンでは、name_after は前のアクションで追加されるカラムの名前であることができます。

カラムを追加することはテーブル構造を変更するだけで、データに対しては何も操作を行いません。ALTER の後、データはディスク上に表示されません。テーブルから読み取る際にカラムのデータが欠落している場合、それはデフォルト値で埋められます（もしデフォルト式があればそれを実行し、なければゼロまたは空文字列を使用します）。カラムはデータパーツのマージ後にディスク上に現れます（MergeTreeを参照）。

このアプローチにより、古いデータの容量を増やすことなく ALTER クエリを瞬時に完了させることができます。

例:

DROP COLUMN

名前 name のカラムを削除します。IF EXISTS 句が指定されている場合、カラムが存在しない場合はエラーが返されません。

ファイルシステムからデータを削除します。これは全ファイルを削除するため、クエリはほぼ瞬時に完了します。

ヒント

物化ビューによって参照されているカラムは削除できません。それ以外の場合、エラーが返されます。

例:

RENAME COLUMN

カラム name の名前を new_name に変更します。IF EXISTS 句が指定されている場合、カラムが存在しない場合はエラーが返されません。名前変更は基になるデータを伴わないため、クエリはほぼ瞬時に完了します。

注意: テーブルのキー式（ORDER BY または PRIMARY KEY として指定されたもの）で指定されたカラムはリネームできません。これらのカラムを変更しようとすると SQL Error [524] が発生します。

例:

CLEAR COLUMN

指定されたパーティションのカラム内のすべてのデータをリセットします。パーティション名の設定については、パーティション式の設定方法のセクションを参照してください。

IF EXISTS 句が指定されている場合、カラムが存在しない場合はエラーが返されません。

例:

COMMENT COLUMN

カラムにコメントを追加します。IF EXISTS 句が指定されている場合、カラムが存在しない場合はエラーが返されません。

各カラムには1つのコメントを持つことができます。カラムにコメントが既に存在する場合、新しいコメントは前のコメントを上書きします。

コメントは DESCRIBE TABLE クエリによって返される comment_expression カラムに保存されます。

例:

MODIFY COLUMN

このクエリは name カラムのプロパティを変更します：

• 型

• デフォルト式

• 圧縮コーデック

• TTL

• カラムレベルの設定

カラムの圧縮 CODECS を変更する例については、カラム圧縮コーデックスを参照してください。

カラム TTL を変更する例については、カラム TTLを参照してください。

カラムレベルの設定を変更する例については、カラムレベルの設定を参照してください。

IF EXISTS 句が指定されている場合、カラムが存在しない場合はエラーが返されません。

型を変更する際、値は toType 関数が適用されたかのように変換されます。デフォルト式だけが変更された場合、クエリは複雑な操作を行わず、ほぼ瞬時に完了します。

例:

カラムの型の変更は唯一の複雑なアクションです - データを含むファイルの内容を変更します。大きなテーブルの場合、これには長い時間がかかる可能性があります。

クエリは FIRST | AFTER 句を使用してカラムの順序を変更することもできますが、その場合はカラム型が必須です（ADD COLUMN の説明を参照）。

例:

ALTER クエリは原子的です。MergeTree テーブルの場合、ロックフリーでもあります。

カラムの変更のための ALTER クエリはレプリケートされます。手順は ZooKeeper に保存され、その後各レプリカがそれを適用します。すべての ALTER クエリは同じ順序で実行されます。クエリは、他のレプリカで適切なアクションが完了するのを待ちます。ただし、レプリケートされたテーブルのカラムを変更するクエリは中断されることがあり、すべてのアクションは非同期で実行されます。

MODIFY COLUMN REMOVE

カラムプロパティの1つを削除します： DEFAULT、ALIAS、MATERIALIZED、CODEC、COMMENT、TTL、SETTINGS。

構文:

例

TTL を削除する:

関連項目

• REMOVE TTL.

MODIFY COLUMN MODIFY SETTING

カラム設定を変更します。

構文:

例

カラムの max_compress_block_size を 1MB に変更します:

MODIFY COLUMN RESET SETTING

カラム設定をリセットし、テーブルの CREATE クエリのカラム式における設定宣言も削除します。

構文:

例

カラム設定 max_compress_block_size をデフォルト値にリセットします:

MATERIALIZE COLUMN

DEFAULT または MATERIALIZED 値式でカラムをマテリアライズします。ALTER TABLE table_name ADD COLUMN column_name MATERIALIZED を使用してマテリアライズカラムを追加する際、既存の行にマテリアライズされた値がない場合は自動的には埋められません。MATERIALIZE COLUMN ステートメントは、DEFAULT または MATERIALIZED 式が追加または更新された後に既存のカラムデータを上書きするために使用されます（これはメタデータのみを更新し、既存のデータは変更しません）。ソートキー内でカラムをマテリアライズすることは無効な操作であるため、ソート順序が壊れる可能性があります。 ミューテーションとして実装されています。

新しいまたは更新された MATERIALIZED 値式を持つカラムについては、すべての既存の行が上書きされます。

新しいまたは更新された DEFAULT 値式を持つカラムについては、動作は ClickHouse のバージョンによって異なります：

• ClickHouse < v24.2 では、すべての既存の行が上書きされます。
• ClickHouse >= v24.2 では、DEFAULT 値式を持つカラムに挿入された行の値が明示的に指定されたかどうかを区別します。もし値が明示的に指定された場合、ClickHouse はそのまま保持します。もし値が計算された場合、ClickHouse はそれを新しいまたは更新された MATERIALIZED 値式に変更します。

構文:

• PARTITION を指定した場合、カラムは指定されたパーティションのみでマテリアライズされます。

例

関連項目

• MATERIALIZED.

Limitations

ALTER クエリを使用すると、ネストされたデータ構造内の別々の要素（カラム）を作成および削除できますが、全体のネストされたデータ構造を管理することはできません。ネストされたデータ構造を追加するには、 name.nested_name のような名前と Array(T) の型を持つカラムを追加できます。ネストされたデータ構造は、ドットの前に同じプレフィックスを持つ複数の配列カラムに相当します。

プライマリキーやサンプリングキー（ENGINE 式で使用されるカラム）内のカラムを削除することはサポートされていません。プライマリキーに含まれるカラムの型を変更することは、データが変更されない場合にのみ可能です（たとえば、Enumに値を追加したり、型を DateTime から UInt32 に変更したりすることが許可されています）。

ALTER クエリが必要なテーブルの変更を行うには不十分な場合、新しいテーブルを作成し、INSERT SELECT クエリを使用してデータをコピーし、RENAME クエリを使用してテーブルを切り替え、古いテーブルを削除できます。

ALTER クエリはテーブルのすべての読み取りと書き込みをブロックします。言い換えれば、ALTER クエリの実行中に長い SELECT が実行されている場合、ALTER クエリはそれが完了するのを待ちます。同時に、同じテーブルへのすべての新しいクエリは、この ALTER が実行されている間待機します。

データを直接保存しないテーブル（Merge と Distributed のような）については、ALTER はテーブル構造を変更するだけで、従属テーブルの構造は変更しません。たとえば、Distributed テーブルの ALTER を実行すると、すべてのリモートサーバー上のテーブルに対しても ALTER を実行する必要があります。