JQL
TypeScript SDK reference for the complete Judgment Query Language contract.
judgeval-js JQL source on GitHub
JQL is a structured, project-scoped query language for traces, spans, and sessions. These pages document the public TypeScript builder calls, the canonical JSON IR they emit, the server constraints applied to that IR, and the exact public response envelopes.
Install and configure
npm install judgevalProvide JUDGMENT_API_KEY and JUDGMENT_ORG_ID through the environment, then
select a project on the SDK client:
import { Judgeval } from "judgeval";
const client = await Judgeval.create({ projectName: "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
import { Judgeval } from "judgeval";
import { eq, traces } from "judgeval/jql";
const client = await Judgeval.create({ projectName: "my-project" });
const query = traces()
.where(eq("status", "error"))
.last("7d")
.rows({ fields: ["trace_id", "status", "timestamp"], limit: 100 });
const result = await 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(...)JudgevalConfig
Configuration options for the Judgeval client. Credentials are resolved in order: explicit arguments first, then environment variables `JUDGMENT_API_KEY`, `JUDGMENT_ORG_ID`, and `JUDGMENT_API_URL`.
Client methods
TypeScript JQL client methods, request options, and transport behavior.
Last updated on