Query Builder & List Mode

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

1. Choose the datastore or measures to work from.
2. Add the dimensions to group by, or switch to list mode for rows.
3. Add filters. Parameterise anything that should vary by context rather than hard-coding it.
4. Run it and check the result against something you already know.
5. 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.

List Mode and Row Listings

Not every question is an aggregate. "Which repairs are overdue?" wants rows, not a count — and list mode makes a row listing a first-class thing the BI subsystem can hold, chart and place on a dashboard.

Where to find it

Architect Panel → Data:

• Query Builder — where a query is switched to list mode

Architect Panel → Dashboards:

• BI Dashboards — where a listing is placed alongside charts

Why this needed to exist

Before list mode, a dashboard could tell you there were fourteen overdue repairs but not which ones. The answer was to build a separate browse view with its own filters — which then drifted from the dashboard's definition, so the count and the list disagreed and nobody knew which to believe.

List mode uses the same query definition for both. If the dashboard says fourteen, the listing has fourteen rows in it, by construction.

When to use rows rather than a total

• Work queues — the point is to act on individual items.
• Exceptions — a count of exceptions is less useful than the exceptions.
• Anything under about twenty rows where a person will want to see them all anyway.

Use an aggregate when the number itself is the point, and a listing when the next action is on a row.

Worked example — an exceptions listing

A finance team wanted "invoices over 60 days". The count alone told them there were 23 and nothing else. In list mode the same query returns the 23 rows with customer, value, age and owner — sorted oldest first — and the team works straight down it. The dashboard figure and the listing cannot disagree, because they are one query.

Keep listings short

A listing of two thousand rows on a dashboard is a performance problem and an unreadable screen. Filter it to what is actionable — overdue, unallocated, awaiting approval — and let the full set live in a browse view somebody opens deliberately.

Choose the columns for the decision

Show what somebody needs to decide what to do, not everything the datastore holds. For an overdue repairs listing that is usually the reference, the address, how overdue, and who owns it. The tenancy history is not a decision input at that moment.

Worked example

An operations dashboard carries three blocks: a trend chart of repairs raised, a figure for the current backlog, and a listing of everything more than five days overdue with its patch and owner. The listing is the same query as the figure, in list mode, so the two always agree — and the supervisor works straight from the listing rather than exporting it.

Recommendations

• One definition, two presentations. Never build a separate view to accompany a count.
• Cap the rows and sort by what matters most.
• Include the owner column on anything actionable — a list nobody is named on is a list nobody does.