clickhouse-query

ClickHouse クエリテスト

分析、メトリクス分析、デバッグのために ClickHouse でアドホッククエリを実行するには、このスキルを使用します。

クエリの実行

付属のクエリスクリプトを使用します。

node .claude/skills/clickhouse-query/query.mjs "SELECT count() FROM views"

オプション

フラグ	説明
--explain	クエリの実行計画を表示します
--writable	書き込み操作を許可します（ユーザーの許可が必要です）
--timeout <s>, -t	クエリのタイムアウト時間（秒）を指定します（デフォルト：30）
--file, -f	ファイルからクエリを読み込みます
--json	結果を JSON として出力します
--quiet, -q	出力を最小限にし、結果のみを表示します

例

# Count rows in a table
node .claude/skills/clickhouse-query/query.mjs "SELECT count() FROM views"

# Query with filters
node .claude/skills/clickhouse-query/query.mjs "SELECT * FROM modelEvents WHERE modelId = 123 LIMIT 10"

# Check query execution plan
node .claude/skills/clickhouse-query/query.mjs --explain "SELECT * FROM views WHERE userId = 1"

# Override default 30s timeout for longer queries
node .claude/skills/clickhouse-query/query.mjs --timeout 60 "SELECT ... (complex aggregation)"

# Query from file
node .claude/skills/clickhouse-query/query.mjs -f my-query.sql

# JSON output for processing
node .claude/skills/clickhouse-query/query.mjs --json "SELECT type, count() FROM modelEvents GROUP BY type"

安全機能

1. デフォルトで読み取り専用：--writable フラグが使われない限り、INSERT／ALTER／DROP をブロックします
2. 30 秒のタイムアウト：クエリの実行が長引くのを防ぎます（--timeout で変更できます）
3. 明示的な許可が必要：--writable を使う前に、必ずユーザーに許可を求めてください

--writable を使う場合

--writable フラグは、次の場合にのみ使用してください。

• ユーザーが書き込みアクセスを明示的にリクエストした場合
• テストデータを挿入する必要がある場合
• メンテナンス操作を実行する場合

重要：--writable を指定して実行する前に、必ずユーザーに許可を求めてください。

よく使われるテーブル

テーブル	説明
views	ページ／エンティティの表示イベント
modelEvents	モデルの作成／公開／更新イベント
modelVersionEvents	ダウンロードを含むモデルのバージョンイベント
userActivities	ユーザー登録、ログイン、サブスクリプションのイベント
images	画像のアップロード／削除イベント
reactions	いいね／よくないねイベント
reports	コンテンツの報告イベント
entityMetricEvents	集計されたメトリクスイベント

レプリカクラスターへのクエリ

重要：本番環境では ClickHouse のレプリカクラスターを使用します。システムテーブル（ログ、メトリクスなど）をクエリする場合、すべてのノードからデータを取得するには clusterAllReplicas() を使用する必要があります。

レプリカクラスター上のシステムテーブル

-- WRONG: Only queries the node you're connected to
SELECT * FROM system.query_log WHERE event_time > now() - INTERVAL 1 HOUR

-- CORRECT: Queries all replicas in the cluster
SELECT * FROM clusterAllReplicas(default, system.query_log)
WHERE event_time > now() - INTERVAL 1 HOUR

よく使われるシステムテーブルのクエリ

-- Find recent queries across all nodes
SELECT
    hostname(),
    event_time,
    query_duration_ms,
    formatReadableSize(memory_usage) AS memory,
    query
FROM clusterAllReplicas(default, system.query_log)
WHERE type = 'QueryFinish'
    AND event_time > now() - INTERVAL 5 MINUTE
ORDER BY event_time DESC
LIMIT 20

-- Find expensive queries by memory usage (last 24 hours)
SELECT
    count() as query_count,
    user,
    sum(memory_usage) AS total_memory,
    normalized_query_hash
FROM clusterAllReplicas(default, system.query_log)
WHERE event_time > now() - INTERVAL 1 DAY
    AND query_kind = 'Select'
    AND type = 'QueryFinish'
GROUP BY normalized_query_hash, user
ORDER BY total_memory DESC
LIMIT 10

-- Search query logs by pattern
SELECT event_time, query_id, query, type
FROM clusterAllReplicas(default, merge('system', '^query_log*'))
WHERE query ILIKE '%some_table%'
    AND event_time > now() - INTERVAL 5 MINUTE

-- Debug a specific query across all nodes
SELECT hostname(), message
FROM clusterAllReplicas(default, system.text_log)
WHERE query_id = 'your-query-id-here'
ORDER BY event_time_microseconds ASC

clusterAllReplicas() を使う場合

用途	関数
システムテーブル（query_log、text_log など）	clusterAllReplicas(default, system.table_name)
アプリケーションテーブル（views、modelEvents など）	直接クエリ（すでに分散されています）
複数のシステムテーブルを検索	clusterAllReplicas(default, merge('system', '^pattern*'))

ClickHouse SQL のヒント

-- Use count() not COUNT(*)
SELECT count() FROM views

-- Date filtering with toDate()
SELECT * FROM views WHERE toDate(time) = today()

-- Last 7 days
SELECT * FROM modelEvents WHERE time > now() - INTERVAL 7 DAY

-- Aggregations
SELECT type, count() as cnt FROM modelEvents GROUP BY type ORDER BY cnt DESC