> ## 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 on `agent_runs.metadata_json`, `transcript_groups.metadata_json`, `judge_results.output`, and `judge_results.result_metadata` (stored as JSONB). The `transcripts.metadata_json` column is stored as binary and does not support direct JSON operators in queries.
</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`            | Binary-encoded JSON payload of message turns.         |
| `metadata_json`       | Binary-encoded metadata describing the transcript.    |
| `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.        |