ALTER TABLE ... COLUMN

テーブル構造を変更するための一連のクエリ。

構文:

ALTER [TEMPORARY] TABLE [db].name [ON CLUSTER cluster] ADD|DROP|RENAME|CLEAR|COMMENT|{MODIFY|ALTER}|MATERIALIZE COLUMN ...

クエリでは、カンマ区切りで 1 つ以上のアクションのリストを指定します。 各アクションは、カラムに対して実行する操作です。

サポートされているアクションは次のとおりです。

• 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 — カラムが存在しないパーツで、そのカラムをマテリアライズします。 これらのアクションについては、以下で詳しく説明します。

ADD COLUMN [IF NOT EXISTS] name [type] [default_expr] [COMMENT 'comment for column'] [codec] [STATISTICS] [TTL] [settings] [AFTER name_after | FIRST]

指定した name、type、codec、および default_expr を持つ新しいカラムをテーブルに追加します (デフォルト式 のセクションを参照) 。型に続く修飾子は任意の順序で記述でき、それぞれ最大1回まで指定できます。カラム定義 を参照してください。

IF NOT EXISTS 句が含まれている場合、カラムがすでに存在していてもクエリはエラーを返しません。AFTER name_after (別のカラム名) を指定すると、そのカラムはテーブルのカラム一覧で指定したカラムの直後に追加されます。カラムをテーブルの先頭に追加する場合は、FIRST 句を使用します。それ以外の場合、カラムはテーブルの末尾に追加されます。一連の操作では、name_after に前のいずれかの操作で追加されたカラム名を指定することもできます。

カラムの追加ではテーブル構造が変更されるだけで、データに対する操作は行われません。ALTER の後も、データはディスクに書き込まれません。テーブルの読み取り時にカラムのデータが存在しない場合は、デフォルト値で補完されます (デフォルト式があればそれを実行し、なければゼロまたは空文字列が使用されます) 。このカラムがディスク上に現れるのは、データパーツのマージ後です (MergeTree を参照) 。

この方法により、古いデータ量を増やすことなく、ALTER クエリを即座に完了できます。

例:

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;

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 [IF EXISTS] name

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

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

例:

ALTER TABLE visits DROP COLUMN browser

RENAME COLUMN [IF EXISTS] name to new_name

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

注: テーブルのキー式 (ORDER BY または PRIMARY KEY) で指定されているカラムの名前は変更できません。これらのカラムの変更を試みると、SQL Error [524] が発生します。

例:

ALTER TABLE visits RENAME COLUMN webBrowser TO browser

CLEAR COLUMN [IF EXISTS] name IN PARTITION partition_name

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

IF EXISTS 句を指定した場合、カラムが存在しなくてもクエリはエラーを返しません。

例:

ALTER TABLE visits CLEAR COLUMN browser IN PARTITION tuple()

COMMENT COLUMN [IF EXISTS] name 'Text comment'

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

各カラムには 1 つのコメントを付けられます。カラムにすでにコメントがある場合は、新しいコメントで以前のコメントが上書きされます。

コメントは、DESCRIBE TABLE クエリが返す comment_expression カラムに保存されます。

例:

ALTER TABLE visits COMMENT COLUMN browser 'This column shows the browser used for accessing the site.'

MODIFY COLUMN [IF EXISTS] name
    [type] [default_expr] [COMMENT 'comment for column'] [codec] [STATISTICS] [TTL] [settings] [AFTER name_after | FIRST]
    | ADD ENUM VALUES ( 'name' [= number] [, ...] )
ALTER COLUMN [IF EXISTS] name
    TYPE [type] [default_expr] [COMMENT 'comment for column'] [codec] [STATISTICS] [TTL] [settings] [AFTER name_after | FIRST]
    | ADD ENUM VALUES ( 'name' [= number] [, ...] )

型の後に続く修飾子は任意の順序で記述でき、それぞれ 1 回まで指定できます。詳しくは カラム定義 を参照してください。

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

• 型

• デフォルト式

• 圧縮コーデック

• 有効期限 (TTL)

• カラムレベル設定

• Enum/Enum8/Enum16 型の Enum 値

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

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

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

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

型を変更する場合、値は toType 関数を適用した場合と同様に変換されます。デフォルト式のみを変更する場合、このクエリは複雑な処理を行わず、ほぼ瞬時に完了します。

例:

ALTER TABLE visits MODIFY COLUMN browser Array(String)

カラム型の変更だけが複雑な操作であり、データを含むファイルの内容も変更されます。大規模なテーブルでは、これに時間がかかる場合があります。

このクエリでは、FIRST | AFTER 句を使用してカラムの順序を変更することもできます。詳しくは ADD COLUMN の説明を参照してください。ただし、この場合はカラム型の指定が必須です。

例:

CREATE TABLE users (
    c1 Int16,
    c2 String
) ENGINE = MergeTree
ORDER BY c1;

DESCRIBE users;
┌

ALTER クエリはアトミックです。MergeTree テーブルでは、ロックフリーでもあります。

カラムを変更するための ALTER クエリはレプリケートされます。指示は ZooKeeper に保存され、その後各レプリカで適用されます。すべての ALTER クエリは同じ順序で実行されます。クエリは、他のレプリカで必要な処理が完了するまで待機します。ただし、レプリケートテーブルのカラムを変更するクエリは途中で中断される場合があり、すべての処理は非同期に実行されます。

カラムのプロパティのいずれか 1 つ (DEFAULT、ALIAS、MATERIALIZED、CODEC、COMMENT、TTL、SETTINGS) を削除します。

構文:

ALTER TABLE table_name MODIFY COLUMN column_name REMOVE property;

例

有効期限 (TTL) を削除する:

ALTER TABLE table_with_ttl MODIFY COLUMN column_ttl REMOVE TTL;

関連項目

• REMOVE TTL.

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

構文:

ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING name=value,...;

例

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

ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING max_compress_block_size = 1048576;

カラム設定をリセットします。また、テーブルのCREATEクエリ内のカラム式から設定の宣言も削除します。

構文:

ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING name,...;

例

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

ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING max_compress_block_size;

Enum、Enum8、Enum16、Nullable(Enum)、Nullable(Enum8)、Nullable(Enum16) 型のカラムに新しい値を追加します。

構文:

ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('EnumName' [= number], ...);

例

enum_column_name カラムに 2 つの値を追加します。

ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('Hundred' = 100, 'HundredOne');

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 値式に変更します。

構文:

ALTER TABLE [db.]table [ON CLUSTER cluster] MATERIALIZE COLUMN col [IN PARTITION partition | IN PARTITION ID 'partition_id'];

• PARTITION を指定すると、指定したパーティションに対してのみカラムがマテリアライズされます。

例

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);

┌

関連項目

• MATERIALIZED。
• MATERIALIZE INDEX。

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 を実行する必要があります。