SQL schema

The tables and columns you can query with Judgment's virtual SQL (vsql).

Judgment’s virtual SQL (vsql) is a fixed set of read-only tables over your project’s data. You query them with sql_query over MCP, with the Judgment Agent, or with client.sql() in the SDK. For how to run queries and worked examples, see Query with SQL.

Rules

LIMIT caps the rows returned, not the rows scanned. Filter on started_at or on IDs to keep queries fast.

The same reference is available as Markdown from MCP discover_schema, Python client.discover_schema(), TypeScript client.discoverSchema(), and GET /v1/sql/schema.

API and SQL names still say behavior; it means label. config.behaviors holds the labels each judge can apply, and telemetry.scores.behavior_id_at_evaluation records which label a judge applied. New judges are categorical; binary and numeric scores come from older judges.

evaluations.runs and evaluations.items hold test runs started from a test config over a dataset. Test suite runs aren’t in these tables.

Patterns

Tables

Judgment SQL (telemetry.v1)

One read-only SELECT against these virtual tables; host supplies org/project scope; SQL cannot override it.

Memory: prefer narrow time ranges or trace/span IDs and only needed fields. Small LIMITs help inspection but do not bound scan, grouping, sort or join memory. Run broad scans sequentially. On QUERY_MEMORY_LIMIT, narrow scope or simplify before retrying.

telemetry.traces

One latest root record per trace_id

telemetry.spans

One latest record per (trace_id, span_id)

telemetry.scores

One retained evaluation result

telemetry.trace_tags

One tag assignment per (trace_id, tag)

telemetry.alerts

One alert generated by an automation rule

evaluations.runs

One current evaluation test run

evaluations.items

One latest scorer result per run, example, judge, and judge version

datasets.datasets

One current dataset

datasets.examples

One dataset membership per example, including its version interval

config.judges

One judge with a production version per judge_id

config.behaviors

One current label definition per behavior_id

Examples

Session timing and usage

WITH session_roots AS (
  SELECT session_id, min(started_at) AS started_at, max(ended_at) AS ended_at,
         count() AS trace_count
  FROM telemetry.traces
  WHERE session_id IS NOT NULL
  GROUP BY session_id
), session_usage AS (
  SELECT session_id, sum(cost_usd) AS cost_usd,
         sum(non_cached_input_tokens + cache_read_input_tokens + cache_creation_input_tokens) AS input_tokens,
         sum(output_tokens) AS output_tokens
  FROM telemetry.spans
  WHERE session_id IS NOT NULL
  GROUP BY session_id
)
SELECT r.session_id, r.trace_count, r.started_at, r.ended_at,
       dateDiff('microsecond', r.started_at, r.ended_at) / 1000.0 AS elapsed_ms,
       coalesce(u.cost_usd, 0) AS cost_usd,
       coalesce(u.input_tokens, 0) AS input_tokens,
       coalesce(u.output_tokens, 0) AS output_tokens
FROM session_roots AS r
LEFT JOIN session_usage AS u USING (session_id)
ORDER BY r.started_at DESC, r.session_id DESC
LIMIT 50

Current example counts by dataset

SELECT d.dataset_id, d.name, countIf(e.example_id IS NOT NULL AND e.version_removed IS NULL) AS current_examples
FROM datasets.datasets AS d
LEFT JOIN datasets.examples AS e USING (dataset_id)
GROUP BY d.dataset_id, d.name
ORDER BY current_examples DESC
LIMIT 50