Docs · Guides

Queries

Queries answers questions that the built-in pages do not. You write a query in the Probara Query Language (PQL), run it, and read the answer as a table or a chart. Save a query to reuse it, and add a saved query to a dashboard as a live widget.

QuestionAnswer
Which plans include Queries?Pro and Enterprise (and during a trial). On Free, the item opens the upgrade dialog.
Who can run a query?Every member, viewers included. Results include only the projects you can access.
Who can save a query?Owner, Admin and Member. Viewer cannot.
Who sees a public query?Every organization member.
Who sees a private query?Its creator, organization owners and admins, and the members and groups picked for it.
Who can change or delete one?Its creator, and organization owners and admins.

Plans

Queries use the same plans as dashboards: Pro and Enterprise. On Free, Queries stays in the top navigation next to Dashboards. Clicking it opens the upgrade dialog, with a See plans button.

If your organization moves to Free, nothing is deleted. Saved queries are kept and come back when the organization is on Pro or Enterprise again. See Billing.

Open Queries

Click Queries in the top navigation. The list shows the saved queries you can see, most recently updated first:

ColumnWhat it shows
NameThe name, with the description below it
OwnerThe member who created it, or Former member if they left the organization
VisibilityPublic or Private
UpdatedWhen the query last changed

Search by name with Search queries. For a row, the actions menu (⋯) has Open, Edit settings, Duplicate and Delete. To write a new query, click New query.

Write and run a query

  1. Click New query, or open a saved query, and write your query in the Query box.
  2. Run it with Ctrl+Enter or Cmd+Enter, or click Run.
  3. Read the results below the editor.

The editor suggests keywords, entities, fields, enum values, functions, operators, custom fields, members and saved query names as you type. It marks problems as you type and counts them. For the full syntax, see the PQL language reference.

The query text is kept in the page address. Copy the link to share a draft with a colleague who can see the same projects.

Read an error

When a query has a problem, the results area lists the problems, with the position of each one, for example Line 2, column 14. Each problem has a code, which the language reference explains with what to change.

Two messages need a different fix:

  • The query is longer than 4,000 characters. Shorten the query.
  • Not available yet. The part named in quotes is not supported yet. Remove it for now.

Read the results

  • The table shows one row per record, or one row per group for an aggregate query. A row links to its record where the app has a page for it, such as a case or a suite.
  • Results are shown in pages of 50 rows by default. Add LIMIT (up to 500) and OFFSET (up to 10,000) to change the page size and the start. Use the page numbers, or Previous and Next, to move between pages.
  • When more rows match than PQL counts, the total reads 10,000+.
  • An aggregate query shows at most 1,000 groups. The notice “Only the first 1,000 groups are shown. Add a condition to narrow the results.” means the rest are not shown.
  • No results means no record matches for the projects you can access.
  • A query over results includes the results of archived cases, since archiving keeps the execution history. To leave them out, add case.archived = false, as in FROM results WHERE case.archived = false.
  • An empty value shows as No value. Yes and no values show as Yes and No.
  • A page past the last result shows “This page is past the last result.” Click Back to first page.

Hidden projects

If the query matches projects you cannot access, the results say so. For example, “Not included: 2 projects you can’t access.” Read the numbers as partial, not as the total. Archived and locked projects are never included, for anyone.

Choose Render as

Choose a way from the Render as list to show the same result in another form:

ModeWhat it needs
TableAny query.
BarAn aggregate query with a group and a measure, such as SELECT status, count() ... GROUP BY status.
LineAn aggregate query with a time bucket, such as bucket(created, month), and a measure.
DonutAn aggregate query with one group and one measure.
Single valueAn aggregate query that returns exactly one row.

A mode that does not fit the result is disabled in the list. Hover over it to read why, for example “Needs a time bucket, such as bucket(created, month).” Charts draw the rows on the current page only.

Export CSV

Export CSV downloads the rows on the current page. The file is written for spreadsheets and other tools:

  • Times are in UTC, in ISO format.
  • Durations are in milliseconds.
  • The file is UTF-8 with a byte order mark, and its lines end in CRLF.
  • Text that a spreadsheet could run as a formula is escaped.

To export more than one page, use the full export. It downloads up to 10,000 rows, or up to 1,000 groups for an aggregate query. The same export is available through the PQL API.

Save a query

  1. Click Save in the editor. The Save query dialog opens.

  2. Enter a Name, up to 120 characters, and an optional Description, up to 2,000 characters.

  3. Choose Who can see it:

    ChoiceWho can see it
    PublicEvery member of the organization.
    PrivateYou, the members and groups you choose, and organization owners and admins.

  4. For Private, pick the people in the Members tab and the groups in the Groups tab. Each tab’s label shows how many it holds, and a pick comes off with its ×.

  5. Click Save query.

Names are unique in the organization, and the check ignores capital letters. If the name is taken, the dialog says “A query with this name already exists.”

Once a query is saved:

  • Save stores your changes to it. Text that differs from the saved query is marked Unsaved changes. Leaving the page with unsaved changes asks “Discard unsaved changes?”, with Keep editing and Discard changes.
  • Save as saves the current text as a new query. The copy keeps the same visibility and starts with no members or groups.
  • Duplicate, in the list’s actions menu, makes a copy named <name> (copy). If that name is taken, the copy is named <name> (copy 2), then (copy 3), and so on.

Change a query’s settings

Click Edit settings in the list, or open the query and choose Query settings. You can change the name, the description and who can see the query. Click Save settings.

Only the creator and organization owners and admins can change a query. Anyone else who opens its settings sees “You cannot change this query.”

Delete a query

In the list, open the row’s actions menu (⋯), choose Delete, and confirm with Delete query. The query is deleted for everyone who can see it, and this cannot be undone.

If a dashboard widget uses the query, the widget stays on the dashboard in a “query deleted” state. An editor removes it from the dashboard. See Query widgets.

Who can see a query

  • A public query is visible to every member.
  • A private query is visible to its creator, organization owners and admins, and the members and groups picked for it.
  • A query you cannot see is not listed. Opening its link shows “This query does not exist, or you can’t see it.”

Dates and time zones

Dates and relative times, such as now(-7d) and startOf(week), use the Timezone in your profile. With Auto-detected, they use UTC.

Next step

More guides