JQL
Python SDK reference for the complete Judgment Query Language contract.
JQL is a structured, project-scoped query language for traces, spans, and sessions. These pages document the public Python builder calls, the canonical JSON IR they emit, the server constraints applied to that IR, and the exact public response envelopes.
Install and configure
pip install judgevalProvide JUDGMENT_API_KEY and JUDGMENT_ORG_ID through the environment, then
select a project on the SDK client:
from judgeval import Judgeval
client = Judgeval(project_name="my-project")The SDK resolves the project name to an ID. Organization and project scope are sent by the SDK and must not appear in JQL JSON.
First query
from judgeval import Judgeval
from judgeval.jql import eq, traces
client = Judgeval(project_name="my-project")
query = (
traces()
.where(eq("status", "error"))
.last("7d")
.rows(fields=["trace_id", "status", "timestamp"], limit=100)
)
result = client.query(query)The builder emits this language-neutral JSON:
{
"op": "query",
"source": "traces",
"filter": { "op": "eq", "field": "status", "value": "error" },
"time": { "last": "7d" },
"select": {
"op": "rows",
"fields": ["trace_id", "status", "timestamp"],
"limit": 100
}
}Reference map
| Page | Contract covered |
|---|---|
| Client methods | Authentication context, query, present, discover, request limits, transport |
| Queries and terminals | Roots, time bounds, immutable chaining, select operations, row shapes |
| Filters and expressions | Every filter/expression constructor, allowed nesting, validation constraints |
| Pipelines | Stage order, current-column semantics, limits, expressions, grain changes |
| Presentations | Chart/table inputs, field formats, typed frame output, rendering boundary |
| Discovery | Catalog kinds, valid options, and returned columns |
| Responses and errors | Exact public envelopes, nullability, error classes, status/code handling |
Query structure
A source query contains one grain, an optional root filter, an optional time bound,
and either one select terminal or a pipeline. select and pipe are mutually
exclusive. A presentation wraps a source query; discovery is a separate root object.
source(traces | spans | sessions)
-> root filter?
-> time?
-> select terminal
OR pipeline stages
-> optional table/chart wrapper
-> client.query(...) OR client.present(...)