その他の MergeTree テーブル設定

これらの設定は system.merge_tree_settings で確認でき、ClickHouse のソースコードから自動生成されています。

アダプティブ書き込みバッファの初期サイズ

true に設定すると、CollapsingMergeTree または VersionedCollapsingMergeTree テーブルの sign カラムに暗黙的な制約が追加され、 有効な値 (1 と -1) のみを許可します。

セカンダリ索引の対象になっているカラムを変更する ALTER コマンドを許可するかどうか、および 許可する場合にどのような処理を行うかを設定します。デフォルトでは、このような ALTER コマンドは許可され、索引は再構築されます。

設定可能な値:

• rebuild (default): ALTER コマンド内のカラムの影響を受けるセカンダリ索引を再構築します。
• throw: 例外を送出し、明示的 なセカンダリ索引の対象になっているカラムに対する ALTER をすべて禁止します。暗黙的な索引はこの制限の対象外であり、再構築されます。
• drop: 依存するセカンダリ索引を削除します。新しいパーツにはその索引が含まれなくなるため、再作成するには MATERIALIZE INDEX が必要です。
• compatibility: 元の動作に合わせます。ALTER ... MODIFY COLUMN では throw、ALTER ... UPDATE/DELETE では rebuild になります。
• ignore: 熟練者向けです。索引を不整合な状態のままにするため、誤ったクエリ結果を招く可能性があります。

ミューテーション/replace/detach などの際は、ハードリンクではなく常にデータをコピーします。

true の場合、マージ時にパッチパーツが適用されます

有効にすると、新しく作成される各パーツに一意の識別子が割り当てられます。 有効にする前に、すべてのレプリカが UUID バージョン 4 をサポートしていることを確認してください。

適切なすべてのカラムに対して自動的に計算する統計タイプのカンマ区切りリストです。 サポートされている統計タイプ: basic, tdigest, countmin, uniq, uniq_v2。 minmax 統計タイプは非推奨です。これは basic の部分集合であるため、代わりに basic を使用してください。

マージ または mutation の 1 ステップの実行に要する目標時間です。1 ステップの処理に これより長い時間がかかる場合は、この時間を超えることがあります

廃止された設定で、効果はありません。

レプリカのクローン時に ZooKeeper の multi-create get-part リクエストで使用するバッチサイズ。

主キーに含まれない sampling expression を持つテーブルの作成を許可します。これは、 後方互換性のために、不正なテーブルを含む状態でサーバーを一時的に実行できるようにする場合にのみ 必要です。

insert および マージ 時に、スパース シリアライゼーションを判断するための、より低コストな sampling による推定ではなく、 各カラムのデフォルト値数を正確に計算します。 これは、永続化された num_defaults カウンターを利用する optimize_trivial_count_with_sparsity_filter で必要になります (Nullable カラムでは、 さらに nullable_serialization_version = 'allow_sparse' が必要です) 。 無効のままにしておけば inserts/マージ の速度は従来どおり維持されますが、有効にすると スパース化の対象となり得る各カラムごとに O(rows) の追加パスが発生します。

(Replicated, Shared) MergeTree ではない、従来型以外の MergeTree を使用するテーブルで、プロジェクションの作成を許可するかどうかを指定します。 ignore オプションは互換性のためだけのものであり、誤った結果を招く可能性があります。それ以外の値では、許可する場合に プロジェクションのマージ時にどう処理するかを指定します。動作は drop または rebuild のいずれかです。したがって、従来型の MergeTree ではこの設定は無視されます。これは OPTIMIZE DEDUPLICATE も制御しますが、効果は MergeTree family のすべてのメンバーに及びます。lightweight_mutation_projection_mode オプションと同様に、これも part level です。

設定可能な値:

• ignore
• throw
• drop
• rebuild

すでに挿入済みのブロックを再確認する前に、各 insert の反復処理が、メモリ内の deduplication_hashes cache が より新しいバージョンに更新されるのを待つ時間です。この cache は ClickHouse Keeper 内の deduplication_hashes ディレクトリを反映しているため、insert は Keeper との往復変換なしで重複を検出できます。

テーブル宣言で特定のカラムに圧縮コーデックが定義されていない場合に使用される、デフォルトの圧縮コーデックを指定します。 カラムの圧縮コーデックの選択順序:

1. テーブル宣言でそのカラムに定義された圧縮コーデック
2. default_compression_codec で定義された圧縮コーデック (この設定)
3. compression 設定で定義されたデフォルトの圧縮コーデック デフォルト値: 空文字列 (未定義) 。

ストレージに使用するディスクの名前です。storage policy の代わりに指定できます。

Dynamic データ型のシリアル化バージョンです。互換性のために必要です。

設定可能な値:

• v1
• v2
• v3

この設定をパーティション操作 クエリ (ATTACH/MOVE/REPLACE PARTITION) の宛先テーブルに対して有効にすると、 ソーステーブルと宛先テーブルの索引およびプロジェクションは 同一である必要があります。無効な場合は、宛先テーブルが ソーステーブルの索引およびプロジェクションの上位集合を持つことができます。

この設定の値が 0 より大きい場合、ただ 1 つのレプリカのみが直ちにマージを開始し、他のレプリカはローカルでマージを実行する代わりに、その時間内は結果をダウンロードして待機します。選択されたレプリカがその時間内にマージを完了しなかった場合は、標準の動作にフォールバックします。

設定可能な値:

• 任意の正の整数。

完了したミューテーションに関するレコードを保持する件数です。ゼロの場合は、 そのすべてを保持します。

マージ時の読み取りでファイルシステムキャッシュを強制的に経由させます

テーブル初期化の再試行間隔 (秒) 。

廃止された設定で、何の効果もありません。

デフォルトでは、論理削除 DELETE は プロジェクション を持つテーブルでは機能しません。これは、projection 内の行が DELETE 操作の影響を受ける可能性があるためです。そのため、デフォルト値は throw です。ただし、このオプションで動作を変更できます。値を drop または rebuild のいずれかにすると、プロジェクション に対しても deletes が機能するようになります。drop は projection を削除するため、 現在のクエリでは projection が削除されることで高速になる可能性がありますが、 以降のクエリでは projection がアタッチされなくなるため低速になる可能性があります。rebuild は projection を再構築するため、現在のクエリのパフォーマンスに影響する可能性がありますが、 以降のクエリは高速化される可能性があります。さらに、これらのオプションは パーツ level でのみ機能するため、変更対象にならない パーツ 内の プロジェクション は、 drop や rebuild のようなアクションをトリガーすることなく、そのまま維持されます。

設定可能な値:

• throw
• drop
• rebuild

exclude_deleted_rows_for_part_size_in_merge とあわせて有効にすると、 既存のデータパーツの削除済み行数が、テーブルの起動時に 計算されます。なお、これにより起動時のテーブル読み込みが遅くなる可能性があります。

設定可能な値:

• true
• false

関連項目

• exclude_deleted_rows_for_part_size_in_merge 設定

マージやミューテーションなどのバックグラウンド処理で、テーブルロックを取得できない場合に失敗と見なすまでの秒数。

ミューテーションと他のワークロードの間で、リソースの利用と共有をどのように制御するかを調整するために使用されます。指定した値は、このテーブルのバックグラウンドミューテーションに対する workload 設定の値として使用されます。指定しない場合 (空文字列) は、代わりにサーバー設定 mutation_workload が使用されます。

関連項目

• ワークロードスケジューリング

非レプリケートの MergeTree テーブルで、重複確認のためにハッシュ値を保持する直近の挿入ブロック数です。

設定可能な値:

• 任意の正の整数。
• 0 (重複排除を無効化) 。

レプリケートテーブルと同様の重複排除の仕組みが使用されます ( replicated_deduplication_window 設定を参照) 。重複排除用の ハッシュ値は、挿入されたブロック全体を対象に計算されます。ハッシュ値は ClickHouse Keeper ではなく、ディスク上のローカルファイルに書き込まれます。

最新の ブロック 番号を SharedJoin または SharedSet に通知します。ClickHouse Cloud でのみ使用できます。

Nullable(T) カラムで使用するシリアライゼーション方式を制御します。

設定可能な値:

• basic — Nullable(T) に標準のシリアライゼーションを使用します。

• allow_sparse — Nullable(T) でスパースエンコーディングの使用を許可します。

JSON データ型のシリアライゼーションバージョンです。互換性のために必要です。

設定可能な値:

• v1
• v2
• v3

共有データのシリアライゼーションバージョンを変更できるのは、バージョン v3 のみです。

突発的なサーバー再起動時のデータ損失を防ぐために、 非アクティブなパーツを保持しておく時間 (秒) 。

設定可能な値:

• 任意の正の整数。

複数のパーツを新しいパーツにマージすると、ClickHouse は元の パーツを非アクティブとしてマークし、old_parts_lifetime 秒が経過した後にのみ削除します。 非アクティブなパーツは、現在のクエリで使用されていない場合、つまり そのパーツの refcount が 1 の場合に削除されます。

新しいパーツに対しては fsync が呼び出されないため、しばらくの間、新しいパーツは server の RAM (OS キャッシュ) 上にしか存在しません。server が突発的に再起動すると、 新しいパーツが失われたり破損したりする可能性があります。データ保護のため、 非アクティブなパーツはすぐには削除されません。

起動時に ClickHouse はパーツの整合性を確認します。マージ済みの パーツが破損している場合、ClickHouse は非アクティブなパーツをアクティブな一覧に戻し、 その後それらを再度マージします。次に、破損したパーツはリネームされ (broken_ プレフィックスが追加され) 、detached フォルダーに移動されます。マージ済みのパーツが 破損していない場合は、元の非アクティブなパーツがリネームされ (ignored_ プレフィックスが追加され) 、detached フォルダーに移動されます。

デフォルトの dirty_expire_centisecs 値 (Linux カーネルの設定) は 30 秒 (書き込まれたデータが RAM にのみ保持される最大時間) ですが、 ディスクシステムに高い負荷がかかっている場合、実際の書き込みはそれよりかなり遅くなることがあります。実験的に、 old_parts_lifetime には 480 秒という値が選ばれており、この間に 新しいパーツが確実にディスクへ書き込まれることが保証されます。

新たに挿入されるテーブルパートの圧縮効率を高めるために、挿入時に行順序を最適化するかどうかを制御します。

通常の MergeTree-engine テーブルに対してのみ効果があります。特殊な MergeTree engine テーブル (例: CollapsingMergeTree) には効果がありません。

MergeTree テーブルは、 (必要に応じて) compression codecs を使用して圧縮されます。 LZ4 や ZSTD のような汎用的な圧縮コーデックは、データにパターンがある場合に最大の圧縮率を発揮します。 同じ値が長く連続するデータは、一般に非常によく圧縮されます。

この設定を有効にすると、ClickHouse は、新たに 挿入されるパート内のデータを、新しいテーブルパートの各カラムにおいて同じ値の連続数が最小になるような行順序で格納しようとします。 言い換えると、同じ値の連続数が少ないほど、個々の連続区間は 長くなり、圧縮効率が高くなります。

最適な行順序を見つけることは、計算量の観点から現実的ではありません (NP 困難) 。 そのため、ClickHouse は、元の行順序よりも圧縮率を改善できる行順序を すばやく見つけるためにヒューリスティックを使用します。

有効にすると、新しいデータの行順序を分析して 最適化するために、挿入操作で追加の CPU コストが発生します。INSERT は、データの特性に応じて 30～50% 長くかかることが見込まれます。 LZ4 または ZSTD の圧縮率は、平均で 20～40% 改善します。

この設定は、主キーがないテーブル、または低カーディナリティの 主キーを持つテーブル、すなわち異なる主キー値が少数しかないテーブルで最も効果を発揮します。 高カーディナリティの主キー、たとえば型 DateTime64 の timestamp カラムを含む主キーでは、この設定の恩恵は 期待できません。

スキップ索引 サブストリームを個別の skp_idx_<name>.idx2 / .mrk2 ファイルとして書き込む代わりに、パーツごとに単一の skp_idx.packed アーカイブへまとめるしきい値です (シリアライズ後のディスク上バイト数、つまりサブストリームの圧縮と hashing chain の後のサイズ) 。この値より大きいサブストリームは、従来のファイル単位レイアウトのままです。判定は 書き込み時にサブストリームごとに独立して行われるため、1 つのパーツ内で小さい索引 (例: minmax) はパックされ、大きいもの (例: 重い bloom_filter) はファイル単位のままになる場合があります。パッキングを完全に無効化するには 0 を設定します 。既定値は 1 MiB で、通常は小さい skip 索引をパーツごとに 1 つのアーカイブへまとめ、オブジェクト ストレージ上のオブジェクト数 (および読み取りリクエスト) を削減する一方、実際に大きいサブストリームはファイル単位のレイアウトのままにします。

各 スキップ索引 サブストリームは実際には data file と marks file で構成されており、spill の判定が行われるまで両方が しきい値までメモリ内に buffer されます。そのため、書き込み中の Peak memory は 2 * packed_skip_index_max_bytes * (number of substreams that stay below the threshold) に比例します。

全文索引はこの設定ではサポートされず、パックされることはありません。

パッキングにより、table に多数の skip 索引が定義されている場合の inode 負荷を軽減できます (たとえば add_minmax_index_for_numeric_columns を使用する場合) 。

ディスク上フォーマットは自己記述的です。reader は skp_idx.packed を検出し、その内部のパック済み サブストリームを透過的に提供します。この設定の変更は新しく書き込まれるパーツにのみ影響し、 既存のパーツは書き込み時のレイアウトを保持します。

パートごとの min-max 索引が対象とするカラムを選択します。各値を選ぶと、1つ前の値で有効になるカラム群に加えて、さらに別のカラム群が有効になります。

設定可能な値:

• partition_key_only — パーティションキーのカラムのみを追跡します。
• with_block_number_offset — パーティションキーのカラムに加えて、永続化された仮想カラム _block_number と _block_offset も追跡します。これにより、これらのカラムによるパートレベルの pruning が有効になります。

論理 UPDATE クエリで生成されるパッチパートのディスク上のシリアライゼーションバージョン。

設定可能な値:

• v1 - レガシーフォーマット: パッチパートには _part, _part_offset システムカラムが含まれ、 (_part, _part_offset) でソートされます。最悪の場合、適用時のメモリ使用量はパッチパート全体のサイズに抑えられます。
• v2 - パッチパートにはメインテーブルのソートキーカラムが含まれ、 (sorting_key_columns..., _block_number, _block_offset) でソートされます。適用時のメモリ使用量は、同一ソートキーが連続する範囲のうち最大のものに抑えられます。

ディスク上の旧形式のパッチは、この設定にかかわらず引き続き読み取れます。

true の場合、string_serialization_version のようなシリアライゼーションバージョンは、Array/Map/Nullable/JSON/etc. のようなネスト型の内部にも伝播されます。無効にすると、シリアライゼーションバージョンはこの型のトップレベルのカラムと Tuple el にのみ適用されます

カラム内の デフォルト 値の数を 全 値の数で割った比率の最小値です。 この値を設定すると、そのカラムはスパースな シリアライゼーションで保存されます。

カラムがスパースである場合 (ほとんどの値がゼロである場合) 、ClickHouse はそれを スパースなフォーマットでエンコードし、計算を自動的に最適化できます。つまり、クエリ時に データを完全に伸長する必要がありません。このスパース シリアライゼーションを有効にするには、ratio_of_defaults_for_sparse_serialization 設定を 1.0 未満にしてください。値が 1.0 以上の場合、 カラムは常に通常の完全なシリアライゼーションで書き込まれます。

設定可能な値:

• スパースなシリアライゼーションを有効にするには、0 から 1 の間の Float
• スパースなシリアライゼーションを使用しない場合は、1.0 (またはそれ以上)

例

次のテーブルでは、s カラムは 95% の 行で空文字列です。my_regular_table ではスパースなシリアライゼーションを使用せず、 my_sparse_table では ratio_of_defaults_for_sparse_serialization を 0.95 に設定しています:

CREATE TABLE my_regular_table
(
`id` UInt64,
`s` String
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO my_regular_table
SELECT
number AS id,
number % 20 = 0 ? toString(number): '' AS s
FROM
numbers(10000000);

CREATE TABLE my_sparse_table
(
`id` UInt64,
`s` String
)
ENGINE = MergeTree
ORDER BY id
SETTINGS ratio_of_defaults_for_sparse_serialization = 0.95;

INSERT INTO my_sparse_table
SELECT
number,
number % 20 = 0 ? toString(number): ''
FROM
numbers(10000000);

my_sparse_table の s カラムが、ディスク上で使用するストレージ容量が少ないことに注目してください。

SELECT table, name, data_compressed_bytes, data_uncompressed_bytes FROM system.columns
WHERE table LIKE 'my_%_table';

┌─table────────────┬─name─┬─data_compressed_bytes─┬─data_uncompressed_bytes─┐
│ my_regular_table │ id   │              37790741 │                75488328 │
│ my_regular_table │ s    │               2451377 │                12683106 │
│ my_sparse_table  │ id   │              37790741 │                75488328 │
│ my_sparse_table  │ s    │               2283454 │                 9855751 │
└──────────────────┴──────┴───────────────────────┴─────────────────────────┘

カラムでスパースエンコーディングが使用されているかどうかは、 system.parts_columns テーブルの serialization_kind カラムを見ることで確認できます:

SELECT column, serialization_kind FROM system.parts_columns
WHERE table LIKE 'my_sparse_table';

s のどの部分がスパースシリアライゼーションで保存されたかを確認できます:

┌─column─┬─serialization_kind─┐
│ id     │ Default            │
│ s      │ Default            │
│ id     │ Default            │
│ s      │ Default            │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
│ id     │ Default            │
│ s      │ Sparse             │
└────────┴────────────────────┘

ClickHouse Cloudでのみ利用できます。どの範囲も削除または置換されなかった場合に、blocking parts の削減を再度試みるまでの最小待機時間です。設定値を小さくすると、background_schedule_pool 内のタスクが高頻度でトリガーされるため、大規模なクラスターでは ZooKeeper への大量のリクエストが発生します

カラムのファイル名が長すぎる場合 ('max_file_name_length' バイトを超える場合) は、SipHash128に置き換えます

true の場合、このノード上のレプリケートテーブルのレプリカは リーダーになることを試みます。

設定可能な値:

• true
• false

ClickHouse は、policy に含まれない未定義のディスク上にあるデータパーツの見落としを防ぐため、 ATTACH または CREATE table のたびに、孤立したパーツがないかすべてのディスクを走査します。 孤立したパーツは、たとえばディスクが storage policy から除外された場合のような、 安全でない可能性があるストレージの再構成によって発生します。 この設定では、ディスクの特性に基づいて検索対象とするディスクの範囲を制限します。

設定可能な値:

• any - 範囲は制限されません。
• local - 範囲はローカルディスクに制限されます。
• none - 対象範囲を空にし、検索しません

serialization.json の書き込み時に使用するシリアライゼーションバージョンです。 この設定は、クラスターのアップグレード時に互換性を保つために必要です。

設定可能な値:

• basic - 基本フォーマット。
• with_types - 追加の types_serialization_versions フィールドを含むフォーマットで、型ごとのシリアライゼーションバージョンを使用できます。 これにより、string_serialization_version のような設定が有効になります。

ローリングアップグレード中は、これを basic に設定し、新しいサーバーが 古いサーバーと互換性のあるデータパーツを生成するようにします。アップグレード完了後は、 型ごとのシリアライゼーションバージョンを有効にするため、WITH_TYPES に切り替えます。

有効時 (デフォルト) には、共通のプレフィックスを持つドット区切りの名前の Array カラム (例: n.a および n.b) は Nested 構造の一部として扱われます。これらはディスク上の単一の offsets ファイル (例: n.size0) を共有し、 INSERT 時には配列サイズが同一であることが検証されます。 無効時には、各 Array カラムがそれぞれ独立した offsets ファイルを持ち、ドット区切りの名前に特別な セマンティクスはなくなります。また、同じプレフィックスを共有するドット区切りの Array カラムと スカラー カラムを共存させることもできます (例: n UInt32 と n.a Array(String)) 。この設定はテーブル作成後は変更できません。

古いパーツが多数ある場合、クリーンアップスレッドは1回の反復で最大 simultaneous_parts_removal_limit 個のパーツを削除しようとします。 simultaneous_parts_removal_limit を 0 に設定すると、上限なしを意味します。

ストレージディスクポリシー名

トップレベルの String カラムのシリアライゼーション フォーマットを制御します。

この設定は、serialization_info_version が "with_types" に設定されている場合にのみ有効です。 with_size_stream に設定すると、トップレベルの String カラムは、サイズをインラインで格納するのではなく、 文字列長を格納する独立した .size サブカラムを使ってシリアライズされます。これにより実際の .size サブカラムを利用できるようになり、圧縮効率が向上する場合があります。

ネストされた String 型 (たとえば Nullable、LowCardinality、Array、Map の内部にあるもの) は、Tuple 内に現れる場合を除き、影響を受けません。

設定可能な値:

• single_stream — サイズをインラインで格納する標準のシリアライゼーション フォーマットを使用します。
• with_size_stream — トップレベルの String カラムに対して、独立したサイズストリームを使用します。

tmp_ディレクトリを保持する期間 (秒) です。この値は下げないでください。 この設定値が小さいと、マージやミューテーションが正常に動作しない可能性があるためです。

再圧縮を伴うマージを開始するまでのタイムアウト時間 (秒) 。この間、 ClickHouse は、この再圧縮を伴うマージが割り当てられたレプリカから、 再圧縮済みのパートを取得しようとします。

再圧縮は多くの場合低速なため、このタイムアウトが経過するまでは 再圧縮を伴うマージを開始せず、この再圧縮を伴うマージが割り当てられた レプリカから再圧縮済みのパートを取得しようとします。

設定可能な値:

• 任意の正の整数。

TTL 設定に従ってそのパーツ内のすべての行の有効期限が切れた場合に、 MergeTree テーブルでデータパーツ全体を完全に削除するかどうかを制御します。

ttl_only_drop_parts が無効な場合 (デフォルト) 、 TTL 設定に基づいて有効期限が切れた行のみが削除されます。

ttl_only_drop_parts が有効な場合、 TTL 設定に従ってそのパーツ内のすべての行の有効期限が切れていれば、パーツ全体が削除されます。

シャットダウン前に、テーブルは一意なパーツ (現在のレプリカにのみ存在するもの) が他のレプリカにフェッチされるまで、必要な時間だけ待機します (0 は 無効を意味します) 。

ZooKeeper セッションの有効期限切れを確認する間隔 (秒単位) 。

設定可能な値:

• 任意の正の整数。