- 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 - カラム設定をリセットします。
- MODIFY COLUMN ADD ENUM VALUES - Enum に新しい値を追加します。
- MATERIALIZE COLUMN — カラムが存在しないパーツで、そのカラムを materialize します。 これらのアクションについては、以下で詳しく説明します。
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)
- カラムレベル設定
- Enum/Enum8/Enum16 型の Enum 値
IF EXISTS 句が指定されている場合、カラムが存在しなくても、このクエリはエラーを返しません。
型を変更する場合、値は toType 関数を適用した場合と同様に変換されます。デフォルト式のみを変更する場合、このクエリは複雑な処理を行わず、ほぼ瞬時に完了します。
例:
FIRST | AFTER clause を使用してカラムの順序を変更することもできます。詳しくは ADD COLUMN の説明を参照してください。ただし、この場合はカラム型の指定が必須です。
例:
ALTER クエリはアトミックです。MergeTree テーブルでは、ロックフリーでもあります。
カラムを変更するための ALTER クエリはレプリケートされます。指示は ZooKeeper に保存され、その後各レプリカで適用されます。すべての ALTER クエリは同じ順序で実行されます。クエリは、他のレプリカで必要な処理が完了するまで待機します。ただし、レプリケートテーブルのカラムを変更するクエリは途中で中断される場合があり、すべての処理は非同期に実行されます。
Nullable カラムを Non-Nullable に変更する際は、十分注意してください。NULL 値が含まれていないことを確認してください。含まれていると、そのカラムの読み取り時に問題が発生します。その場合の回避策は、mutation を Kill し、カラムを Nullable 型に戻すことです。
MODIFY COLUMN REMOVE
DEFAULT、ALIAS、MATERIALIZED、CODEC、COMMENT、TTL、SETTINGS) を削除します。
構文:
MODIFY COLUMN MODIFY SETTING
max_compress_block_size を 1MB に変更します。
MODIFY COLUMN RESET SETTING
max_compress_block_size をデフォルト値に戻します:
MODIFY COLUMN ADD ENUM VALUES
Enum、Enum8、Enum16、Nullable(Enum)、Nullable(Enum8)、Nullable(Enum16) 型のカラムに新しい値を追加します。
構文:
enum_column_name カラムに 2 つの値を追加します。
MATERIALIZE COLUMN
DEFAULT または MATERIALIZED の値式を持つカラムをマテリアライズします。ALTER TABLE table_name ADD COLUMN column_name MATERIALIZED を使用してマテリアライズドカラムを追加した場合、マテリアライズされた値を持たない既存の行は自動的には補完されません。MATERIALIZE COLUMN ステートメントは、DEFAULT または MATERIALIZED 式を追加または更新した後に、既存のカラムデータを書き換えるために使用できます (この操作で更新されるのはメタデータのみで、既存データ自体は変更されません) 。なお、ソートキーに含まれるカラムをマテリアライズすることは、ソート順序が壊れる可能性があるため無効な操作です。
これは mutation として実装されています。
新規または更新された MATERIALIZED 値式を持つカラムでは、既存のすべての行が書き換えられます。
新規または更新された DEFAULT 値式を持つカラムでは、動作は ClickHouse のバージョンによって異なります。
- ClickHouse < v24.2 では、既存のすべての行が書き換えられます。
- ClickHouse >= v24.2 では、
DEFAULT値式を持つカラムの行の値が、挿入時に明示的に指定されたものか、それともDEFAULT値式から計算されたものかを区別します。値が明示的に指定されていた場合、ClickHouse はそのまま保持します。値が計算されたものだった場合、ClickHouse はそれを新しい、または更新されたMATERIALIZED値式に変更します。
- PARTITION を指定すると、指定したパーティションに対してのみカラムがマテリアライズされます。
制限事項
ALTER クエリでは、ネストされたデータ構造内の個別の要素 (カラム) は作成および削除できますが、ネストされたデータ構造全体は作成または削除できません。ネストされたデータ構造を追加するには、name.nested_name のような名前と Array(T) 型を持つカラムを追加します。ネストされたデータ構造は、ドットの前に同じプレフィックスを持つ複数の配列カラムと等価です。
名前にドットを含むカラムの名前変更は、部分的にサポートされています。ドットは Nested のサブカラムアクセス用に予約されているため、プレフィックス (親名) は同じままでなければなりません。変更できるのは接尾辞 (サブカラム名) だけです。たとえば、a.b は a.c に名前変更できますが、a.b を b.d に名前変更することはできません。これは Nested の親プレフィックスが変わってしまうためです。
主キーまたは sampling key (ENGINE 式で使用されるカラム) に含まれるカラムの削除はサポートされていません。主キーに含まれるカラムの型変更は、その変更によってデータの変更が発生しない場合にのみ可能です (たとえば、Enum に値を追加したり、型を DateTime から UInt32 に変更したりすることは許可されています) 。
必要なテーブル変更を行うのに ALTER クエリだけでは不十分な場合は、新しいテーブルを作成し、INSERT SELECT クエリを使ってそこにデータをコピーし、その後 RENAME クエリでテーブルを切り替え、古いテーブルを削除できます。
ALTER クエリは、そのテーブルに対するすべての読み取りと書き込みをブロックします。つまり、ALTER クエリの実行時に長時間実行される SELECT がある場合、ALTER クエリはその完了を待機します。同時に、同じテーブルに対する新しいクエリも、この ALTER の実行中は待機します。
データ自体を格納しないテーブル (Merge や Distributed など) の場合、ALTER はテーブル構造を変更するだけで、従属するテーブルの構造は変更しません。たとえば、Distributed テーブルに対して ALTER を実行する場合は、すべてのリモートサーバー上のテーブルに対しても ALTER を実行する必要があります。