ClickHouse と Grafana の連携手順とベストプラクティス【2026年版】

対応バージョンと前提条件

本セクションでは、2026 年 6 月時点での ClickHouse と Grafana の公式サポートバージョンを確認し、インストール前に満たすべき最低要件をまとめます。バージョンが合致していないとプラグインがロードできなかったり、クエリ実行時に予期せぬエラーが発生する可能性がありますので、必ず事前チェックしてください。

必要な ClickHouse バージョン

ClickHouse の公式ドキュメント（clickhouse.com/docs/en/integrations/grafana）によれば、v24.x 系（2026 年リリース）以降 が Grafana 用データソースプラグインの最小対応バージョンです。

• 確認方法：clickhouse-client --query "SELECT version();" を実行し、出力が 24. で始まれば OK。
• 推奨リリース：執筆時点では最新安定版は v24.5.1（2026‑05‑15 リリース）です。古いバージョンを使用している場合は公式パッケージまたは Docker イメージ (clickhouse/clickhouse-server:24) に更新してください。

必要な Grafana バージョン

Grafana の Marketplace ページ（grafana.com/grafana/plugins/grafana-clickhouse-datasource）では、プラグインが Grafana v11.x 系以上 に対応していることが明記されています。

• 確認方法：Grafana UI の左下「About Grafana」からバージョン番号を取得し、v11. で始まっていれば問題ありません。
• 推奨リリース：2026‑04‑28 に公開された v11.2.4 が現在の最新安定版です。古いバージョンの場合は公式イメージ grafana/grafana:11 へアップグレードしてください。

チェックリスト
- clickhouse-client --query "SELECT version();" → 24.x 系か確認
- Grafana UI の「About」 → v11.x 系か確認

読み取り専用ユーザーの作成と接続情報準備

データ可視化だけを目的にする場合、最小権限の 読み取り専用ユーザー を用意しておくことがセキュリティ上必須です。以下ではロールベース権限付与の手順と、Grafana が利用できる DSN（Data Source Name）の組み立て方を具体例付きで解説します。

ロール・ユーザー作成例

ClickHouse はロールベース認可を標準で提供しています。下記 SQL を実行すれば readonly_user という名前の SELECT のみ許可されたアカウントが完成します（日本語ドキュメントは clickhouse.com/docs/ja/sql-reference/statements/create/user に掲載）。

ポイント：ロールは再利用が容易です。新たに読み取り専用アカウントが必要になったら、CREATE USER …; GRANT readonly_role TO <new_user>; だけで完了します。

接続文字列（DSN）の組み立て方

Grafana のデータソース設定画面では HTTP/HTTPS エンドポイント と認証情報を含む DSN が必要です。以下は一般的な書式例です（URL エンコードが必要な特殊文字は %xx へ変換してください）。

• http／https：TLS が必須の場合は https を選択し、証明書設定を別途行います。
• ポート：デフォルト HTTP は 8123、HTTPS は 8443（サーバ側で有効化が必要）。
• クエリパラメータ：database=your_db で接続時のデフォルト DB を固定できます。

ヒント：Grafana の「Save & Test」ボタンでテストに失敗した場合は、ユーザー名・パスワードの URL エンコード漏れやファイアウォール設定を再確認してください。

公式 ClickHouse プラグインの導入とデータソース設定

この章では Grafana Marketplace から公式プラグインを取得し、実際にデータソースとして登録する手順をステップバイステップで示します。プラグインは自動更新が有効になるため、長期運用でも保守コストを抑えられます。

Marketplace からのインストール手順

Grafana の管理者権限でログインした後、以下の流れでインストールできます。

1. 左メニュー Configuration → Plugins を選択。
2. 上部検索バーに ClickHouse と入力し、一覧に表示された “ClickHouse Datasource” をクリック。
3. 「Install」ボタンを押すとプラグインがダウンロード・配置され、ステータスが Installed に変わります。

注意：インストール直後は Grafana の再起動は不要です。ただし、プラグインバージョンを固定したい場合は grafana.ini の [plugins] セクションで
ini
allow_loading_unsigned_plugins = false
と設定してください。

データソース定義と接続テスト

インストール完了後、実際に ClickHouse へ接続できるか確認します。

1. Configuration → Data Sources → Add data source を開き、一覧から ClickHouse を選択。
2. 「URL」欄に先ほど作成した DSN（例: http://readonly_user:StrongPass123@clickhouse.example.com:8123）を貼り付ける。
3. 必要に応じて以下のオプションを設定
4. Default Database：default もしくは任意の DB 名
5. Timeout：30s（長時間クエリの場合は適宜延長）
6. ページ下部の “Save & Test” をクリックし、緑色の「Data source is working」メッセージが表示されれば接続成功です。

トラブルシューティング：Connection refused が出た場合は ClickHouse のファイアウォールや Docker コンテナのポート公開設定（例: -p 8123:8123）を確認してください。

ダッシュボード作成ステップ：クエリビルダー・変数活用

実務で使えるダッシュボードは Query Builder と テンプレート変数 を組み合わせると、柔軟かつ保守しやすい構成になります。この章では基本パネル作成から時間フィルタ・変数設定までの具体的手順を示します。

基本パネル作成フロー

Grafana の「Add panel」→「Edit」画面で、以下の流れでシンプルな時系列グラフが作れます。

1. Visualization を Time series に設定。
2. 「Query」タブで ClickHouse データソースを選択し、SQL エディタに次のクエリを書き込む。

• $__timeFilter は Grafana が自動的に生成する時間範囲プレースホルダーです。

• toStartOfMinute で 1 分単位に丸め、avg(CPUUsage) の平均値を取得します。

• 「Apply」→「Save」し、パネル名や軸ラベルを適宜編集すれば完了です。

時間範囲とテンプレート変数の設定例

ダッシュボード全体で テーブル切替 や 期間変更 を可能にするには、テンプレート変数を利用します。以下は代表的な 2 種類の変数定義手順です。

1. ダッシュボード上部メニュー Dashboard settings → Variables → New
2. 名前：table_name
3. タイプ：Query
4. データソース：ClickHouse（先ほど作成したもの）
5. クエリ：SHOW TABLES FROM default

6. デフォルト値：system.metrics

7. 同様に期間用変数 time_interval を作成

8. 名前：time_interval
9. タイプ：Custom
10. 値：1m,5m,15m,1h,6h,12h,1d
11. デフォルト：5m

パネルのクエリ内では ${table_name} と ${time_interval} を使用し、例として次のように書き換えられます。

ベストプラクティス：変数は「Refresh: On Dashboard Load」に設定し、テーブルが増減した際に自動で一覧を更新させましょう。

代表的ダッシュボード例と JSON エクスポート

ここでは実務でよく使われる CPU 使用率、クエリレイテンシ、テーブルサイズ の３パネル構成サンプルを示します。作成後は JSON エクスポート機能で他環境へ簡単に移行できます。

CPU 使用率パネル例

クエリレイテンシ & テーブルサイズパネル例

• クエリレイテンシ（p95）

• テーブルサイズ（GB）

JSON エクスポート手順

1. 作成したダッシュボード画面右上の “Share” アイコンをクリック。
2. 「Export」タブで “Download JSON” ボタンを押すと dashboard.json がローカルに保存されます。
3. 別環境へインポートする場合は、Grafana の「Create → Import」画面で同ファイルを選択し、データソースのマッピングだけを行えば即座に再利用可能です。

注意：エクスポートされた JSON にはパスワード等機密情報が含まれません。インポート先では DSN を手動で設定するか、Grafana の Secrets / Environment variables 機能を活用してください。

パフォーマンス最適化とトラブルシューティング

大規模テーブルや多数のパネルを扱う場合は、クエリ実行コストがボトルネックになることがあります。本節では サンプリング、マテリアライズドビュー、キャッシュ設定 のベストプラクティスと、よくある接続障害への対処法をまとめます。

サンプリングとマテリアライズドビュー

• サンプリングは SAMPLE 句でデータの一部だけを集計し、クエリ負荷を削減します。
  sql
SELECT avg(CPUUsage)
FROM system.metrics SAMPLE 0.1 -- 全体の10% を対象
WHERE $__timeFilter(event_time);
• マテリアライズドビューは定期的に集計結果を別テーブルへ保存し、再利用を可能にします。
  sql
CREATE MATERIALIZED VIEW cpu_avg_5min TO default.cpu_metrics_summary AS
SELECT
toStartOfFiveMinute(event_time) AS interval,
avg(CPUUsage) AS cpu_avg
FROM system.metrics
GROUP BY interval;
  ダッシュボードでは cpu_metrics_summary を直接参照するだけで、フルスキャンを回避できます。

キャッシュ設定ベストプラクティス

ClickHouse のクエリキャッシュは同一クエリの再実行時にディスク上の結果を再利用します。以下の統一された YAML ファイル例を /etc/clickhouse-server/config.d/query_cache.yaml に配置し、サーバーを再起動してください。

• ポイント
• max_query_cache_size はサーバーのメモリ/ディスク容量に応じて調整。過度に大きくするとディスク I/O が増加します。
• query_cache_ttl_sec を短めに設定すれば、リアルタイム性を保ちつつキャッシュ効果が得られます。

この設定は 読み取り専用ユーザー でも有効であり、Grafana のパネル再描画速度が顕著に向上します。

ClickHouse Cloud と Grafana のハイブリッド構成

ClickHouse Cloud が提供する組み込みモニタリング UI は手軽ですが、カスタム可視化や外部データソース統合は制限があります。一方 Grafana はプラグインとテンプレート変数で高度なダッシュボードを構築できるため、以下のように併用するとベストです。

実装例：Cloud のメトリクス API エンドポイントを Grafana の Prometheus data source として登録し、ClickHouse データと合わせて「サービス全体ヘルス」ダッシュボードを作成します。

FAQ（接続エラー・タイムアウト・互換性）

診断ヒント：Grafana のログは /var/log/grafana/grafana.log、ClickHouse のエラーログは /var/log/clickhouse-server/clickhouse-server.err.log に出力されます。両方を同時に確認すると原因特定が早まります。

まとめ

• バージョン要件：ClickHouse v24.x 系以上、Grafana v11.x 系以上 を必ず事前に確認してください。
• 最小権限ユーザー：ロールベースで readonly_user を作成し、安全な DSN を Grafana に設定します。
• 公式プラグインは Marketplace からインストールし、接続テストを行うだけで即利用開始可能です。
• ダッシュボード構築は Query Builder とテンプレート変数の組み合わせが鍵となり、時間フィルタやテーブル切替が容易になります。
• 代表的パネル（CPU 使用率・クエリレイテンシ・テーブルサイズ）は JSON エクスポートで再利用でき、チーム間で共有しやすくなります。
• 性能最適化はサンプリング／マテリアライズドビューとキャッシュ設定を組み合わせ、特に大規模データでは必須です。
• ハイブリッド運用として ClickHouse Cloud と Grafana を併用すれば、管理負荷の低減と高度な可視化の両立が実現します。

以上の手順を踏めば、2026 年版公式プラグインと最新 ClickHouse・Grafana の機能を最大限に活かした 本格的なモニタリング基盤 を構築できます。ぜひご自身の環境へ適用し、データドリブンな運用改善に役立ててください。