signoz-writing-clickhouse-queries
Write raw ClickHouse SQL for a SigNoz dashboard panel: timeseries, value, or table widgets that the builder UI cannot express (custom joins, window functions, regex extraction over log bodies, aggregations beyond builder syntax). Trigger when the user explicitly asks for a "ClickHouse query", a "raw SQL panel", a "custom SQL widget", or describes a SigNoz dashboard panel whose query needs SQL the builder cannot produce. Anchored to dashboard-panel SQL specifically. For ad-hoc data exploration that does not need to land in a panel, use signoz-generating-queries instead.
- Installs
- 362
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/signoz/agent-skills --skill signoz-writing-clickhouse-queries- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads signoz-writing-clickhouse-queries automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Writing ClickHouse Queries for SigNoz Dashboards
When to Use
Use this skill when the user asks for SigNoz queries involving:
- Logs: severity, body text, log volume, structured fields, containers, services, or environments.
- Traces: spans, latency, duration, p95 or p99, HTTP operations, DB operations, or error spans.
- Dashboard panels: timeseries charts, value widgets, and table breakdowns.
If the user asks for a dashboard panel but does not mention ClickHouse, still use this skill.
Signal Detection
Identify whether the request is about logs or traces.
- Logs: log lines, severity, body text, log volume, container logs, or structured log fields.
- Traces: spans, latency, duration, p99, trace analysis, HTTP operations, DB operations, or error spans.
If the request is ambiguous, ask the user to clarify.
Reference Routing
- Logs: read
references/clickhouse-logs-reference.mdbefore writing any query. - Traces: read
references/clickhouse-traces-reference.mdbefore writing any query.
Each reference covers table schemas, optimization patterns, attribute access syntax, dashboard templates, query examples, and a validation checklist.
Quick Reference
- Timeseries panel: return rows of
(ts, value)for a chart over time. - Value panel: return a single
valuefor a stat or counter widget. - Table panel: return labelled columns for a grouped breakdown.
Key Variables by Signal
Logs
- Timestamp type:
UInt64in nanoseconds. - Time filter:
$start_timestamp_nanoand$end_timestamp_nano. - Bucket filter:
$start_timestampand$end_timestamp. - Display conversion:
fromUnixTimestamp64Nano(timestamp). - Main table:
signoz_logs.distributed_logs_v2. - Resource table:
signoz_logs.distributed_logs_v2_resource.
Traces
- Timestamp type:
DateTime64(9). - Time filter:
$start_datetimeand$end_datetime. - Bucket filter:
$start_timestampand$end_timestamp. - Display conversion: use the timestamp directly.
- Main table:
signoz_traces.distributed_signoz_index_v3. - Resource table:
signoz_traces.distributed_traces_v3_resource.
Top Anti-Patterns
- Missing
ts_bucket_start BETWEEN $start_timestamp - 1800 AND $end_timestamp. - Plain
IN/JOINwhose subquery reads a distributed table: withdistributed_product_mode='deny'it fails. Prefer the time-bounded fingerprintGLOBAL INpattern or a local subquery table. UseGLOBAL JOINonly for a demonstrably small, bounded RHS; it broadcasts that dataset to every shard. - Adding a resource CTE when there is no resource attribute filter.
- Omitting a non-aggregated projection from
GROUP BY, including computed projections such asJSONExtractString(body, ...). - Logs query with
$start_datetimeor$end_datetime. - Traces query with
$start_timestamp_nanoor$end_timestamp_nano. - Logs query against
signoz_logs.logs, barelogs, ordistributed_logs; always usesignoz_logs.distributed_logs_v2. - Traces query with
resources_string['service.name']instead ofresource_string_service$$name.
Query Attribution
Every generated query MUST end with a SETTINGS clause for monitoring:
SELECT ...
FROM ...
WHERE ...
SETTINGS log_comment = 'signoz-writing-clickhouse-queries skill | YYYY-MM-DD'
Replace YYYY-MM-DD with today's date (e.g., 2026-04-03). If the query
already has a SETTINGS clause, append log_comment to it with a comma.
Workflow
- Detect the signal: logs or traces.
- Read the matching reference file before writing the query.
- Pick the panel type: timeseries, value, or table.
- Build the query using the required patterns from the reference.
- Append the
SETTINGS log_commentattribution clause. - Validate the result with the checklist in the reference.
FAQ
What does the signoz-writing-clickhouse-queries skill do?
Write raw ClickHouse SQL for a SigNoz dashboard panel: timeseries, value, or table widgets that the builder UI cannot express (custom joins, window functions, regex extraction over log bodies, aggregations beyond builder syntax). Trigger when the user explicitly asks for a "ClickHouse query", a "raw SQL panel", a "custom SQL widget", or describes a SigNoz dashboard panel whose query needs SQL the builder cannot produce. Anchored to dashboard-panel SQL specifically. For ad-hoc data exploration that does not need to land in a panel, use signoz-generating-queries instead.
How do I install signoz-writing-clickhouse-queries?
Run npx skills add https://github.com/signoz/agent-skills --skill signoz-writing-clickhouse-queries in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/signoz-writing-clickhouse-queries/ (personal) or .claude/skills/signoz-writing-clickhouse-queries/ (project).
Which AI agents can use signoz-writing-clickhouse-queries?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is signoz-writing-clickhouse-queries safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains signoz-writing-clickhouse-queries?
It is published by signoz in signoz/agent-skills, and it is an official skill from the maker of the technology it covers. It has 362 recorded installs.
More from signoz/agent-skills
signoz-searching-docs
signoz/agent-skills
Look up information in SigNoz documentation. Make sure to use this skill whenever the user asks "how do I", "where in the docs", "what does the docs say about", "find docs for", or otherwise needs reference material on SigNoz instrumentation, OpenTelemetry setup, self-hosted deployment, API endpoints, auth headers, or troubleshooting steps, even if they don't say the word "docs" explicitly. Docs lookup only; for actions inside SigNoz, the agent will pick the matching signoz- action skill.
signoz-creating-dashboards
signoz/agent-skills
Create a new SigNoz dashboard from a natural-language intent: import a curated template (PostgreSQL, Redis, JVM, k8s, hostmetrics, APM, LLM, etc.) when one fits, or build a custom dashboard from scratch with metric / trace / log panels. Make sure to use this skill whenever the user says "create a dashboard for…", "set up monitoring for…", "build me a dashboard…", "I need observability for…", "import a dashboard template", or asks to track / visualize a service, database, cluster, or AI/LLM platform, even if they don't explicitly say "dashboard". Also use it when someone wants to "monitor", "watch", or "see metrics for" a technology and the natural answer is a dashboard.
signoz-generating-queries
signoz/agent-skills
Generate, write, or run an ad-hoc query against SigNoz observability data (metrics, logs, or traces) without wrapping it in a dashboard panel or alert. Make sure to use this skill whenever the user asks "show me error rates", "query logs for timeout errors", "what's the p99 latency for the cart service", "how many requests hit the payment endpoint", "find slow traces", "errors in the last hour", or otherwise asks an exploratory question that needs live observability data, even if they don't say "query" or "search" explicitly.
signoz-explaining-dashboards
signoz/agent-skills
Explain what an existing SigNoz dashboard shows in plain operational language: the panels, queries, variables, and what to watch for on each. Make sure to use this skill whenever the user asks "explain this dashboard", "what does my [X] dashboard show", "walk me through the panels", "what should I watch for on this dashboard", or "help me understand this dashboard", or otherwise asks for an interpretation of a dashboard's contents, even if they don't say "explain" explicitly. Also use it when someone is onboarding to a service and wants to understand what its existing observability looks like.
signoz-modifying-dashboards
signoz/agent-skills
Modify an existing SigNoz dashboard: add or remove panels, edit a panel's query, threshold, or unit, rename the dashboard, change a panel type (graph ↔ table ↔ value), rearrange the layout, add or edit variables, or update tags. Make sure to use this skill whenever the user says "add a panel to my dashboard", "change the query on this panel", "remove the latency widget", "rename my dashboard", "update the filters", "rearrange the layout", "add a variable", "change panel type from graph to table", or otherwise asks to change something on a dashboard that already exists, even if they don't say "modify" or "edit" explicitly.
signoz-creating-alerts
signoz/agent-skills
Create a new SigNoz alert rule from a natural-language intent: threshold, anomaly, log-volume, error-rate, latency, or absent-data alerts across metrics, logs, traces, and exceptions. Make sure to use this skill whenever the user says "alert me when…", "notify me if…", "set up monitoring for…", "page me on…", "create an alert for…", or asks for a new alert/notification rule, even if they don't say the word "alert" explicitly. Also use it when someone asks to be notified about error rates, latency spikes, log volume, CPU/memory pressure, or anomalous behavior on a service or host.
Popular data & databases skills
supabase-postgres-best-practices
supabase/agent-skills
Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.
prisma-client-api
prisma/skills
Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
prisma-database-setup
prisma/skills
Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.
prisma-cli
prisma/skills
Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.
prisma-postgres
prisma/skills
Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.
prisma-driver-adapter-implementation
prisma/skills
Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.