📣新登場！TiDB Cloud BYOC、TiDB Cloud Filesystem、PostgreSQL-compatible TiDB Cloud Starter がパブリックプレビュー中。このページは自動翻訳されたものです。原文はこちらからご覧ください。
AI
開発者
ベストプラクティス
API

ALTER TABLE

ALTER TABLE を使用して、既存のテーブルの構造やプロパティを変更します。対象には、カラム、コメント、ストレージオプション、外部接続、さらには別のテーブルとのメタデータの入れ替えも含まれます。以下の各サブセクションでは、サポートされている各機能について説明します。

カラム操作

カラムの追加、変換、名前変更、変更、削除によってテーブルを変更します。

構文

-- Add a column to the end of the table
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
ADD [ COLUMN ] <column_name> <data_type> [ NOT NULL | NULL ] [ DEFAULT <constant_value> ]

-- Add a column to a specified position
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
ADD [ COLUMN ] <column_name> <data_type> [ NOT NULL | NULL ] [ DEFAULT <constant_value> ] [ FIRST | AFTER <column_name> ]

-- Add a virtual computed column
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
ADD [ COLUMN ] <column_name> <data_type> AS (<expr>) VIRTUAL

-- Convert a stored computed column to a regular column
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
MODIFY [ COLUMN ] <column_name> DROP STORED

-- Rename a column
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
RENAME [ COLUMN ] <column_name> TO <new_column_name>

-- Change data type
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
MODIFY [ COLUMN ] <column_name> <new_data_type> [ DEFAULT <constant_value> ]
       [ , [ COLUMN ] <column_name> <new_data_type> [ DEFAULT <constant_value> ] ]
       ...

-- Change comment
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
MODIFY [ COLUMN ] <column_name> [ COMMENT '<comment>' ]
[ , [ COLUMN ] <column_name> [ COMMENT '<comment>' ] ]
...

-- Set / Unset masking policy for a column
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
MODIFY [ COLUMN ] <column_name> SET MASKING POLICY <policy_name>
       [ USING ( <column_reference> [ , <column_reference> ... ] ) ]

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
MODIFY [ COLUMN ] <column_name> UNSET MASKING POLICY

-- Remove a column
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
DROP [ COLUMN ] <column_name>

Note:

  • カラムを追加または変更する際、デフォルト値として受け入れられるのは定数値のみです。非定数式を使用するとエラーになります。
  • ALTER TABLE による保存計算カラムの追加は、まだサポートされていません。
  • テーブルのカラムのデータ型を変更する場合、変換エラーのリスクがあります。たとえば、テキスト（String）を含むカラムを数値（Float）に変換しようとすると、問題が発生する可能性があります。
  • カラムにマスキングポリシーを設定する場合は、ポリシーで定義されているデータ型（CREATE MASKING POLICY の構文にあるパラメータ arg_type_to_mask を参照）がそのカラムと一致していることを確認してください。
  • ポリシー定義が追加パラメータを想定している場合は、任意の USING 句を使用します。各ポリシー引数に対応するカラムを順番に列挙してください。最初の引数は常にマスク対象のカラムを表します。
  • USING を含める場合は、少なくともマスク対象カラムと、ポリシーで必要な追加カラムを指定してください。USING (...) 内の最初の識別子は、変更対象のカラムと一致している必要があります。
  • マスキングポリシーを関連付けられるのは通常のテーブルのみです。ビュー、ストリーム、一時テーブルでは SET MASKING POLICY を使用できません。
  • 1 つのカラムに関連付けられるセキュリティポリシー（マスキングまたは行レベル）は最大 1 つです。新しいポリシーを関連付ける前に、既存のポリシーを削除してください。
  • マスキングポリシーの関連付け、関連解除、表示、削除には、グローバルな APPLY MASKING POLICY 権限、または対象のマスキングポリシーに対する APPLY/OWNERSHIP が必要です。
  • 行アクセスポリシーの追加または削除には、対象テーブルに対する ALTER 権限に加え、グローバルな APPLY ROW ACCESS POLICY 権限、またはそのポリシーに対する APPLY/OWNERSHIP が必要です。ポリシーの表示または削除にも同じポリシー権限が必要です。

例

例 1: カラムの追加、名前変更、削除

この例では、'username'、'email'、'age' の各カラムを持つ "default.users" というテーブルを作成します。さらに、さまざまな制約付きで 'id' と 'middle_name' のカラムを追加します。また、"age" カラムの名前を変更し、その後削除する方法も示します。

-- Create a table
CREATE TABLE default.users (
  username VARCHAR(50) NOT NULL,
  email VARCHAR(255),
  age INT
);

-- Add a column to the end of the table
ALTER TABLE default.users
ADD COLUMN business_email VARCHAR(255) NOT NULL DEFAULT 'example@example.com';

DESC default.users;

Field         |Type   |Null|Default              |Extra|
--------------+-------+----+---------------------+-----+
username      |VARCHAR|NO  |''                   |     |
email         |VARCHAR|YES |NULL                 |     |
age           |INT    |YES |NULL                 |     |
business_email|VARCHAR|NO  |'example@example.com'|     |

-- Add a column to the beginning of the table
ALTER TABLE default.users
ADD COLUMN id int NOT NULL FIRST;

DESC default.users;

Field         |Type   |Null|Default              |Extra|
--------------+-------+----+---------------------+-----+
id            |INT    |NO  |0                    |     |
username      |VARCHAR|NO  |''                   |     |
email         |VARCHAR|YES |NULL                 |     |
age           |INT    |YES |NULL                 |     |
business_email|VARCHAR|NO  |'example@example.com'|     |

-- Add a column after the column 'username'
ALTER TABLE default.users
ADD COLUMN middle_name VARCHAR(50) NULL AFTER username;

DESC default.users;

Field         |Type   |Null|Default              |Extra|
--------------+-------+----+---------------------+-----+
id            |INT    |NO  |0                    |     |
username      |VARCHAR|NO  |''                   |     |
middle_name   |VARCHAR|YES |NULL                 |     |
email         |VARCHAR|YES |NULL                 |     |
age           |INT    |YES |NULL                 |     |
business_email|VARCHAR|NO  |'example@example.com'|     |

-- Rename a column
ALTER TABLE default.users
RENAME COLUMN age TO new_age;

DESC default.users;

Field         |Type   |Null|Default              |Extra|
--------------+-------+----+---------------------+-----+
id            |INT    |NO  |0                    |     |
username      |VARCHAR|NO  |''                   |     |
middle_name   |VARCHAR|YES |NULL                 |     |
email         |VARCHAR|YES |NULL                 |     |
new_age       |INT    |YES |NULL                 |     |
business_email|VARCHAR|NO  |'example@example.com'|     |

-- Remove a column
ALTER TABLE default.users
DROP COLUMN new_age;

DESC default.users;

Field         |Type   |Null|Default              |Extra|
--------------+-------+----+---------------------+-----+
id            |INT    |NO  |0                    |     |
username      |VARCHAR|NO  |''                   |     |
middle_name   |VARCHAR|YES |NULL                 |     |
email         |VARCHAR|YES |NULL                 |     |

例 2: カラムの変更とマスキングポリシー

-- Change column types and defaults
ALTER TABLE users
MODIFY COLUMN age BIGINT DEFAULT 18,
       COLUMN email VARCHAR(320) DEFAULT '';

-- Add masking policy that expects extra arguments
ALTER TABLE users
MODIFY COLUMN email SET MASKING POLICY pii_email USING (email, username);

-- To drop or alter the column, remove the policy first
ALTER TABLE users
MODIFY COLUMN email UNSET MASKING POLICY;

行アクセスポリシー操作

テーブルに行アクセスポリシーを関連付ける、または関連解除します。行アクセスポリシーは、クエリ実行時および DML の対象行マッチング時に行をフィルタリングします。

構文

-- Add a row access policy to a table
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
ADD ROW ACCESS POLICY <policy_name> ON ( <column_name> [ , <column_name> ... ] )

-- Drop a specific row access policy from a table
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
DROP ROW ACCESS POLICY <policy_name>

-- Drop all row access policies from a table
ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
DROP ALL ROW ACCESS POLICIES

例

SET enable_experimental_row_access_policy = 1;

CREATE TABLE employees(id INT, name STRING, department STRING);

CREATE ROW ACCESS POLICY rap_engineering
AS (dept STRING)
RETURNS BOOLEAN -> dept = 'Engineering';

ALTER TABLE employees
ADD ROW ACCESS POLICY rap_engineering ON (department);

ALTER TABLE employees
DROP ROW ACCESS POLICY rap_engineering;

テーブルコメント

テーブルのコメントを変更します。テーブルにまだコメントがない場合、このコマンドは指定したコメントをテーブルに追加します。

構文

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
COMMENT = '<comment>'

例

-- Create a table with a comment
CREATE TABLE t(id INT) COMMENT ='original-comment';

SHOW CREATE TABLE t;

┌──────────────────────────────────────────────────────────────────────────────────────┐
│  Table │                                 Create Table                                │
├────────┼─────────────────────────────────────────────────────────────────────────────┤
│ t      │ CREATE TABLE t (\n  id INT NULL\n) ENGINE=FUSE COMMENT = 'original-comment' │
└──────────────────────────────────────────────────────────────────────────────────────┘

-- Modify the comment
ALTER TABLE t COMMENT = 'new-comment';

SHOW CREATE TABLE t;

┌─────────────────────────────────────────────────────────────────────────────────┐
│  Table │                              Create Table                              │
├────────┼────────────────────────────────────────────────────────────────────────┤
│ t      │ CREATE TABLE t (\n  id INT NULL\n) ENGINE=FUSE COMMENT = 'new-comment' │
└─────────────────────────────────────────────────────────────────────────────────┘

-- Create a table without comment
CREATE TABLE t(id INT);

-- Add a comment later
ALTER TABLE t COMMENT = 'new-comment';

Fuse Engine オプション

テーブルの Fuse Engine オプション を設定または解除します。

構文

-- Set Fuse Engine options
ALTER TABLE [ <database_name>. ]<table_name> SET OPTIONS (<options>)

-- Unset Fuse Engine options, reverting them to their default values
ALTER TABLE [ <database_name>. ]<table_name> UNSET OPTIONS (<options>)

解除できる Fuse Engine オプションは次のものだけです。

  • block_per_segment
  • block_size_threshold
  • data_retention_period_in_hours
  • data_retention_num_snapshots_to_keep
  • enable_schema_evolution
  • row_avg_depth_threshold
  • row_per_block
  • row_per_page

例

CREATE TABLE fuse_table (a int);

SET hide_options_in_show_create_table=0;

-- Show current options
SHOW CREATE TABLE fuse_table;

-- Change Fuse options
ALTER TABLE fuse_table SET OPTIONS (block_per_segment = 500, data_retention_period_in_hours = 240);

-- Show updated options
SHOW CREATE TABLE fuse_table;

-- Limit snapshots and enable auto vacuum
CREATE OR REPLACE TABLE t(c INT);
ALTER TABLE t SET OPTIONS(data_retention_num_snapshots_to_keep = 1);
SET enable_auto_vacuum = 1;
INSERT INTO t VALUES(1);
INSERT INTO t VALUES(2);
INSERT INTO t VALUES(3);

-- Revert options to defaults
ALTER TABLE fuse_table UNSET OPTIONS (block_per_segment, data_retention_period_in_hours);

外部テーブル接続

外部テーブルの接続設定を更新します。コマンド実行時に適用されるのは、認証情報関連のフィールド（access_key_id、secret_access_key、role_arn）のみです。bucket、region、root などのその他のプロパティは変更されません。

構文

ALTER TABLE [ <database_name>. ]<table_name> CONNECTION = ( connection_name = '<connection_name>' )
パラメータ説明必須
connection_name外部テーブルで使用する接続の名前です。この接続はシステム内にすでに存在している必要があります。はい

このコマンドは、認証情報をローテーションする必要がある場合や、IAM ロールが変更された場合に特に便利です。このコマンドで使用する前に、指定した接続がすでに存在している必要があります。

セキュリティのベストプラクティス

外部テーブルを扱う場合、AWS IAM ロールはアクセスキーと比べて大きなセキュリティ上の利点があります。

  • 認証情報を保存しない: 設定内にアクセスキーを保存する必要がなくなります
  • 自動ローテーション: 認証情報のローテーションを自動的に処理します
  • きめ細かな制御: より正確なアクセス制御が可能です

TiDB Cloud Lake で IAM ロールを使用する方法については、AWS IAM Role による認証 を参照してください。

例

-- Create connections
CREATE CONNECTION external_table_conn
    STORAGE_TYPE = 's3'
    ACCESS_KEY_ID = '<your-access-key-id>'
    SECRET_ACCESS_KEY = '<your-secret-access-key>';

CREATE CONNECTION external_table_conn_new
    STORAGE_TYPE = 's3'
    ACCESS_KEY_ID = '<your-new-access-key-id>'
    SECRET_ACCESS_KEY = '<your-new-secret-access-key>';

-- Create an external table using the first connection
CREATE OR REPLACE TABLE external_table_test (
    id INT,
    name VARCHAR,
    age INT
)
's3://testbucket/13_fuse_external_table/'
CONNECTION=(connection_name = 'external_table_conn');

-- Update to use the new connection
ALTER TABLE external_table_test CONNECTION=( connection_name = 'external_table_conn_new' );

-- Migrate to IAM role authentication
CREATE CONNECTION s3_access_key_conn
    STORAGE_TYPE = 's3'
    ACCESS_KEY_ID = '<your-access-key-id>'
    SECRET_ACCESS_KEY = '<your-secret-access-key>';

CREATE TABLE sales_data (
    order_id INT,
    product_name VARCHAR,
    quantity INT
)
's3://sales-bucket/data/'
CONNECTION=(connection_name = 's3_access_key_conn');

CREATE CONNECTION s3_role_conn
    STORAGE_TYPE = 's3'
    ROLE_ARN = 'arn:aws:iam::123456789012:role/lake-access';

ALTER TABLE sales_data CONNECTION=( connection_name = 's3_role_conn' );

スナップショットタグ操作

特定の FUSE テーブルスナップショットを参照する名前付きスナップショットタグを作成または削除します。スナップショットタグを使用すると、テーブルのある時点の状態をブックマークでき、後で AT 句を使ってクエリできます。

詳細については、以下を参照してください。

テーブルの入れ替え

1 つのトランザクション内で、2 つのテーブル間のすべてのテーブルメタデータとデータをアトミックに入れ替えます。この操作では、すべてのカラム、制約、データを含むテーブルスキーマが交換され、結果として各テーブルがもう一方のテーブルの実体を引き継ぎます。

構文

ALTER TABLE [ IF EXISTS ] <source_table_name> SWAP WITH <target_table_name>
パラメータ説明
source_table_name入れ替え元となる 1 つ目のテーブル名
target_table_name入れ替え先となる 2 つ目のテーブル名

使用上の注意

  • Fuse Engine テーブルでのみ使用できます。外部テーブル、システムテーブル、およびその他の非 Fuse テーブルはサポートされません。
  • 一時テーブルは、永続テーブルまたはトランジェントテーブルと入れ替えることはできません。
  • 入れ替え操作を実行するには、現在のロールが両方のテーブルの所有者である必要があります。
  • 両方のテーブルは同じデータベース内に存在する必要があります。データベースをまたぐ入れ替えはサポートされません。
  • 入れ替え操作はアトミックです。両方のテーブルが正常に入れ替えられるか、どちらも変更されないかのいずれかです。
  • 入れ替え中はすべてのデータとメタデータが保持されます。データが失われたり変更されたりすることはありません。

例

-- Create two tables with different schemas
CREATE OR REPLACE TABLE t1(a1 INT, a2 VARCHAR, a3 DATE);
CREATE OR REPLACE TABLE t2(b1 VARCHAR);

-- Check table schemas before swap
DESC t1;
DESC t2;

-- Swap the tables
ALTER TABLE t1 SWAP WITH t2;

-- After swapping, t1 now has t2's schema, and t2 has t1's schema
DESC t1;
DESC t2;

タグ操作

テーブルにガバナンスタグを割り当てる、または削除します。ガバナンスタグは、分類とデータガバナンスのためのキーと値のメタデータです。タグは事前に CREATE TAG で作成しておく必要があります。詳細については、SET TAG / UNSET TAG を参照してください。

構文

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
    SET TAG <tag_name> = '<value>' [, <tag_name> = '<value>' ...]

ALTER TABLE [ IF EXISTS ] [ <database_name>. ]<table_name>
    UNSET TAG <tag_name> [, <tag_name> ...]

例

ALTER TABLE default.users SET TAG env = 'prod', owner = 'team_a';
ALTER TABLE default.users UNSET TAG env, owner;

このページは役に立ちましたか？