> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> CREATE TABLE 文のカラム圧縮コーデック

# カラム圧縮コーデック

export const ExperimentalBadge = () => {
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#experimental-features" className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            実験的な機能
        </a>;
};

export const CloudNotSupportedBadge = () => {
  return <a href="https://clickhouse.com/docs/products/cloud/guides/cloud-compatibility#list-of-unsupported-features" className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            ClickHouse Cloud ではサポートされていません
        </a>;
};

デフォルトでは、ClickHouse はセルフマネージド版では `lz4` 圧縮を使用し、ClickHouse Cloud では `zstd` を使用します。

`MergeTree` エンジンファミリーでは、サーバー設定の [compression](/docs/ja/reference/settings/server-settings/settings/other#compression) セクションでデフォルトの圧縮方式を変更できます。

各カラムの圧縮方式は、[`CREATE TABLE`](/docs/ja/reference/statements/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>
...
```

`Default` コーデックを指定すると、実行時の各種設定 (およびデータのプロパティ) に応じたデフォルトの圧縮を参照できます。
例: `value UInt64 CODEC(Default)` — コーデックを指定しない場合と同じです。
[適応型コーデック選択](#adaptive-codec-selection)も参照してください。

また、カラムから現在のCODECを削除し、config.xmlで指定されたデフォルトの圧縮を使用することもできます。

```sql theme={null}
ALTER TABLE codec_example MODIFY COLUMN float_value CODEC(Default);
```

コーデックはパイプラインとして組み合わせることができます。例: `CODEC(Delta, Default)`。

<Tip>
  `lz4` などの外部ユーティリティでは、ClickHouse のデータベースファイルを展開できません。代わりに、専用の [clickhouse-compressor](https://github.com/ClickHouse/ClickHouse/tree/master/programs/compressor) ユーティリティを使用してください。
</Tip>

圧縮は、以下のテーブルエンジンでサポートされています。

* [MergeTree](/docs/ja/reference/engines/table-engines/mergetree-family/mergetree) ファミリー。カラム圧縮コーデックと、[compression](/docs/ja/reference/settings/server-settings/settings/other#compression) 設定でデフォルトの圧縮方式を選択する機能をサポートします。
* [Log](/docs/ja/reference/engines/table-engines/log-family/index) ファミリー。デフォルトでは `lz4` 圧縮方式を使用し、カラム圧縮コーデックをサポートします。
* [Set](/docs/ja/reference/engines/table-engines/special/set)。デフォルトの圧縮のみをサポートします。
* [Join](/docs/ja/reference/engines/table-engines/special/join)。デフォルトの圧縮のみをサポートします。

ClickHouse は、汎用コーデックと特殊用途のコーデックをサポートしています。

<div id="general-purpose-codecs">
  ## 汎用コーデック
</div>

<div id="none">
  ### NONE
</div>

`NONE` — 圧縮なし。

<div id="lz4">
  ### LZ4
</div>

`LZ4` — デフォルトで使用される可逆[データ圧縮アルゴリズム](https://github.com/lz4/lz4)です。LZ4 の高速圧縮を使用します。

<div id="lz4hc">
  ### LZ4HC
</div>

`LZ4HC[(level)]` — レベルを設定可能な LZ4 HC (高圧縮) アルゴリズム。デフォルトレベルは 9 です。`level <= 0` を指定すると、デフォルトレベルが適用されます。指定可能なレベル: \[1, 12]。推奨レベル範囲: \[4, 9]。

<div id="zstd">
  ### ZSTD
</div>

`ZSTD[(level)]` — `level`を指定可能な[ZSTD圧縮アルゴリズム](https://en.wikipedia.org/wiki/Zstandard)。指定可能なレベル: \[1, 22]。デフォルトのレベル: 1。

高い圧縮レベルは、1回圧縮して何度も展開するような非対称なシナリオで有用です。レベルが高いほど圧縮率は向上しますが、CPU使用率も高くなります。

<div id="zxc">
  ### ZXC
</div>

<ExperimentalBadge />

`ZXC[(level)]` — `level` を設定可能な非対称 [`zxc` 圧縮アルゴリズム](https://github.com/hellobertrand/zxc)。指定可能なレベル: \[1, 7]。デフォルトレベル: 3。

`ZXC` は、圧縮速度を犠牲にする代わりに非常に高速な展開を実現し、圧縮率は `LZ4` と `ZSTD` の中間です。一度圧縮して何度も展開するパターンに適しており、最新の ARM コアでは最も高速に展開されます。レベルを上げるほど圧縮率は向上し、圧縮速度は低下しますが、展開は高速なままです。

<Note>
  このコーデックは実験的機能であり、使用するには `SET allow_experimental_codecs = 1` が必要です。
</Note>

<div id="zstd_qat">
  ### 廃止された: ZSTD\_QAT
</div>

<CloudNotSupportedBadge />

<div id="deflate_qpl">
  ### 廃止された: DEFLATE\_QPL
</div>

<CloudNotSupportedBadge />

<div id="specialized-codecs">
  ## 特殊用途のコーデック
</div>

これらのコーデックは、データ固有の特性を利用して、より効果的に圧縮できるよう設計されています。一部のコーデックはデータ自体を圧縮するのではなく、データを前処理します。これにより、汎用コーデックを使用する後続の圧縮段階で、より高い圧縮率を実現できます。

<div id="delta">
  ### Delta
</div>

`Delta(delta_bytes)` — 最初の値を除き、生データの値を隣接する2つの値の差に置き換える圧縮方式です。最初の値はそのまま保持されます。`delta_bytes` は生データの値の最大サイズで、デフォルト値は `sizeof(type)` です。引数としての `delta_bytes` の指定は非推奨であり、今後のリリースでサポートが削除される予定です。Delta はデータ準備コーデックであるため、単独では使用できません。

<div id="doubledelta">
  ### DoubleDelta
</div>

`DoubleDelta(bytes_size)` — デルタの差を計算し、コンパクトなバイナリ形式で書き込みます。`bytes_size` は、[Delta](#delta) コーデック の `delta_bytes` と同様の意味を持ちます。引数としての `bytes_size` の指定は非推奨であり、今後のリリースでサポートが削除されます。時系列データのように stride が一定の単調な数列では、最適な圧縮率が得られます。任意の数値型で使用できます。Gorilla TSDB で使用されるアルゴリズムを実装し、64 ビット型をサポートするように拡張しています。32 ビットのデルタでは追加で 1 ビットを使用し、4 ビットのプレフィックスではなく 5 ビットのプレフィックスを使用します。詳細については、[Gorilla: A Fast, Scalable, In-Memory Time Series Database](http://www.vldb.org/pvldb/vol8/p1816-teller.pdf) の「Compressing Time Stamps」を参照してください。DoubleDelta はデータ準備 コーデック であるため、単独では使用できません。

<div id="gcd">
  ### GCD
</div>

`GCD()` - - カラム内の値の最大公約数 (GCD) を計算し、各値をGCDで除算します。整数、小数、日付/時刻のカラムで使用できます。このコーデックは、24、28、16、24、8、24 (GCD = 4) のように、値がGCDの倍数ずつ増減するカラムに適しています。GCDはデータ準備コーデックであるため、単独では使用できません。

<div id="gorilla">
  ### Gorilla
</div>

`Gorilla(bytes_size)` — 現在と直前の浮動小数点値の XOR を計算し、compact なバイナリ形式で書き込みます。連続する値の差が小さいほど、つまり時系列の値の変化が緩やかなほど、圧縮率が向上します。Gorilla TSDB で使用されているアルゴリズムを実装し、64 ビット型をサポートするよう拡張しています。`bytes_size` に指定できる値は 1、2、4、8 です。デフォルト値は、`sizeof(type)` が 1、2、4、8 のいずれかであればその値、それ以外の場合は 1 です。詳細については、[Gorilla: A Fast, Scalable, In-Memory Time Series Database](https://doi.org/10.14778/2824032.2824078) のセクション 4.1 を参照してください。

<div id="alp">
  ### ALP
</div>

<ExperimentalBadge />

`ALP(variant)` — 浮動小数点データ向けの適応型可逆圧縮です。`Float32` と `Float64` をサポートします。詳細については、[ALP: Adaptive lossless floating-point compression](https://ir.cwi.nl/pub/33334)を参照してください。

このコーデックは省略可能なバリアント引数を受け取ります。

* `ALP()` または `ALP(AUTO)` (デフォルト) — 推定圧縮サイズに基づいて STD を使用し、必要に応じて RD にフォールバックします。
* `ALP(STD)` — 標準の ALP バリアント。各値を 10 のべき乗でスケーリングした正確な整数として表現し、得られた整数を Frame-of-Reference とビットパッキングで圧縮します。表現できない値は生データの例外として保存されます。小数値に由来する数値 (例: 測定値、価格) に最適です。
* `ALP(RD)` — Real Doubles バリアント。各値のビットパターンを再解釈し、高位部分 (符号 + 指数 + 仮数の上位ビット) と低位部分に分割します。高位部分は Dictionary エンコード (最大 8 エントリ) され、低位部分はビットパッキングされます。多くの値で上位ビットが共通している場合に最適です。

<Note>
  このコーデックは実験的機能であり、使用するには `SET allow_experimental_codecs = 1` が必要です。
</Note>

<div id="fpc">
  ### FPC
</div>

`FPC(level, float_size)` - 数列内の次の浮動小数点値を、2 つの予測器のうち精度の高い方を使って繰り返し予測し、実際の値と予測値の XOR を取り、その結果を先行ゼロ圧縮します。Gorilla と同様に、変化の緩やかな浮動小数点値の系列を保存する場合に効率的です。64 ビット値 (double) では FPC は Gorilla より高速ですが、32 ビット値では性能が異なる場合があります。指定可能な `level` の値は 1～28 で、デフォルト値は 12 です。指定可能な `float_size` の値は 4、8 で、型が Float の場合、デフォルト値は `sizeof(type)` です。それ以外の場合は 4 です。アルゴリズムの詳細については、[High Throughput Compression of Double-Precision Floating-Point Data](https://userweb.cs.txstate.edu/~burtscher/papers/dcc07a.pdf) を参照してください。

<div id="sz3">
  ### SZ3
</div>

<ExperimentalBadge />

`SZ3` または `SZ3(algorithm, error_bound_mode, error_bound)` - Float32、Float64、Array(Float32)、または Array(Float64) 型のカラムに対応する、誤差上限を指定できる非可逆 コーデック ([SZ3 Lossy Compressor](https://szcompressor.org/)) です。配列カラムでは、すべての配列の長さが同じ場合に最も効果的に圧縮されます (この場合、固定幅ベクトルとして圧縮されます) 。長さが異なる配列もサポートされますが、値のフラットな数列として圧縮されます。Map カラムには適用できません。非可逆圧縮によってキーが破損するためです。`algorithm` でサポートされる値は `ALGO_LORENZO_REG`、`ALGO_INTERP_LORENZO`、`ALGO_INTERP` です。`error_bound_mode` でサポートされる値は `ABS`、`REL`、`PSNR`、`ABS_AND_REL` です。引数 `error_bound` は最大誤差を指定し、Float64 型です。

<Note>
  この コーデック は実験的機能です。使用するには `SET allow_experimental_codecs = 1` を設定する必要があります。
</Note>

<div id="t64">
  ### T64
</div>

`T64` — 整数データ型 (`Enum`、`Date`、`DateTime` を含む) の値に含まれる未使用の上位ビットを切り詰める圧縮方式です。このアルゴリズムの各ステップで、コーデック は 64 個の値からなる ブロック を取得し、それらを 64x64 のビット行列に配置して転置し、値の未使用ビットを切り詰めた後、残りを数列として返します。未使用ビットとは、この圧縮方式が使用されるデータパート全体において、最大値と最小値で異ならないビットです。

`DoubleDelta` と `Gorilla` コーデック は、Gorilla TSDB の圧縮アルゴリズムの構成要素として使用されています。Gorilla 方式は、タイムスタンプを伴う緩やかに変化する値の数列を扱うシナリオで効果を発揮します。タイムスタンプは `DoubleDelta` コーデック で、値は `Gorilla` コーデック で効率的に圧縮されます。たとえば、効率的に保存できる テーブル を作成するには、次の configuration を使用します。

```sql theme={null}
CREATE TABLE codec_example
(
    timestamp DateTime CODEC(DoubleDelta),
    slow_values Float32 CODEC(Gorilla)
)
ENGINE = MergeTree()
```

<div id="quantized">
  ### Quantized
</div>

<ExperimentalBadge />

`Quantized(method, dimensions[, ...])` — `Array(Float32)`、`Array(Float64)`、または `Array(BFloat16)` 型のカラムで近似ベクトル検索をサポートする専用コーデックです。
元のフル精度ベクトルに加えて、各ベクトルに対応するコンパクトな*量子化コード*も保存します。
`MergeTree` ファミリーのテーブルでは、設定 [`vector_search_use_quantized_codes`](/docs/ja/reference/settings/session-settings/vector-search#vector_search_use_quantized_codes) を使用するベクトル検索クエリは、量子化コードをスキャンしてショートリストを作成した後、フル精度ベクトルに対して結果を再スコアリングします。
この2段階検索では、再現率は低下しますが、通常のフル精度スキャンよりも読み取りバイト数を削減できます。
`dimensions` はベクトル長を表します。サポートされる `method` の値は `rabitq`、`turboquant`、`int8`、`prefix`、`product` で、それぞれサイズ、精度、距離関数の間で異なるトレードオフがあります。

このコーデックは `CREATE TABLE` でのみ設定でき、`ADD COLUMN ... CODEC(Quantized(...))` を含め、`ALTER TABLE` で追加、削除、変更することはできません。
暗号化コーデックの `AES_128_GCM_SIV` を含め、他のコーデックと連結することはできません。
詳細については、[量子化コーデックを使用したベクトル検索](/docs/ja/reference/engines/table-engines/mergetree-family/annindexes#vector-search-with-quantized-codecs) を参照してください。

```sql theme={null}
SET allow_experimental_codecs = 1;

CREATE TABLE vectors
(
    id UInt32,
    vec Array(BFloat16) CODEC(Quantized('rabitq', 1536))
)
ENGINE = MergeTree ORDER BY id;
```

<div id="encryption-codecs">
  ## 暗号化コーデック
</div>

これらのコーデックは実際にはデータを圧縮せず、代わりにディスク上のデータを暗号化します。[encryption](/docs/ja/reference/settings/server-settings/settings/other#encryption)設定で暗号化キーが指定されている場合にのみ使用できます。暗号化されたデータは通常、有意に圧縮できないため、暗号化はコーデックパイプラインの最後にのみ適しています。

暗号化コーデック:

<div id="aes_128_gcm_siv">
  ### AES\_128\_GCM\_SIV
</div>

`CODEC('AES-128-GCM-SIV')` — [RFC 8452](https://tools.ietf.org/html/rfc8452) のGCM-SIVモードでAES-128を使用し、データを暗号化します。

<div id="aes-256-gcm-siv">
  ### AES-256-GCM-SIV
</div>

`CODEC('AES-256-GCM-SIV')` — AES-256 を GCM-SIV モードで使用してデータを暗号化します。

これらのコーデックは固定 nonce を使用するため、暗号化は決定論的です。そのため、[ReplicatedMergeTree](/docs/ja/reference/engines/table-engines/mergetree-family/replication) などの重複排除機能を持つエンジンと互換性がありますが、弱点もあります。同じデータブロックを 2 回暗号化すると、生成される暗号文は完全に同一になります。そのため、ディスクを読み取れる攻撃者は同一性を確認できます (ただし、内容は取得できません) 。

<Note>
  "\*MergeTree" ファミリーを含むほとんどのエンジンは、コーデックを適用せずにディスク上に索引ファイルを作成します。つまり、暗号化されたカラムに索引が作成されている場合、平文がディスク上に残ります。
</Note>

<Note>
  暗号化されたカラム内の特定の値を指定する SELECT クエリ (WHERE 句など) を実行すると、その値が [system.query\_log](/docs/ja/reference/system-tables/query_log) に記録される場合があります。ロギングを無効にすることを検討してください。
</Note>

**例**

```sql theme={null}
CREATE TABLE mytable
(
    x String CODEC(AES_128_GCM_SIV)
)
ENGINE = MergeTree ORDER BY x;
```

<Note>
  圧縮が必要な場合は、明示的に指定する必要があります。指定しない場合、データには暗号化のみが適用されます。
</Note>

**例**

```sql theme={null}
CREATE TABLE mytable
(
    x String CODEC(Delta, LZ4, AES_128_GCM_SIV)
)
ENGINE = MergeTree ORDER BY x;
```

<div id="adaptive-codec-selection">
  ## 適応型コーデック選択
</div>

<ExperimentalBadge />

上記の特殊用途のコーデックは適切なデータを大幅に圧縮できますが、選択には専門知識が必要であり、時間とともにデータが変化するカラムに常に最適な単一の選択肢があるとは限りません。MergeTree 設定 [`allow_experimental_adaptive_codec_selection`](/docs/ja/reference/settings/merge-tree-settings) を有効にすると、ClickHouse が自動的に選択します。デフォルトのコーデック (`CODEC(Default)` または `CODEC` の指定なし) を使用するカラムでは、各ブロックはテーブル'のデフォルトコーデック、`NONE`、およびカラム型に適した特殊用途のコーデックの中から、最も小さく圧縮できるコーデックで書き込まれます。

ブロックがデフォルトコーデック使用時より大きくなることはなく、圧縮できないデータは生データとして保存されます (圧縮するとファイルがわずかに大きくなり、読み取りも遅くなるためです) 。この処理は、いずれにしてもデータが再圧縮される、バックグラウンドでのマージとミューテーション時に行われます。挿入速度には影響しません。ディスクから取得するデータ量が減り、クエリで読み取るすべてのブロックはまず展開する必要があり、特殊なコーデックはデフォルトの `LZ4` より高速に展開できるため、クエリは多くの場合高速になります。各ブロックには書き込み時に使用したコーデックが記録されるため、読み取り時に設定は不要です。また、すべてのデータを読み取り可能なまま、いつでもこの機能を無効にできます。

```sql theme={null}
CREATE TABLE adaptive
(
    time DateTime,
    user_id UInt64
)
ENGINE = MergeTree
ORDER BY time
SETTINGS allow_experimental_adaptive_codec_selection = 1;

INSERT INTO adaptive SELECT toDateTime('2026-01-01') + number, cityHash64(number) FROM numbers(1000000);
OPTIMIZE TABLE adaptive FINAL;
```

[`mergeTreeCodecBlockCounts`](/docs/ja/reference/functions/table-functions/mergeTreeCodecBlockCounts) テーブル関数を使用すると、その仕組みを確認できます。ここでは `time` が一定に増加するため、ブロック内で変化するビットのみを保存する `T64` は、すべてのブロックでデフォルトの コーデック よりも優れた結果を示しました。`user_id` にはどの コーデック でも圧縮できない hash が格納されているため、そのブロックは生データのまま保存されました：

```sql theme={null}
SELECT column, codec_block_counts FROM mergeTreeCodecBlockCounts(currentDatabase(), 'adaptive');
```

```text theme={null}
   ┌─column──┬─codec_block_counts─┐
1. │ time    │ {'T64':62}         │
2. │ user_id │ {'NONE':123}       │
   └─────────┴────────────────────┘
```

現在選択対象となるのは、整数、列挙型、日付・時刻、`Decimal32`/`Decimal64`、`IPv4`などの整数系カラムです。

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