Skip to main content

Quick Query — Walkthrough

Quick Query is the default mode and the right starting point for the vast majority of slices. It's a point-and-click form that compiles down to the same filter JSON the platform's list pages already use, so anything you can ask in the Customers / Invoices / Subscriptions list pages, you can ask here — plus aggregations, custom field projections, and saved replays.

Step 1 — Open the builder​

  1. Click Workbench → Query Studio in the sidebar.
  2. Click New query in the top-right of the list page.

You land at /workbench/queryStudio/new. The mode toggle defaults to Quick.

Step 2 — Pick an entity​

The Entity dropdown is populated from GET /api/v1/workbench/schema/entities — every JPA-mapped entity in the running platform appears here. Picking one fetches its field metadata from GET /api/v1/workbench/schema/entities/{entity} and renders the field list below.

Common starting points:

  • BillingAccount — billing-side root of every account
  • Invoice — open / past / draft invoices
  • Subscription — active subscriptions and their offers
  • RatedTransaction — pre-invoice rated lines
  • WalletOperation — pre-rated wallet operations
  • Payment — payment events
  • Customer — top of the account hierarchy

Step 3 — Pick fields​

Tick the fields you want to see in the result table. Quick mode currently shows top-level fields only; nested entities (customerAccount, seller, …) are accessible via Deep Query if you need to project from them.

The chosen fields drive both the projection (genericFields in the request body) and the result-table columns.

Step 4 — Run sync​

Click Run sync. The builder posts to POST /api/rest/v2/generic/all/{entity} with:

{
  "genericFields": ["code", "status", "amountWithTax", "dueDate"],
  "limit": 100
}

Results render in the right panel. Foreign-key columns are flattened to description ?? code — you'll see customerAccount.code rendered as CA_PX_BG2, not [Object object].

If your result is bigger than the governor's sync cap (default 1 000 rows), the row count is hard-capped at that value. To get more, switch to Async (see below).

Step 5 — Save​

Below the builder, fill in:

  • Code — your name for the query, uppercase + digits + underscores. Convention: BLR_* is reserved for system templates; pick anything else for personal queries (e.g. MY_OPEN_INVOICES_PX).
  • Description — what the query returns and why it exists.
  • Visibility:
    • PRIVATE — only you can open the link
    • PROTECTED — anyone in your organisation
    • PUBLIC — any signed-in user

Click Save. The URL changes to /workbench/queryStudio/MY_OPEN_INVOICES_PX and the query lands in the Mine tab on the list page.

Step 6 — Replay​

Open the saved query later by:

  • Clicking the row in the Query Studio list page.
  • Pasting the URL /workbench/queryStudio/MY_OPEN_INVOICES_PX into a colleague's browser (subject to visibility).
  • Hitting GET /api/rest/v2/reportQueries?query=code=='MY_OPEN_INVOICES_PX' directly.

Replay loads the entity + fields back into the builder; running again hits the live data, not a cached snapshot.

Async run​

For larger results, toggle the execution mode to Async. The builder enables this only after the query has been saved (the async path needs a ReportQuery.id to attach the result to).

Async submission posts to:

POST /api/rest/v2/reportQueries/{id}/execute?async=true&sendNotification=false

Today the response is just "Accepted". Navigate to the result history (or refresh the saved query view) to see the new QueryExecutionResult row appear with status RUNNING, then COMPLETED. The result file lands at {providerRoot}/exports/queryStudio/{user}/{date}/. The dedicated Result View page (/workbench/queryStudio/{code}/results/{id}) polls and offers CSV / Excel / PDF / JSON download.

The B9 retrofit (returning the new queryExecutionResultId synchronously from the async submit) is a planned follow-up. Until then, Quick async users navigate to the result list to find their submission.

Schedule​

Once a query is saved, click Schedule in the page header to set up a recurring run that emails the result file:

  1. Frequency: Daily / Weekly (with day-of-week) / Monthly (with day-of-month).
  2. Hour + minute (UTC unless your tenant overrides).
  3. File format: CSV / EXCEL / PDF / JSON.
  4. Recipient emails (comma-separated).

Behind the scenes this creates a QueryScheduler + JobInstance pair. The job runs at the chosen cadence and emails the file produced by the same export pipeline as Schedule and Result View.

Limits​

  • 1 000 rows hard cap on sync runs (governor knob workbench.governor.maxRowsSync).
  • 30 s sync timeout (workbench.governor.maxQueryDurationSyncSec).
  • 3 concurrent sync queries per user (workbench.governor.maxConcurrentSyncPerUser).
  • 30 queries / minute / user (workbench.governor.maxQueriesPerMinutePerUser).

If a limit hits, the UI surfaces an amber toast with the specific limit, current count, max, and retry-after seconds. See Governor limits for tuning.

When to leave Quick for Deep​

Switch to Deep Query when:

  • You need a join the dot-notation path can't express.
  • You want a polymorphic query against a subclass hierarchy.
  • You need a window function or a sub-select that the visual chips don't expose.
  • You want to share an executable HQL snippet with another developer.

Quick stays sufficient for ~80% of day-to-day analytics. Deep is the next step up.