> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> テーブルのドキュメント

# CREATE TABLE

新しいテーブルを作成します。デフォルトでは、テーブルは現在のサーバー上にのみ作成されます。
分散 DDL クエリは `ON CLUSTER` 句によって実現されており、これについては[別途説明しています](/ja/reference/statements/distributed-ddl)。

<div id="syntax-forms">
  ## 構文形式
</div>

ユースケースに応じて、このクエリにはさまざまな構文形式があります。

<div id="with-explicit-schema">
  ### 明示的なスキーマを指定してテーブルを作成する
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [NULL|NOT NULL] [DEFAULT|MATERIALIZED|EPHEMERAL|ALIAS expr1] [COMMENT 'comment for column'] [compression_codec] [TTL expr1],
    name2 [type2] [NULL|NOT NULL] [DEFAULT|MATERIALIZED|EPHEMERAL|ALIAS expr2] [COMMENT 'comment for column'] [compression_codec] [TTL expr2],
    ...
) ENGINE = engine
  [COMMENT 'comment for table']
```

`db` が設定されている場合は `db` データベースに、設定されていない場合は現在のデータベースに、括弧内で指定した構造と `engine` エンジンを持つ `table_name` という名前のテーブルを作成します。
テーブルの構造は、カラム定義、セカンダリ索引、プロジェクション、および制約の一覧です。[主キー](#primary-key) が engine でサポートされている場合は、テーブルエンジンのパラメータとして示されます。

最も単純な場合、カラム定義は `name type` です。例: `RegionID UInt32`。

型に続く修飾子である `COMMENT`、`compression_codec`、`STATISTICS`、`TTL`、`COLLATE`、`PRIMARY KEY`、およびカラムごとの `SETTINGS` は、任意の順序で記述でき、それぞれ最大 1 回だけ指定できます。たとえば、`RegionID UInt32 CODEC(ZSTD) COMMENT 'comment for column'` と `RegionID UInt32 COMMENT 'comment for column' CODEC(ZSTD)` は同じです。`SHOW CREATE TABLE` はカラム宣言を正規化することに注意してください。残る修飾子は常に `COMMENT`、`CODEC`、`STATISTICS`、`TTL`、`COLLATE`、`SETTINGS` の正規順序で出力され、カラムごとの `PRIMARY KEY` はカラム宣言からテーブルレベルの `PRIMARY KEY` 句へ移動されます。

デフォルト値用の式も定義できます (下記を参照) 。

必要に応じて、1 つ以上のキー式を使って主キーを指定できます。

カラムおよびテーブルにコメントを追加できます。

<div id="with-a-schema-similar-to-other-table">
  ### 既存テーブルのスキーマを使用してテーブルを作成する
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db2.]table_clone AS [db.]table [ENGINE = engine]
```

ClickHouse では、既存テーブルのスキーマとデータをコピーできます。

既存テーブルのスキーマを複製するには:

これにより、別のテーブルと同じ構造を持つテーブルが作成されます。

<div id="with-a-schema-and-data-cloned-from-another-table">
  ### 既存テーブルのスキーマとデータを使用してテーブルを作成する
</div>

既存テーブルのスキーマとデータを複製するには:

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db2.]table_clone CLONE AS [db.]table [ENGINE = engine]
```

これにより、既存のテーブルと同じスキーマとデータを持つテーブルが作成されます。新しいテーブルの作成後、`db.table` のすべてのパーティションがそのテーブルにアタッチされます。つまり、`db.table` のデータは作成時に `db2.table_clone` に複製されます。このクエリは、次のものと同等です。

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db2.]table_clone AS [db.]table [ENGINE = engine];
ALTER TABLE [db2.]table_clone ATTACH PARTITION ALL FROM [db.]table;
```

どちらの機能でも、テーブルには別のエンジンを指定できます。エンジンを指定しない場合は、元のテーブル (`db.table`) と同じエンジンが使用されます。

<div id="from-a-table-function">
  ### table function を使用してテーブルを作成する
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db.]table_name AS table_function()
```

指定した[table function](/ja/reference/functions/table-functions/index)と同じ結果を返すテーブルを作成します。作成されたテーブルも、指定した対応する table function と同じように動作します。

<div id="from-select-query">
  ### SELECT クエリでテーブルを作成する
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db.]table_name[(name1 [type1], name2 [type2], ...)] ENGINE = engine AS SELECT ...
```

`SELECT` クエリの結果と同様の構造を持つテーブルを `engine` エンジンで作成し、`SELECT` のデータを格納します。カラム定義を明示的に指定することもできます。

テーブルがすでに存在し、`IF NOT EXISTS` が指定されている場合、このクエリは何も実行しません。

クエリでは、`ENGINE` 句の後にほかの句を続けることもできます。テーブルの作成方法の詳細については、[テーブルエンジン](/ja/reference/engines/table-engines/index) の説明を参照してください。

**例**

```sql title="Query" theme={null}
CREATE TABLE t1 (x String) ENGINE = Memory AS SELECT 1;
SELECT x, toTypeName(x) FROM t1;
```

```text title="Response" theme={null}
┌─x─┬─toTypeName(x)─┐
│ 1 │ String        │
└───┴───────────────┘
```

<div id="default_values">
  ## カラムのデフォルト値を指定する
</div>

カラム定義では、`DEFAULT expr`、`MATERIALIZED expr`、または `ALIAS expr` の形式でデフォルト値の式を指定できます。例: `URLDomain String DEFAULT domain(URL)`。

式 `expr` は省略可能です。省略した場合は、カラム型を明示的に指定する必要があります。その場合のデフォルト値は、数値カラムでは `0`、文字列カラムでは `''` (空文字列) 、配列カラムでは `[]` (空の配列) 、日付カラムでは `1970-01-01`、Nullable カラムでは `NULL` になります。

デフォルト値を持つカラムでは、カラム型を省略でき、その場合は `expr` の型から推論されます。たとえば、`EventDate DEFAULT toDate(EventTime)` というカラムの型は date になります。

データ型とデフォルト値の式の両方が指定されている場合は、式を指定された型に変換する暗黙的な型キャスト関数が挿入されます。例: `Hits UInt32 DEFAULT 0` は内部的には `Hits UInt32 DEFAULT toUInt32(0)` として表現されます。

デフォルト値の式 `expr` では、任意のテーブルカラムや定数を参照できます。ClickHouse は、テーブル構造の変更によって式の計算にループが生じないことを確認します。INSERT では、式を解決可能であること、つまり式の計算に必要なすべてのカラムが渡されていることを確認します。

<div id="default">
  ### DEFAULT
</div>

`DEFAULT expr`

通常のデフォルト値です。この種のカラムでは、値が INSERT クエリで指定されていない場合、`expr` から計算されます。

例:

```sql theme={null}
CREATE OR REPLACE TABLE test
(
    id UInt64,
    updated_at DateTime DEFAULT now(),
    updated_at_date Date DEFAULT toDate(updated_at)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test (id) VALUES (1);

SELECT * FROM test;
┌─id─┬──────────updated_at─┬─updated_at_date─┐
│  1 │ 2023-02-24 17:06:46 │      2023-02-24 │
└────┴─────────────────────┴─────────────────┘
```

<div id="materialized">
  ### MATERIALIZED
</div>

`MATERIALIZED expr`

マテリアライズ式です。このようなカラムの値は、行の挿入時に、指定されたマテリアライズ式に基づいて自動的に計算されます。`INSERT` 時に値を明示的に指定することはできません。

また、この型のデフォルト値カラムは、`SELECT *` の結果に含まれません。これは、`SELECT *` の結果を常に `INSERT` を使ってテーブルにそのまま挿入し直せるという不変条件を保つためです。この動作は、setting `asterisk_include_materialized_columns` を使用すると無効にできます。

例:

```sql theme={null}
CREATE OR REPLACE TABLE test
(
    id UInt64,
    updated_at DateTime MATERIALIZED now(),
    updated_at_date Date MATERIALIZED toDate(updated_at)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test VALUES (1);

SELECT * FROM test;
┌─id─┐
│  1 │
└────┘

SELECT id, updated_at, updated_at_date FROM test;
┌─id─┬──────────updated_at─┬─updated_at_date─┐
│  1 │ 2023-02-24 17:08:08 │      2023-02-24 │
└────┴─────────────────────┴─────────────────┘

SELECT * FROM test SETTINGS asterisk_include_materialized_columns=1;
┌─id─┬──────────updated_at─┬─updated_at_date─┐
│  1 │ 2023-02-24 17:08:08 │      2023-02-24 │
└────┴─────────────────────┴─────────────────┘
```

<div id="ephemeral">
  ### EPHEMERAL
</div>

`EPHEMERAL [expr]`

一時的なカラムです。この型のカラムはテーブルに保存されず、`SELECT` で取得することもできません。ephemeral カラムの唯一の用途は、これらを使って他のカラムのデフォルト値式を構築することです。

カラムを明示的に指定しない `INSERT` では、この型のカラムはスキップされます。これは、`SELECT *` の結果を常に `INSERT` を使ってテーブルにそのまま挿入し直せるという不変条件を保つためです。

例:

```sql theme={null}
CREATE OR REPLACE TABLE test
(
    id UInt64,
    unhexed String EPHEMERAL,
    hexed FixedString(4) DEFAULT unhex(unhexed)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test (id, unhexed) VALUES (1, '5a90b714');

SELECT
    id,
    hexed,
    hex(hexed)
FROM test
FORMAT Vertical;

Row 1:
──────
id:         1
hexed:      Z��
hex(hexed): 5A90B714
```

<div id="alias">
  ### ALIAS
</div>

`ALIAS expr`

計算カラム (同義語) です。この型のカラムはテーブルに保存されず、これらに値を `INSERT` することはできません。

`SELECT` クエリでこの型のカラムを明示的に参照すると、値はクエリ時に `expr` から計算されます。デフォルトでは、`SELECT *` には ALIAS カラムは含まれません。この動作は、設定 `asterisk_include_alias_columns` によって無効にできます。

ALTER クエリを使って新しいカラムを追加しても、それらのカラムについて古いデータは書き込まれません。代わりに、新しいカラムの値を持たない古いデータを読み取る際には、デフォルトで式がその場で計算されます。ただし、その式の実行にクエリ内で指定されていない別のカラムが必要な場合は、それらのカラムも追加で読み取られますが、必要なデータブロックに対してのみ行われます。

テーブルに新しいカラムを追加したあとでそのデフォルト式を変更すると、古いデータに対して使われる値も変わります (ディスクに値が保存されていないデータについて) 。バックグラウンドマージの実行時には、マージ対象のいずれかのパーツに存在しないカラムのデータは、マージ後のパーツに書き込まれる点に注意してください。

ネストされたデータ構造内の要素には、デフォルト値を設定できません。

```sql theme={null}
CREATE OR REPLACE TABLE test
(
    id UInt64,
    size_bytes Int64,
    size String ALIAS formatReadableSize(size_bytes)
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO test VALUES (1, 4678899);

SELECT id, size_bytes, size FROM test;
┌─id─┬─size_bytes─┬─size─────┐
│  1 │    4678899 │ 4.46 MiB │
└────┴────────────┴──────────┘

SELECT * FROM test SETTINGS asterisk_include_alias_columns=1;
┌─id─┬─size_bytes─┬─size─────┐
│  1 │    4678899 │ 4.46 MiB │
└────┴────────────┴──────────┘
```

<div id="null-or-not-null-modifiers">
  ## NULL または NOT NULL 修飾子
</div>

カラム定義では、データ型の後ろに `NULL` および `NOT NULL` 修飾子を付けることで、その型を [Nullable](/ja/reference/data-types/nullable) にできるかどうかを指定できます。

型が `Nullable` ではない場合、`NULL` を指定すると `Nullable` として扱われ、`NOT NULL` を指定した場合はそのまま `Nullable` にはなりません。たとえば、`INT NULL` は `Nullable(INT)` と同じです。型が `Nullable` であるにもかかわらず `NULL` または `NOT NULL` 修飾子を指定すると、例外がスローされます。

関連項目: [data\_type\_default\_nullable](/ja/reference/settings/session-settings/other#data_type_default_nullable) 設定。

<div id="primary-key">
  ## 主キー
</div>

テーブルの作成時に[主キー](/ja/reference/engines/table-engines/mergetree-family/mergetree#primary-keys-and-indexes-in-queries)を定義できます。主キーは、次の2つの方法で指定できます。

<Columns cols={2}>
  <div>
    **カラムリスト内**

    ```sql theme={null}
    CREATE TABLE [db.]table_name
    (
        name1 type1, name2 type2, ...,
        PRIMARY KEY(expr1[, expr2,...])
    )
    ENGINE = engine;
    ```
  </div>

  <div>
    **カラムリストの外**

    ```sql theme={null}
    CREATE TABLE [db.]table_name
    (
        name1 type1, name2 type2, ...
    )
    ENGINE = engine
    PRIMARY KEY(expr1[, expr2,...]);
    ```
  </div>
</Columns>

<Tip>
  1つのクエリで両方の方法を併用することはできません。
</Tip>

<div id="constraints">
  ## テーブル制約を指定する
</div>

カラムの説明に加えて、制約も定義できます:

<div id="constraint">
  ### CONSTRAINT
</div>

```sql theme={null}
CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1] [compression_codec] [TTL expr1],
    ...
    CONSTRAINT constraint_name_1 CHECK boolean_expr_1,
    ...
) ENGINE = engine
```

`boolean_expr_1` には任意のブール式を指定できます。テーブルに制約が定義されている場合、`INSERT` クエリの各行に対してそれぞれの制約がチェックされます。いずれかの制約が満たされていない場合、サーバーは制約名とチェック式を含む例外を返します。

大量の制約を追加すると、大規模な `INSERT` クエリのパフォーマンスに悪影響を及ぼす可能性があります。

すべてのテーブルにある既存の制約は、[`system.constraints`](/ja/reference/system-tables/constraints) テーブルで確認できます。

<div id="assume">
  ### ASSUME
</div>

`ASSUME` 句は、真であると仮定される table に対する `CONSTRAINT` を定義するために使用されます。この制約は、その後オプティマイザによって SQL queries のパフォーマンス向上に利用されます。

`users_a` table の作成時に `ASSUME CONSTRAINT` が使われている次の例を見てみましょう。

```sql theme={null}
CREATE TABLE users_a (
    uid Int16, 
    name String, 
    age Int16, 
    name_len UInt8 MATERIALIZED length(name), 
    CONSTRAINT c1 ASSUME length(name) = name_len
) 
ENGINE=MergeTree 
ORDER BY (name_len, name);
```

ここでは、`ASSUME CONSTRAINT` を使って、`length(name)` 関数が常に `name_len` カラムの値と等しいことを前提としていることを示しています。つまり、クエリ内で `length(name)` が呼び出されるたびに、ClickHouse はそれを `name_len` に置き換えることができます。これにより `length()` 関数を呼び出さずに済むため、通常はそのほうが高速です。

そのため、クエリ `SELECT name FROM users_a WHERE length(name) < 5;` を実行する際、ClickHouse は `ASSUME CONSTRAINT` に基づいて、これを `SELECT name FROM users_a WHERE name_len < 5`; に最適化できます。これにより、各行ごとに `name` の長さを計算する必要がなくなるため、クエリの実行速度が向上する可能性があります。

`ASSUME CONSTRAINT` **は制約を強制するものではありません**。これは、その制約が成り立つことをオプティマイザに知らせるだけです。制約が実際には成り立っていない場合、クエリの結果が不正確になる可能性があります。したがって、`ASSUME CONSTRAINT` は、その制約が正しいと確信できる場合にのみ使用してください。

<div id="ttl-expression">
  ## TTL で保存期間を定義する
</div>

値の保存期間を定義します。指定できるのは MergeTree ファミリーのテーブルのみです。詳細は、[カラムとテーブルの TTL](/ja/reference/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-ttl) を参照してください。

<div id="column_compression_codec">
  ## カラム圧縮コーデックを選択する
</div>

<a id="general-purpose-codecs" />

<a id="none" />

<a id="lz4" />

<a id="lz4hc" />

<a id="zstd" />

<a id="zxc" />

<a id="zstd_qat" />

<a id="deflate_qpl" />

<a id="specialized-codecs" />

<a id="delta" />

<a id="doubledelta" />

<a id="gcd" />

<a id="gorilla" />

<a id="alp" />

<a id="fpc" />

<a id="sz3" />

<a id="t64" />

<a id="quantized" />

<a id="encryption-codecs" />

<a id="aes_128_gcm_siv" />

<a id="aes-256-gcm-siv" />

<a id="adaptive-codec-selection" />

デフォルトでは、セルフマネージド版のClickHouseには `lz4` 圧縮が、ClickHouse Cloudには `zstd` 圧縮が適用されます。`CREATE TABLE` クエリでは、カラムごとに圧縮方式を指定することもできます。

```sql theme={null}
CREATE TABLE codec_example
(
    dt Date CODEC(ZSTD),
    ts DateTime CODEC(LZ4HC),
    float_value Float32 CODEC(NONE),
    double_value Float64 CODEC(LZ4HC(9)),
    value Float32 CODEC(Delta, ZSTD)
)
ENGINE = <Engine>
...
```

利用可能な汎用、特殊用途、および暗号化 コーデック については、[カラム圧縮 コーデック](/ja/reference/statements/create/table/codec)を参照してください。

<div id="temporary-tables">
  ## 一時テーブルの作成
</div>

ClickHouse は一時テーブルをサポートしています。一時テーブルはセッションの終了時に削除されます。詳細については、[CREATE TEMPORARY TABLE](/ja/reference/statements/create/table/temporary-table) を参照してください。

<div id="replace-table">
  ## REPLACE TABLE でテーブルをアトミックに更新する
</div>

<a id="syntax" />

<a id="examples" />

`REPLACE` ステートメントを使用すると、テーブルを[アトミックに](/ja/concepts/core-concepts/glossary#atomicity)更新できます。詳細については、[REPLACE TABLE](/ja/reference/statements/create/table/replace-table)を参照してください。

<div id="comment-clause">
  ## テーブルコメントを追加する
</div>

テーブルの作成時にコメントを追加できます。

**構文**

```sql theme={null}
CREATE TABLE [db.]table_name
(
    name1 type1, name2 type2, ...
)
ENGINE = engine
COMMENT 'Comment'
```

<Note>
  `COMMENT` 句は、`PARTITION BY`、`ORDER BY`、ストレージ固有の `SETTINGS` など、ストレージ固有の句の**後**に指定する必要があります。

  `COMMENT` 句の後に解析されるのは、ストレージ関連の設定ではなく、`max_threads` などのクエリ固有の `SETTINGS` のみです。

  つまり、句の正しい順序は次のとおりです。

  * `ENGINE`
  * ストレージ句
  * `COMMENT`
  * クエリ設定 (ある場合)
</Note>

**例**

```sql title="Query" theme={null}
CREATE TABLE t1 (x String) ENGINE = Memory COMMENT 'The temporary table';
SELECT name, comment FROM system.tables WHERE name = 't1';
```

```text title="Response" theme={null}
┌─name─┬─comment─────────────┐
│ t1   │ The temporary table │
└──────┴─────────────────────┘
```

<div id="related-content">
  ## 関連コンテンツ
</div>

* ブログ: [スキーマとコーデックによるClickHouseの最適化](https://clickhouse.com/blog/optimize-clickhouse-codecs-compression-schema)
* ブログ: [ClickHouseで時系列データを扱う](https://clickhouse.com/blog/working-with-time-series-data-and-functions-ClickHouse)