Skip to main content
DQL (Docent Query Language) lets you query agent runs, metadata, and evaluation results using a SQL-like syntax. See DQL Reference for full syntax.

​
Execute a Query

from docent import Docent

client = Docent()

result = client.execute_dql(
    "my-collection-id",
    "SELECT id, metadata_json->>'model' AS model FROM agent_runs LIMIT 10",
)

​
Parameters

​
collection_id
str
required
ID of the collection to query.
​
dql
str
required
The DQL query string.

​
Returns

​
result
dict
Query result.

​
Errors

  • ValueError — dql is empty
  • HTTPError — Invalid DQL syntax or collection not found

​
Convert Results to Dicts

result = client.execute_dql(
    "my-collection-id",
    "SELECT id AS run_id, metadata_json->>'model' AS model FROM agent_runs LIMIT 5",
)

rows = client.dql_result_to_dicts(result)
for row in rows:
    print(row)  # {"run_id": "abc-123", "model": "gpt-4"}

​
Parameters

​
dql_result
dict
required
A result dict returned by execute_dql.

​
Returns

​
rows
list[dict]
List of dictionaries, one per row, with column names as keys.

​
Common Query Patterns

​
Filter by metadata

result = client.execute_dql(
    collection_id,
    """
    SELECT id, metadata_json->>'score' AS score
    FROM agent_runs
    WHERE metadata_json->>'model' = 'gpt-4'
      AND CAST(metadata_json->>'score' AS DOUBLE PRECISION) > 0.8
    """
)

​
Join with evaluation results

result = client.execute_dql(
    collection_id,
    """
    SELECT
        ar.id,
        jr.output->>'label' AS label,
        jr.output->>'explanation' AS explanation
    FROM agent_runs ar
    JOIN judge_results jr ON ar.id = jr.agent_run_id
    WHERE jr.rubric_id = 'rubric-123'
    """
)

​
Count and aggregate

result = client.execute_dql(
    collection_id,
    """
    SELECT
        jr.output->>'label' AS label,
        COUNT() AS count
    FROM judge_results jr
    WHERE jr.rubric_id = 'rubric-123'
    GROUP BY jr.output->>'label'
    """
)
For complete syntax, see the DQL Reference.