Probara Query Language (PQL) reference

Probara Query Language (PQL) asks questions of your test data. A query names an entity, such as cases or results, filters its rows with WHERE, and can group and aggregate them. Write PQL in Queries, or send it to the PQL API.

Quick path

1. Name the entity: FROM cases.
2. Filter the rows: WHERE priority = "High".
3. Choose the page: LIMIT 50.

FROM cases WHERE priority = "High" AND status = "Active" ORDER BY title LIMIT 50

Query shape

Rules:

• Keywords, function names, entity names and field names are not case-sensitive.
• A line comment starts with --.
• Line breaks and extra spaces do not matter.
• A query with SELECT and an aggregate returns grouped rows. Any other query returns rows.
• A SELECT item that is not aggregated must appear in GROUP BY.

Literals

Notes:

• Text values must be quoted. title = Login is an error, and title = "Login" works.
• Names of milestones, suites, environments, tags and projects are text. Quote them when they contain spaces: milestone = "Release 1.4".
• Fixed-duration fields, such as runs.duration, accept m, h, d and w only. Use mo, q and y only in relative time.

Operators

Boolean fields accept only = and !=, so write archived = true, not archived.

Entities

Every entity has an id, which is its display ID, and a project. The tables list the fields you can use. A field marked Optional can be empty, so is empty applies to it. A field marked History supports was and changed.

Cases

Default columns: id, title, suite, priority, status.

Relations: results, runCases, defects, jira. Custom fields: cf[...].

Suites

Default columns: id, name, parent, cases.

Relations: cases.

Runs

Default columns: id, name, state, status, milestone, passRate.

Relations: results, runCases, defects. Custom fields: cf[...].

Run cases

Run cases are the cases inside a run, including the ones not yet tested. Default columns: run, case, status, assignee, elapsed.

No relations.

A run case of a parameterized case is one instance: a case with two parameters of three values each has nine run cases in a run. Count them with count() over the run cases, and see Parameterized test cases.

Results

Default columns: id, run, case, status, executedBy, executed.

No relations. Custom fields: none.

Defects

Default columns: id, title, status, severity, priority, assignee.

Relations: cases, results. Custom fields: cf[...].

Milestones

Default columns: id, name, status, due.

Relations: runs, cases, defects.

Plans

Default columns: id, name, status, milestone.

Relations: runs, cases.

Shared steps

Default columns: id, title, folder, updated.

No relations.

Custom fields

Cases, runs and defects have your organization’s custom fields. Write the field’s title in brackets:

FROM cases WHERE cf["Risk"] = "High"

The title is matched ignoring capital letters and surrounding spaces. A title that no custom field of that entity has returns unknown_custom_field.

Paths to related records

Results and run cases link to a run and a case. Reach into them with a dot path:

FROM results WHERE run.environment = "staging" AND case.priority = "Critical" AND status = failed

Paths work in WHERE and in GROUP BY, for example GROUP BY run.environment.

lastResult

lastResult is the most recent result of a case, by execution time and then by ID. It is available on cases at the top level of a query.

• lastResult.status reads the status of the latest result.
• lastResult(environment = "staging").status reads the latest result among the runs that match the condition. The condition uses run fields, such as environment, milestone and plan.
• A case with no matching result has no value, so = does not match it.

FROM cases WHERE lastResult(environment = "staging").status = failed ORDER BY title

lastResult cannot be compared directly, and it has no history.

Relations

exists and count look at the related records of each row.

FROM cases WHERE exists(results where status = failed)
FROM cases WHERE NOT exists(results)
FROM cases WHERE count(results where status = failed) >= 3

Rules:

• Use exists and count in WHERE. exists in HAVING returns relation_placement.
• Compare count(relation) with a number.
• Sub-queries nest at most two levels deep. FROM suites WHERE exists(cases where exists(results where status = failed)) is two levels.
• Related rows count only in projects you can access, and each related record counts once.
• Archived cases are left out of a related-record condition over cases unless the condition names archived. See Archived cases.

Functions

passRate() counts the following:

• On results, passed results divided by all results.
• On runs, passed cases divided by passed, failed, blocked and skipped cases. This is the same figure as runs.passRate.

SELECT bucket(executed, week) AS period, passRate() AS rate, count() AS results FROM results GROUP BY 1 ORDER BY 1

Time and time zones

Dates and relative times are read in the Timezone of your profile. With Auto-detected, UTC is used. now, startOf, endOf, bucket and the date comparisons all follow this zone.

Relative time accepts every unit: m, h, d, w, mo, q and y. Fixed-duration fields accept m, h, d and w.

Aggregation rules

• GROUP BY takes fields, expressions and positions, such as GROUP BY 1. It does not take a SELECT alias. Repeat the expression, or use its position.
• HAVING filters groups with aggregates, such as HAVING count() > 5. It does not take aliases, so HAVING n > 5 fails.
• ORDER BY takes aliases (ORDER BY n DESC), positions counted from 1 (ORDER BY 2) and aggregates (ORDER BY count() DESC). Aggregates need a group or an aggregate in SELECT. User and tag fields cannot be sorted.
• Grouping works on number, boolean, enum, option, user, reference and tag fields. Text and dates cannot be grouped directly. Group a date with bucket().
• Tags and multi-select fields count a row in the group of each of its values. Two such fields grouped together give one group per combination, so the groups can add up to more than the number of rows.
• No value. Rows without a value form a group named No value. It sorts first.
• count(field) counts the rows where the field has a value.
• HAVING on a tag or multi-select field is refused. Filter in WHERE instead.
• Without GROUP BY, an aggregate returns one row for all matching rows.
• Time buckets start at the start of the unit in your time zone. Empty buckets are not returned.
• Date pickers compare by local day.
• Groups are shown up to 1,000 per page. The result says so when there are more.

History

Change history records changes to some fields. Two operators read it:

• status was in_progress is true when the value is the current value, or was one of the values recorded in the history.
• status changed is true when the history holds at least one change. Add modifiers to narrow it:

All the modifiers you write must match the same change. t is a date or a relative time, read in your time zone.

FROM defects WHERE status changed from resolved to open after now(-14d)
FROM cases WHERE priority changed by currentUser() after now(-7d)

Fields with history

Change history is not available for run state, milestone and suite moves, custom fields (cf[...]), or linked fields. A query that uses them returns history_not_available.

Rules:

• Use was and changed in WHERE. In HAVING they return history_placement.
• Change history keeps records for your plan’s history retention window. See Data retention.
• Changes made before the record was audited are not known, so a value can be missing from its history.

In query() references

id in query("Saved name") keeps the rows that a saved query returns:

FROM cases WHERE id in query("Critical failures")

• The saved query must return the same entity, and in rows mode.
• Its ORDER BY and LIMIT are ignored.
• A saved query can refer to another query up to three levels deep. A cycle is refused.
• You can refer only to queries you can see. An unknown or hidden name returns unknown_saved_query.

Archived cases

A query over cases leaves out archived cases unless the query names archived itself. The same rule applies to a related-record condition over cases, such as exists(cases ...).

FROM cases WHERE title ~ "login"                 -- archived cases are left out
FROM cases WHERE archived = true                 -- the condition decides

A query over results is different. Archiving keeps a case’s execution history, so FROM results (and FROM runCases) includes the results of archived cases. To leave them out, name the case as live:

FROM results WHERE case.archived = false         -- the results of archived cases are left out

Limits

Errors

Each error has a code, a message, and the place in the query where it occurs. Through the API, each error appears in details.errors with the same code. See Errors.

Syntax errors

Names and functions

Values and operators

Aggregates, grouping and paging

When the server does not support a construct yet, the query returns Not available yet in the editor, with the construct named. Remove that part of the query for now.

Worked examples

Each example answers one common question. Replace the names with your own suites, milestones and environments.

Next step

• Write and run queries in Queries.
• Put a saved query on a dashboard in Dashboards.
• Send queries from code with the PQL API.