SQL editor

Query your spans, traces, and scores with read-only ClickHouse SQL.

The SQL editor runs read-only ClickHouse SQL over your project’s data. Use it for questions the Logs filters can’t answer, such as cost per model or error rate per customer.

Run a query

Open the editor

Go to Observability › SQL editor. A new tab offers Start from a template: Cost by day, Top models, Error rate, and Traces overview. Pick one, or write your own.

Write the SQL

The Tables panel on the right lists every table and column. Click a column to insert it, or use Preview rows on a table. The editor also autocompletes tables, columns, and functions, and underlines names it doesn’t recognize before you run.

This query returns cost and latency per model for the last 7 days:

SQL

Copy

SELECT
    model,
    count(*) AS requests,
    round(sum(cost), 2) AS total_cost,
    round(avg(latency), 2) AS avg_latency
FROM logs
WHERE timestamp >= now() - INTERVAL 7 DAY
GROUP BY model
ORDER BY total_cost DESC
LIMIT 20

Run it

Click Run or press ⌘ Enter (Ctrl Enter on Windows and Linux). If the tab has several statements, it runs the one at the cursor. If you select text, it runs the selection.

The results show below the editor, with the row count, duration, and time. Click a column header to sort, or click Inspect row to read one row in full.

Always filter on the table’s time column, such as timestamp for logs. Queries without one scan more data and are more likely to time out.

Save and manage queries

Every tab is a saved query. Your SQL saves as you type or run, and the editor shows Saved when it’s done.

• New query: click the button after the last tab. New queries are named Untitled query.
• Rename: hover the open tab and click the pencil.
• Delete: click × on the tab, then confirm. This deletes the saved query for good.

Chart the results

When the result has a time column and a numeric column, click Chart to plot it. Click Add to dashboard to put the chart on a Metrics view.

This query produces the chart above:

SELECT
    toDate(timestamp) AS day,
    sum(cost) AS total_cost
FROM logs
WHERE timestamp >= now() - INTERVAL 14 DAY
GROUP BY day
ORDER BY day

Export results

Click Export, or press E, and choose Export as CSV or Export as JSONL. The export reruns your query in the background, so it isn’t limited to the rows on screen. When it’s done, download it from the dialog or from Settings › Exports.

Copy rows as TSV, in the same menu, copies the rows shown.

How queries work

You query tables that Respan defines, not the underlying database. Before a query runs, Respan checks it and adapts it:

• Respan’s tables and columns only. Use the tables and columns listed under Tables. Anything else fails with table not found or column not found.
• Your project only. Respan adds your project filter to every table. You don’t write it, and you can’t remove it.
• Read-only. SELECT and WITH only. Joins, subqueries, and UNION work.
• ClickHouse functions. Function names are case-sensitive: countIf, toStartOfHour, quantile(0.95)(latency). Date, string, math, array, map, JSON, and aggregate functions work. Functions that read files, URLs, or other servers are blocked.
• IN takes a list or a subquery. To check whether an array contains a value, use has(array, value).

traces and the rollup tables store partial totals that Respan combines when you query, so they have a few extra rules. See traces and Rollup tables.

Tables

eval_results and annotations join to logs on log_unique_id = unique_id.

logs

One row per span. LLM calls, tool calls, agent steps, and workflow steps are all spans.

traces

traces stores each trace as partial totals, which Respan combines when you query. That makes it fast, but it works differently from logs:

1. Group by trace_unique_id to get one row per trace.
2. Filter totals in HAVING, not WHERE. span_count, llm_call_count, error_count, total_cost, total_prompt_tokens, total_completion_tokens, total_tokens, customer_identifier, and metadata work in SELECT, HAVING, and ORDER BY. In WHERE, filter only on start_time, end_time, environment, or trace_unique_id.
3. Name each column, such as total_cost AS cost. Without an alias, the result header shows the combining function, like sumMerge(total_cost). Pick a name that isn’t already a column name.

This query lists yesterday’s traces that had at least one failed span, most expensive first:

SELECT
    trace_unique_id,
    span_count AS spans,
    error_count AS errors,
    total_cost AS cost,
    start_time AS started_at
FROM traces
WHERE start_time >= now() - INTERVAL 1 DAY
GROUP BY trace_unique_id
HAVING error_count > 0
ORDER BY cost DESC
LIMIT 50

eval_results

One row per evaluator score. Join to logs to break scores down by model, prompt, or customer:

SELECT
    l.model,
    e.evaluator_name,
    count(*) AS scores,
    round(avg(e.primary_score), 3) AS avg_score
FROM eval_results e
JOIN logs l ON e.log_unique_id = l.unique_id
WHERE e.created_at >= now() - INTERVAL 1 DAY
    AND l.timestamp >= now() - INTERVAL 1 DAY
GROUP BY l.model, e.evaluator_name
ORDER BY scores DESC

annotations

One row per piece of human feedback on a span.

Rollup tables

Rollup tables hold pre-aggregated totals per minute or hour, and the Tables panel lists them under Rollups. Use them for charts over weeks or months, where logs would be slow. Like traces, they combine partial totals when you query:

• Group by a time bucket, such as timestamp or toStartOfDay(timestamp).
• Use the measure columns in SELECT, HAVING, and ORDER BY, not WHERE. In WHERE, filter on timestamp and environment, plus metric_key and model in metadata_metrics.

This query returns daily requests and cost for the last 30 days:

SELECT
    toStartOfDay(timestamp) AS day,
    request_count AS requests,
    round(total_cost, 2) AS cost
FROM log_metrics_hourly
WHERE timestamp >= now() - INTERVAL 30 DAY
GROUP BY day
ORDER BY day

log_metrics (per minute) and log_metrics_hourly (per hour):

latency_quantiles_minute and latency_quantiles_hourly: each quantile column is an array of p50, p90, p95, and p99, in that order. Read p95 with latency_quantiles[3].

metadata_metrics: hourly totals for each numeric metadata key your organization tracks.

organization

One row with your organization’s name.

Custom properties

metadata holds the custom properties you send with each span, as a map of string keys to string values.

• Read a key: metadata['feature']. A missing key returns an empty string.
• Check a key exists: mapContains(metadata, 'feature').
• Use a number: toFloat64OrNull(metadata['score']). Values are stored as text.

To see which keys your spans carry:

SELECT
    arrayJoin(mapKeys(metadata)) AS key,
    count(*) AS spans
FROM logs
WHERE timestamp >= now() - INTERVAL 1 DAY
GROUP BY key
ORDER BY spans DESC

On traces, metadata is a combined total, so use it in SELECT or HAVING, not WHERE.

More examples

Error rate by model, last 24 hours:

SELECT
    model,
    count(*) AS requests,
    round(countIf(status = 'failed') / count(*) * 100, 2) AS error_rate_pct
FROM logs
WHERE timestamp >= now() - INTERVAL 1 DAY
GROUP BY model
HAVING count(*) > 10
ORDER BY error_rate_pct DESC

Cost by a custom property, such as feature:

SELECT
    metadata['feature'] AS feature,
    count(*) AS requests,
    round(sum(cost), 2) AS total_cost
FROM logs
WHERE timestamp >= now() - INTERVAL 7 DAY
GROUP BY feature
ORDER BY total_cost DESC

Limits