DQL Schema

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

Get Schema

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

str

required

ID of the collection.

Returns

dict

Schema response containing tables and rubrics.

Show Fields

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.

list[dict]

List of rubric schemas with id, version, name, and output_fields.

Example: Find Metadata Columns

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

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.

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).
`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.

Getting Started

Collections

Agent Runs

DQL

Feedback & Labels

More

Legacy

Get Schema

Parameters

Returns

Example: Find Metadata Columns

Tables

agent_runs

transcripts

transcript_groups

judge_results

​Get Schema

​Parameters

​Returns

​Example: Find Metadata Columns

​Tables

​agent_runs

​transcripts

​transcript_groups

​judge_results

Get Schema

Parameters

Returns

Example: Find Metadata Columns

Tables

agent_runs

transcripts

transcript_groups

judge_results