# Queries

> Ask your own questions of your test data, read the answers as tables and charts, export them, and save the queries you reuse.

**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](https://docs.probara.net/en/guides/dashboards/) as a live widget.

| Question                      | Answer                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------ |
| 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](https://docs.probara.net/en/guides/billing/).

## Open Queries

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

| Column         | What it shows                                                                 |
| -------------- | ----------------------------------------------------------------------------- |
| **Name**       | The name, with the description below it                                       |
| **Owner**      | The member who created it, or **Former member** if they left the organization |
| **Visibility** | **Public** or **Private**                                                     |
| **Updated**    | When 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](https://docs.probara.net/en/guides/pql-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](https://docs.probara.net/en/guides/pql-reference/#errors) 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:

| Mode             | What it needs                                                                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| **Table**        | Any query.                                                                                           |
| **Bar**          | An aggregate query with a group and a measure, such as `SELECT status, count() ... GROUP BY status`. |
| **Line**         | An aggregate query with a time bucket, such as `bucket(created, month)`, and a measure.              |
| **Donut**        | An aggregate query with one group and one measure.                                                   |
| **Single value** | An 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](https://docs.probara.net/en/developers/api/pql/).

## 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**:

   | Choice      | Who can see it                                                              |
   | ----------- | --------------------------------------------------------------------------- |
   | **Public**  | Every member of the organization.                                           |
   | **Private** | You, 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](https://docs.probara.net/en/guides/dashboards/#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](https://docs.probara.net/en/guides/user-profile/). With **Auto-detected**, they use UTC.

## Next step

- Learn the language in the [PQL language reference](https://docs.probara.net/en/guides/pql-reference/).
- Put a saved query on a dashboard in [Dashboards](https://docs.probara.net/en/guides/dashboards/#query-widgets).
- Run and save queries from code with the [PQL API](https://docs.probara.net/en/developers/api/pql/) and the [Saved queries API](https://docs.probara.net/en/developers/api/saved-queries/), or from an AI agent with the [MCP server](https://docs.probara.net/en/developers/mcp-tools/).