システムテーブルの概要

システムテーブルは、次の情報を提供します。

サーバーの状態、プロセス、および環境
サーバーの内部プロセス
ClickHouseバイナリのビルド時に使用されたオプション

システムテーブルは、次の特徴を持ちます。

system database に配置されている
データの読み取り専用である
DROP や ALTER はできないが、デタッチは可能である

ほとんどのシステムテーブルは、データを RAM に保存します。ClickHouse server は起動時にこのようなシステムテーブルを作成します。

ほかのシステムテーブルとは異なり、システムログテーブル metric_log、query_log、query_thread_log、trace_log、part_log、crash_log、text_log、および backup_log は MergeTree テーブルエンジンで管理され、デフォルトではデータを filesystem に保存します。filesystem からテーブルを削除すると、ClickHouse server は次回データが書き込まれる際に空のテーブルを再作成します。新しいリリースでシステムテーブルのスキーマが変更された場合、ClickHouse は現在のテーブルの名前を変更し、新しいテーブルを作成します。

システムログテーブルは、/etc/clickhouse-server/config.d/ 配下にテーブルと同名の設定ファイルを作成するか、/etc/clickhouse-server/config.xml で対応する要素を設定することでカスタマイズできます。カスタマイズ可能な要素は次のとおりです。

database: システムログテーブルが属する database。このオプションは現在非推奨です。すべてのシステムログテーブルは database system 配下にあります。
table: データを挿入するテーブル
partition_by: PARTITION BY 式を指定します。
ttl: テーブルの有効期限 (TTL) 式を指定します。
flush_interval_milliseconds: データをディスクに flush する間隔
engine: パラメーター付きの完全な engine 式 (ENGINE = で始まるもの) を指定します。このオプションは partition_by および ttl と競合します。同時に設定すると、サーバーは例外を発生させて終了します。

例:

<clickhouse>
    <query_log>
        <database>system</database>
        <table>query_log</table>
        <partition_by>toYYYYMM(event_date)</partition_by>
        <ttl>event_date + INTERVAL 30 DAY DELETE</ttl>
        <!--
        <engine>ENGINE = MergeTree PARTITION BY toYYYYMM(event_date) ORDER BY (event_date, event_time) SETTINGS index_granularity = 1024</engine>
        -->
        <flush_interval_milliseconds>7500</flush_interval_milliseconds>
        <max_size_rows>1048576</max_size_rows>
        <reserved_size_rows>8192</reserved_size_rows>
        <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
        <flush_on_crash>false</flush_on_crash>
    </query_log>
</clickhouse>

デフォルトでは、テーブルの増大に制限はありません。テーブルのサイズを制御するには、古くなったログレコードを削除するための有効期限 (TTL)設定を使用できます。また、MergeTreeエンジンのテーブルのパーティション化機能も利用できます。

システムメトリクスの取得元

ClickHouse server は、システムメトリクスの収集に以下を使用します。

CAP_NET_ADMIN ケーパビリティ。
procfs (Linux のみ) 。

procfs

ClickHouse server に CAP_NET_ADMIN ケーパビリティがない場合は、ProcfsMetricsProvider へのフォールバックを試みます。ProcfsMetricsProvider では、クエリごとのシステムメトリクス (CPU および I/O) を収集できます。

システムで procfs がサポートされ、有効になっている場合、ClickHouse server は以下のメトリクスを収集します。

OSCPUVirtualTimeMicroseconds
OSCPUWaitMicroseconds
OSIOWaitMicroseconds
OSReadChars
OSWriteChars
OSReadBytes
OSWriteBytes

ClickHouse Cloud のシステムテーブル

ClickHouse Cloud では、セルフマネージド環境と同様に、システムテーブルからサービスの状態やパフォーマンスに関する重要な情報を得られます。システムテーブルの中には、特に分散メタデータを管理する Keeper ノードからデータを取得するものなど、クラスター全体のレベルで機能するものがあります。これらのテーブルはクラスター全体の状態を反映するため、個々のノードに対してクエリしても結果は一貫しているはずです。たとえば、parts は、どのノードにクエリしても一貫している必要があります。

SELECT hostname(), count()
FROM system.parts
WHERE `table` = 'pypi'

┌

一方、他のシステムテーブルはノード固有です。たとえば、インメモリで保持されるものや、MergeTree テーブルエンジンを使用してデータを永続化するものが該当します。これは、logs やメトリクスのようなデータで一般的です。この永続化によって、履歴データを分析に利用できるようになります。ただし、これらのノード固有のテーブルは、その性質上、各ノードごとに固有です。

一般に、システムテーブルがノード固有かどうかを判断する際には、次のルールを適用できます。

_log 接尾辞を持つシステムテーブル。
メトリクスを公開するシステムテーブル。たとえば metrics、asynchronous_metrics、events。
実行中のプロセスを公開するシステムテーブル。たとえば processes、merges。

さらに、システムテーブルの新しいバージョンが、アップグレードやスキーマ変更に伴って作成されることがあります。これらのバージョンには、数値の接尾辞を使って名前が付けられます。

たとえば、system.query_log テーブルを考えてみましょう。これには、そのノードで実行された各クエリについて 1 行ずつ記録されます。

SHOW TABLES FROM system LIKE 'query_log%'

┌

複数のバージョンをまたいだクエリ

merge 関数を使うと、これらのテーブルをまたいでクエリできます。たとえば、次のクエリは、各 query_log テーブルについて、対象ノードに対して発行された最新のクエリを特定します。

SELECT
    _table,
    max(event_time) AS most_recent
FROM merge('system', '^query_log')
GROUP BY _table
ORDER BY most_recent DESC

┌

重要なのは、これらのテーブルが依然として 各ノードにローカル であることです。

ノードをまたいだクエリ

クラスター全体を包括的に把握するには、clusterAllReplicas 関数を merge 関数と組み合わせて利用できます。clusterAllReplicas 関数を使うと、"default" クラスター内のすべてのレプリカにまたがってシステムテーブルをクエリし、ノード固有のデータを 1 つの結果に集約できます。これを merge 関数と組み合わせることで、クラスター内の特定のテーブルに関するすべてのシステムデータを対象にできます。

この方法は、クラスター全体にわたる処理の監視やデバッグで特に有用で、ClickHouse Cloud デプロイメントの健全性やパフォーマンスを効果的に分析するのに役立ちます。

たとえば、分析で重要になることが多い query_log テーブルをクエリした場合の違いを見てみましょう。

SELECT
    hostname() AS host,
    count()
FROM system.query_log
WHERE (event_time >= '2025-04-01 00:00:00') AND (event_time <= '2025-04-12 00:00:00')
GROUP BY host

┌

ノードやバージョンをまたいだクエリ

システムテーブルにはバージョン差異があるため、これでもなおクラスター内の全データを完全には表せません。これを上記の内容とmerge関数と組み合わせることで、対象の日付範囲に対して正確な結果が得られます。

SELECT
    hostname() AS host,
    count()
FROM clusterAllReplicas('default', merge('system', '^query_log'))
WHERE (event_time >= '2025-04-01 00:00:00') AND (event_time <= '2025-04-12 00:00:00')
GROUP BY host SETTINGS skip_unavailable_shards = 1

┌

システムテーブルの概要