DQL Steps

A DQL step is a structured query (read-only SQL) over your collection’s data so you can quickly filter, group, and aggregate. You can run DQL over metadata, transcripts, and the output of prior Reading steps. Your coding agent generates DQL steps as part of Analysis Plans. Example use cases for DQL steps include:

/docent What's the average reward by model across this collection?

/docent Get me the tasks where model A regresses compared to model B when averaging score across rollouts.

DQL steps are read-only in the UI. To revise them, prompt your coding agent. We recommend using a coding agent to generate DQL instead of writing it by hand. For the full DQL syntax (operators, JSON access, CTEs, joins), see the DQL language reference.

Reading and revising DQL steps

In an analysis plan, DQL steps run by default. You can see the results as a table in the UI, and the DQL query that generated them above it. The results table does not sort or filter in place. To order rows, ask your coding agent to put the ordering in the query (e.g., “sort by suspiciousness” adds an ORDER BY clause). DQL steps have deeply linked IDs. When sorting or filtering, ask your coding agent to include an ID column (e.g., agent_runs.id) in the SELECT. Any ID column in the results table renders as a clickable link that opens the linked transcript inline, so you can read the run that produced each row without leaving the plan.

Example queries

Average reward by model

SELECT metadata_json->'model'->>'name' AS model_name,
       AVG((metadata_json->>'reward')::float) AS avg_reward
FROM agent_runs
GROUP BY metadata_json->'model'->>'name'

Success rate by environment

SELECT metadata_json->>'environment' AS environment,
       COUNT(*) AS total_runs,
       SUM(CASE WHEN metadata_json->>'status' = 'completed'
           THEN 1 ELSE 0 END) AS completed,
       CAST(SUM(CASE WHEN metadata_json->>'status' = 'completed'
           THEN 1 ELSE 0 END) AS DOUBLE PRECISION)
         / NULLIF(COUNT(*), 0) AS completion_rate
FROM agent_runs
WHERE metadata_json ? 'environment'
GROUP BY metadata_json->>'environment'
ORDER BY total_runs DESC

Get Started

Analysis Plans

Ingestion

Data Models

Guides

Legacy

Support

Reading and revising DQL steps

Example queries

​Reading and revising DQL steps

​Example queries

Reading and revising DQL steps

Example queries