> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transluce.org/llms.txt
> Use this file to discover all available pages before exploring further.

# DQL Steps

> Structured queries generated by your coding agent.

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](/analysis/reading-steps). Your coding agent generates DQL steps as part of [Analysis Plans](/analysis/analysis-plans). Example use cases for DQL steps include:

```text wrap theme={null}
/docent What's the average reward by model across this collection?
```

```text wrap theme={null}
/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](/analysis/dql).

## 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**

```sql theme={null}
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**

```sql theme={null}
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
```