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

> Introspect available tables and columns for DQL queries

Use `get_dql_schema` to discover what tables and columns are available for a collection.
This is useful for programmatically building queries.

## Get Schema

```python theme={null}
from docent import Docent

client = Docent()

schema = client.get_dql_schema("my-collection-id")
for table in schema["tables"]:
    print(f"\nTable: {table['name']}")
    for col in table["columns"]:
        print(f"  {col['name']}: {col['data_type']}")
```

### Parameters

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

### Returns

<ResponseField name="schema" type="dict">
  Schema response containing tables and rubrics.

  <Expandable title="Fields">
    <ResponseField name="tables" type="list[dict]">
      List of table objects, each with `name`, `aliases`, and `columns`.
      Each column has `name`, `data_type`, `nullable`, `is_primary_key`,
      and optionally `foreign_keys` and `alias_for`.
    </ResponseField>

    <ResponseField name="rubrics" type="list[dict]">
      List of rubric schemas with `id`, `version`, `name`, and `output_fields`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example: Find Metadata Columns

```python theme={null}
schema = client.get_dql_schema(collection_id)

# Find the agent_runs table
agent_runs_table = next(t for t in schema["tables"] if t["name"] == "agent_runs")

# List all columns
for col in agent_runs_table["columns"]:
    print(f"  {col['name']} ({col['data_type']}, nullable={col['nullable']})")
```

## Tables

<Note>
  JSON operators work directly on `agent_runs.metadata_json`, `transcript_groups.metadata_json`, `judge_results.output`, and `judge_results.result_metadata` (stored as `jsonb`). The `transcripts.messages` and `transcripts.metadata_json` columns are stored as `bytea` (UTF-8 JSON) — wrap them in `convert_from(col, 'UTF8')::jsonb` before applying `->`, `->>`, `jsonb_array_length`, etc.
</Note>

### agent\_runs

| Column | Description |
| - | - |
| `id` | Agent run identifier (UUID). |
| `collection_id` | Collection that owns the run |
| `name` | Optional user-provided display name. |
| `description` | Optional description supplied at ingest time. |
| `metadata_json` | User supplied metadata, stored as JSON. |
| `created_at` | When the run was recorded in Docent. |

### transcripts

| Column | Description |
| - | - |
| `id` | Transcript identifier (UUID). |
| `collection_id` | Collection that owns the transcript. |
| `agent_run_id` | Parent run identifier; joins back to `agent_runs.id`. |
| `name` | Optional transcript title. |
| `description` | Optional description. |
| `transcript_group_id` | Optional grouping identifier. |
| `messages` | UTF-8 bytes of a JSON array of message turns (Postgres `bytea`, not `jsonb`). Decode with `convert_from(messages, 'UTF8')::jsonb` before using JSON operators or `jsonb_array_length` (see [Counting transcript messages](/sdk/dql/execute#counting-transcript-messages)). |
| `metadata_json` | UTF-8 bytes of JSON metadata (`bytea`). Use the same `convert_from(..., 'UTF8')::jsonb` pattern as `messages` before applying JSON operators. |
| `dict_key` | Dictionary key for transcript identification. |
| `created_at` | Timestamp recorded during ingest. |

### transcript\_groups

| Column | Description |
| - | - |
| `id` | Transcript group identifier. |
| `collection_id` | Collection that owns the group. |
| `agent_run_id` | Parent run identifier; joins back to `agent_runs.id`. |
| `name` | Optional name for the group. |
| `description` | Optional descriptive text. |
| `parent_transcript_group_id` | Identifier of the parent group (for hierarchical groupings). |
| `metadata_json` | JSONB metadata payload for the group. |
| `created_at` | Timestamp recorded during ingest. |

### judge\_results

| Column | Description |
| - | - |
| `id` | Judge result identifier. |
| `agent_run_id` | Run scored by the rubric. |
| `rubric_id` | Rubric identifier. |
| `rubric_version` | Version of the rubric used when scoring. |
| `output` | JSON representation of rubric outputs. |
| `value` | Deprecated: use `output` instead. |
| `result_metadata` | Optional JSON metadata attached to the result. |
| `result_type` | Enum describing the rubric output type. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.