カラム操作
クエリのセットはテーブル構造を変更することを可能にします。
構文:
クエリでは、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 - カラム設定をリセットします。
- MATERIALIZE COLUMN — カラムが不足しているパーツにカラムをマテリアライズします。 これらのアクションの詳細は以下に記述されています。
ADD COLUMN
指定された name
、type
、codec
および default_expr
を使って、テーブルに新しいカラムを追加します(デフォルト式のセクションを参照)。
IF NOT EXISTS
句が含まれている場合、カラムが既に存在してもクエリはエラーを返しません。AFTER name_after
(別のカラムの名前)を指定すると、指定されたカラムの後にカラムが追加されます。テーブルの先頭にカラムを追加したい場合は、FIRST
句を使用します。そうでない場合、カラムはテーブルの末尾に追加されます。アクションのチェーンの場合、name_after
は前のアクションの1つで追加されたカラムの名前であることができます。
カラムを追加することは、データに対するアクションを実行することなく、テーブル構造のみを変更します。ALTER
後、データはディスク上に表示されません。テーブルから読み取る際にカラムのデータが不足している場合、デフォルト値で埋められます(デフォルト式がある場合はそれを実行するか、ゼロまたは空の文字列を使用します)。カラムは、データパーツをマージした後にディスクに表示されます(MergeTreeを参照)。
このアプローチにより、古いデータのボリュームを増やすことなく、ALTER
クエリを瞬時に完了させることができます。
例:
DROP COLUMN
名前 name
のカラムを削除します。IF EXISTS
句が指定されている場合、カラムが存在しない場合でもクエリはエラーを返しません。
ファイルシステムからデータを削除します。これは全ファイルを削除するため、クエリはほぼ瞬時に完了します。
Materialized View で参照されているカラムは削除できません。それ以外の場合はエラーが返されます。
例:
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
クエリは同じ順序で実行されます。クエリは他のレプリカで適切なアクションが完了するのを待ちます。ただし、レプリケートテーブルでカラムを変更するためのクエリは、中断される可能性があり、すべてのアクションは非同期で実行されます。
Nullable カラムを Non-Nullable に変更する際は注意してください。NULL 値が含まれていないことを確認してください。そうでない場合、読み込み時に問題が発生します。その場合の回避策は、変異を終了させてカラムを Nullable 型に戻すことです。
MODIFY COLUMN REMOVE
カラムプロパティの1つを削除します:DEFAULT
、ALIAS
、MATERIALIZED
、CODEC
、COMMENT
、TTL
、SETTINGS
。
構文:
例
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
式が追加または更新された後に既存のカラムデータを書き換えるのに使用できます(これはメタデータのみを更新し、既存のデータは変更しません)。ソートキーにカラムをマテリアライズすることは無効な操作であり、ソート順序を壊す可能性があることに注意してください。
Mutationとして実装されています。
新しいまたは更新された MATERIALIZED
値式を持つカラムに対して、すべての既存の行が書き換えられます。
新しいまたは更新された DEFAULT
値式を持つカラムに対して、その動作はClickHouseのバージョンによって異なります:
- ClickHouse < v24.2 では、すべての既存の行が書き換えられます。
- ClickHouse >= v24.2 は、
DEFAULT
値式を持つカラムに行値が挿入されたときに明示的に指定されたかどうかを区別します。値が明示的に指定された場合、ClickHouseはそれをそのまま保持します。値が計算された場合、ClickHouseはそれを新しいまたは更新されたMATERIALIZED
値式に変更します。
構文:
- PARTITIONを指定すると、指定されたパーティションでのみカラムがマテリアライズされます。
例
参照してください
制限事項
ALTER
クエリを使用すると、ネストされたデータ構造で別々の要素(カラム)を作成および削除できますが、全体のネストされたデータ構造を削除することはできません。ネストされたデータ構造を追加するには、name.nested_name
のような名前のカラムを追加し、型を Array(T)
とします。ネストされたデータ構造は、ドットの前に同じプレフィックスを持つ複数の配列カラムに相当します。
主キーまたはサンプリングキー(ENGINE
式で使用されるカラム)でのカラム削除はサポートされていません。主キーに含まれるカラムの型変更は、データが変更されない場合にのみ可能です(たとえば、Enum に値を追加したり、型を DateTime
から UInt32
に変更したりすることが許可されています)。
ALTER
クエリだけではテーブル変更が不十分な場合は、新しいテーブルを作成し、INSERT SELECT クエリを使用してデータをコピーし、その後、RENAME クエリを使用してテーブルを切り替え、古いテーブルを削除できます。
ALTER
クエリはテーブルに対するすべての読み取りと書き込みをブロックします。言い換えれば、長い SELECT
が ALTER
クエリの実行時に実行されている場合、ALTER
クエリはそれが完了するのを待ちます。同時に、同じテーブルに対するすべての新しいクエリは、ALTER
が実行されている間待機します。
データを自身で保存しないテーブル(Merge や Distributed など)の場合、ALTER
はテーブルの構造を変更するだけで、下位テーブルの構造は変更されません。たとえば、Distributed
テーブルの ALTER
を実行する場合、すべてのリモートサーバー上のテーブルでも ALTER
を実行する必要があります。