ObserveKit Help
Back to app

Writing a query

The SQL Editor is for ad-hoc queries against the underlying ClickHouse store. Use it when the structured pages (Log Explorer, Metrics, Traces) don't give you the precision you need.

Two modes

A toggle near the top switches between:

  • Builder (default) — a visual query builder. Pick a signal (Logs / Metrics / Spans), add filters / group-by / order-by / limit. Faster than writing SQL for common cases.
  • SQL — raw SQL editor. Write any SELECT statement.

Press Ctrl+Enter at any time to execute. Or click Run top-right.

Time picker

Across the top: presets 15m | 1h | 6h | 24h | 7d, plus explicit From/To datetime inputs. The Builder uses this as a WHERE timestamp BETWEEN ... clause. In SQL mode the picker does not affect your query — nothing is substituted into the SQL, so write the range yourself.

Schema panel (left)

Browser of the three tables you can query:

  • logs — every log line. Columns: timestamp, source_id, namespace, pod_name, container_name, container_id, node_name, stream, level, message, labels, parsed_fields, trace_id, span_id, exception_fingerprint, workload, workload_kind. Each column is tagged with its kind: time, facet, enum, id, text, json, virtual.
  • metrics — time-series points.
  • spans — trace spans.

That is the whole list. There is no cold or archive table (ClickHouse serves archived data through logs transparently), no pre-aggregated rollup tables, and no metadata database — see There is no cold table, and no meta database for why.

> Full column list with types is in the Table & column reference; operators, JSON extraction, wildcards/regex, and limits are in the Query reference.

TEMPLATES

A collapsible section of pre-built example queries you can click to load into the editor.

Builder mode

Three sub-tabs at the top of the form: Logs / Metrics / Spans. Pick the signal you're querying.

Form fields:

  • Filters — + Add filter to compose WHERE clauses with field, operator, value rows.
  • Group By — + Add group by to add columns.
  • Order By — + Add order by to sort.
  • Limit — preset chips: No limit | 100 | 500 | 1,000 | 5,000 | 10,000 | Custom.

Saving the builder state writes to the URL — share the URL to reproduce the exact query for someone else.

SQL mode

Free-form SQL editor with syntax highlighting and autocomplete from the schema panel. Reference any table you see in the panel.

Example queries:

-- Top error message in the last hour
SELECT message, count(*) AS n
FROM logs
WHERE level = 'error' AND timestamp > now() - INTERVAL 1 HOUR
GROUP BY message
ORDER BY n DESC
LIMIT 20
-- p99 latency by service over 24h
SELECT service_name, quantile(0.99)(duration_ns) AS p99
FROM spans
WHERE start_time > now() - INTERVAL 24 HOUR
GROUP BY service_name
ORDER BY p99 DESC

Result panel

After running a query the right pane shows:

  • Result count.
  • Tabular result with sortable column headers.
  • Export options.

If you haven't run anything yet, the empty state reads "Run a query to see results — Press Ctrl+Enter to execute".

Permissions and limits

The SQL Editor is read-only. INSERT, UPDATE, DELETE, DROP are rejected by the server. Heavy queries go to a separate connection pool so they can't block the UI's normal page loads.

Queries time out after 30 seconds. Add filters, narrow the time window, or add LIMIT to keep them fast.

NextOperators & syntax