The Query Builder

The Query Builder is where a question becomes a durable, named thing. Explore is for asking; the Query Builder is for keeping.

Where to find it

Architect Panel → Data:

Query Builder — build, test and save queries
Custom Query Views — saved query definitions

Architect Panel → Dashboards:

Explore — ad-hoc questions against the same layer
BI Dashboards — where saved queries are placed

One definition, four destinations

This is the reason the Query Builder matters more than it first appears. A saved query can be used in four places without being rebuilt:

On a dashboard, as a chart or a figure.
On a record screen, as a pane scoped to that record.
On a schedule, rendered and delivered on a clock.
Through the API, as a read-only dataset.

Because all four draw the same definition, they cannot disagree. The figure on the manager's dashboard, the one in the emailed report, and the one a partner system reads through the API are necessarily the same figure — which is not true of four separately-built queries that happen to have the same name.

Saving under a key

A saved query has a stable key. That key is what a pane, a schedule or an API caller refers to, so renaming the human-readable title does not break anything pointing at it. Choose keys deliberately and treat them as you would any other identifier — they end up in other people's configuration.

Building one

Choose the datastore or measures to work from.
Add the dimensions to group by, or switch to list mode for rows.
Add filters. Parameterise anything that should vary by context rather than hard-coding it.
Run it and check the result against something you already know.
Save it with a clear name and a stable key.

Parameters

A query that takes a parameter is reusable; one with a hard-coded value is not. "Cases for team X" becomes "cases for a team" with the team as a parameter, and the same query then serves every team's dashboard and every team leader's pane.

Test before you publish

Run the query and reconcile it once. A saved query gets copied into dashboards, panes and emails, so an error in it propagates to every one of them — and the further it spreads the harder it is to correct without somebody noticing the numbers changed.

Worked example

A repairs service saves "open repairs by priority", parameterised by patch. It appears on the operations dashboard filtered to all patches, on each supervisor's record pane filtered to theirs, and in a Monday morning email to the service manager. One definition, three audiences, no possibility of them disagreeing.

Recommendations

Parameterise rather than duplicating. Ten near-identical queries will drift.
Name for the question, not the screen — the same query will end up on several.
Reconcile once at save time.
Review saved queries annually and delete what nothing uses.