Concepts
Authoring benchmark questions
Questions live in your data model repository, versioned and branched like the rest of it. You can keep them in a single top-levelagents/eval_questions.yml file — the simplest place to start — or
split them across any number of agents/eval_questions/*.yml files as your set
grows. The parser picks up both and merges every file’s eval_questions list
into one set, so you can move from one file to many at any time without changing
anything else. A run can also be scoped to a single file (see
Running an eval).
Each file has a top-level eval_questions list. A question needs a unique
name, a question, and exactly one ground truth: a certifiedQuery
reference or inline sql.
certifiedQueryreferences a certified query by name. Define it underagents/certified_queries/(or via Certify this query in chat). A reference that doesn’t resolve to an existing certified query is flagged as a validation error.sqlis inline ground-truth SQL, run through the same Cube SQL API the agent uses (soMEASURE(...)and friends work).- Omitting both — or setting both — is a validation error.
- An optional top-level
spacekey scopes a file’s questions to a named space (defaults toauto). Question names are unique per space.
The Questions tab is a read-only view of these files — its File
column shows which file defined each question. To add or edit questions, edit
the YAML in the IDE — there’s no in-product question editor yet.
Running an eval
On the Evals tab, click Run eval and choose:- Branch — which branch’s data model and agent configuration to run against. Defaults to the active branch.
- Questions — All questions (the default) or a single question file, to run only that file’s questions. The selector appears only when the selected branch’s questions come from more than one file, and each file option shows how many questions it holds. Switching branches resets it to All questions.
- Agent —
auto(the implicit auto-agent) or a configured agent name.
Run evals from CI
You can gate a pull request with either the Cube CLI or the public Platform API. In both cases, store the tenant URL and deployment ID as repository variables, store the API key as a secret, and pass the branch under review. The API key needsSchemaUpdate access to start a run and either SchemaRead
or SchemaUpdate access to poll it and read its results.
This capability is currently in preview. Contact Cube support to activate it
for your account.
With the Cube CLI
SetCUBE_CLI_VERSION to the Cube CLI release you have tested, then install
that exact version in the job:
pass. It also fails closed if the API does not confirm a complete result
set. When a complete result set is returned, the command writes eval.json
before exiting, including on a failed verdict. If results cannot be verified,
the step log explains why and the empty output file is removed, so no empty
artifact is uploaded. Add --agent NAME to test a configured agent or
--file eval_questions/revenue.yml to limit the run to one question file. Pass
--json for a machine-readable document containing both the terminal run and
its per-question results when the result set is complete.
With the Platform API
If you do not want to install the CLI, call the same public endpoints directly. This example does not retry thePOST, because repeating a non-idempotent start
request after an ambiguous network failure could create another run. It bounds
every GET, retries transient read failures, and applies the same fail-closed
checks as the CLI. Because reads are idempotent, it retries connection resets
too; a permanent read error such as 401 will also be retried four times before
the job fails. Each read writes to a file so curl can discard a partial response
before retrying.
POST body also accepts agentName and questionFile. Omitting the
pagination parameters on the results request returns the complete result set;
if pageInfo.hasNextPage is anything other than false, do not use that page
as a CI verdict.
Both recipes require every selected question to return pass. A review
verdict, including one caused by missing ground truth, fails the CI gate. Keep
questions intended for manual review in a separate file, then use CLI --file
or API questionFile to run an automatically gradable file in CI.
Reading the results
Open a run to see per-question results: the question list on the left, with a pass/fail icon for each, and the selected question’s detail on the right. The run’s scope is repeated in the header, next to Questions.- Assessment —
pass,fail,review, orerror. - Score reason — when a question doesn’t pass, a tag categorizing why: Row count mismatch, Missing columns, Value mismatch, Unexpected rows, Query error, Ground truth query failed, Ground truth not found, or Agent error.
- Failure analysis — a plain-English explanation, e.g. “The agent returned 3 rows, but the ground truth has 5 rows.”
- Model output · SQL vs. Ground truth SQL answer — the agent’s query side-by-side with the ground truth, so you can spot the difference.
- Response — the agent’s full text answer, rendered as Markdown.
How grading works
Grading is execution-based, not text-based — the same approach used by industry text-to-SQL benchmarks such as BIRD and Spider 2.0. The agent’s SQL and the ground-truth SQL are both executed, and their result sets are compared. So an answer that’s worded or written differently but produces the same data still passes. The comparison is:- Sort-invariant — row order never matters.
- Numeric-tolerant — values are compared to 4 significant figures, so
float/representation noise (
6646vs.6646.0) doesn’t fail. - Column-name-agnostic and lenient on extra columns — each ground-truth
column must be reproduced by some agent column, matched by its values, so
revenuevs.totalaliases don’t matter. Extra columns the agent adds are ignored. - No standalone row-count gate — row count falls out of the comparison: a “top 5” question is enforced because the golden result has exactly 5 rows.
Limitations
- Questions are authored as code only; the Questions tab is read-only.
- Very large question sets can be slow to run in full. To iterate faster, split
them across
agents/eval_questions/*.ymlfiles and scope the run to one file. - Grading is execution-based on the result set; it does not semantically judge prose answers.