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 you can reference the time picker via the helper variables $from and $to.

Schema panel (left)

Categorised browser of the tables and columns you can query:

HOT (live data)

  • 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.

> Full column list with types for every table (logs, spans, metrics, …) is in the Table & column reference; operators, JSON extraction, wildcards/regex, and limits are in the Query reference.

  • metrics — time-series points.
  • spans — trace spans.
  • log_summary — pre-aggregated per-pod log counts.
  • error_summary — pre-aggregated error/warn rollups.
  • cold_logs — logs aged out of hot storage (slower to query).
  • unified_logs — virtual view that hides the hot/cold split (queries hit both).

META

  • meta.sources — the SQLite metastore source rows.

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