Dashboards and textboxes

A dashboard is a grid of widgets — visualizations from any number of queries, plus textboxes for the words that explain them.

Arranging

Press Edit to move and resize. The grid is twenty-four columns wide, so a widget can take a third of the width as easily as a half. Nothing is saved until you press Done Editing — moving a widget and navigating away changes nothing, deliberately.

Filters and parameters

Two different things that look alike on screen:

Dashboard-level parameters

A query parameter mapped to the dashboard rather than the widget. Changing it re-runs every query mapped to it. Use this when the warehouse should do different work.

Dashboard filters

Switched on per dashboard, driven by naming a column something::filter in the SELECT. They narrow rows already fetched, in the browser, without re-running anything.

Both live in one button beside Refresh, with a count. While you are editing the layout they move into a row of their own, because that is where they can be dragged into order.

A widget can also keep its own parameter, on its title row. Two visualizations of the same query each keep their own value — so you can show North and South side by side — and they share a single fetch whenever their values agree.

Textboxes

Add one from Edit → Add Textbox. A textbox has three settings: the text, a style, and an alignment.

Style Plain removes the tile — no white card, no border — which is what you want for a heading dividing a page. A section heading sitting in a card reads as a widget that failed to load. Style Card is the ordinary widget look.

What markdown is allowed

Standard markdown with GitHub extensions, plus raw HTML. The editor has Write and Preview tabs, and the preview carries the style and alignment you chose, so it shows the widget rather than an impression of it.

Raw HTML

Allowed, and sanitised on the way in. This is how you get two columns, a coloured callout, or an image at a chosen width:

<div style="display:flex;gap:14px">
  <div style="flex:1;padding:10px;background:#e4f4f7;border-radius:6px">
    Left
  </div>
  <div style="flex:1;padding:10px;background:#f7eedd;border-radius:6px">
    Right
  </div>
</div>

style and class survive. <script> does not, and neither does an onerror or any other event handler — every string is sanitised before it reaches the page, whoever wrote it.

Folders

A folder gives a set of dashboards a stated meaning — “business KPIs”, “operational metrics for the line” — written when the folder is made and shown wherever it appears, so “does this belong here” has an answer rather than an argument. The Dashboards menu lists the folders somebody chose to put there; Browse folders has the rest.

A locked folder is one only administrators change. A dashboard in it cannot be edited, renamed, archived or have a widget added by anybody else — including whoever made it — and moving one in or out is an administrator’s act too. Everybody can still read them, favourite them and put them on a screen: the lock is on changing, never on seeing. A set anybody can edit is a set of dashboards with a label on it; one only administrators curate is a statement about what has been through review.

Filing a dashboard is optional and stays optional. Most never go in a folder, and nothing asks you to pick one before saving.

Streaming dashboards

A dashboard shows streams or saved queries, never both. The reason is the refresh interval: a dashboard has one, a stream panel wants two seconds, and a warehouse panel wants thirty or more. Mixing them would mean either running every warehouse query behind the board every two seconds, or showing a stream half a minute stale. Adding a widget across that line is refused, and which kind a dashboard is you choose when you make it — so an empty one already knows, and it never changes kind under the panels somebody put there on the strength of it.

A streaming dashboard is offered refresh intervals in seconds — 2, 5, 10, 20, 30, 60 and 120 — where an ordinary one is offered half-minutes.

The panels are still until the dashboard is live. A stream is consumed only while somebody is watching it, so a streaming dashboard that is not live says so rather than drawing empty charts. Make it live and the topics start; they stop again about a minute after the last person closes it, and the windows are kept for ten minutes so coming back resumes in seconds. Anybody who can see the dashboard can watch it, and they need no streams permission to do so — they are not starting anything you have not already started.

Find them under Dashboards → Streaming Dashboards, with the same All, Favorites and Mine views as the ordinary half — and nowhere else. The two halves do not overlap, so a dashboard has one place it lives. A folder is the exception, on purpose: it is a place rather than a type, so it shows whatever has been filed in it, of either kind.

An open streaming dashboard says what it is: a streaming chip beside its name, and a band down the side of the page that turns green while its topics are being consumed. The Live badge beside it is a different thing — it says whether the dashboard is refreshing right now, which an ordinary dashboard can be too.

Sharing

A dashboard can be given a public link that needs no login. Anyone with the URL sees it, so it is a secret-by-obscurity share rather than a permission — treat the link as the credential. Public links can be disabled for the whole instance in settings.

Sending it on a schedule

Share → Send on a schedule mails a dashboard to colleagues every hour, day or week, as a picture in the email or a PDF to print. It needs the renderer add-on and the Send dashboards permission; without a renderer the option is not offered, because there would be nothing to send.

Recipients are people in your organization, chosen by name — never typed addresses, which would be a way to mail a dashboard’s contents anywhere. Each is checked against their own access to the dashboard, not yours: anyone who cannot see it is left off and named when you subscribe them, and checked again before every send, so a subscription never outlives somebody’s right to what it carries.

What is sent is the latest saved results, and the email says how old they are. Give the queries a refresh schedule if you want the numbers current — refreshing everything before each send would be a warehouse bill nobody asked for.

A dashboard has to fit on one page: up to twelve widgets, one page tall. Past that it arrives as something nobody opens, so it is refused when you subscribe and again if the dashboard grows afterwards — with the reason shown beside the subscription.

Every email carries an unsubscribe link of its own, and your mail client’s own Unsubscribe button works too. Taking yourself off leaves everybody else on it.

Sending it to Slack

Share → Send to Slack posts a picture of the dashboard to a channel, with a line of your own text and an Open dashboard button. It needs the same renderer and the same Send dashboards permission as a schedule, plus a Slack app connected by an administrator.

SQLDesk draws the picture and uploads it rather than letting Slack fetch a link, which is what makes this work on an install behind a VPN: Slack never has to reach in. A pasted link would unfurl into a bare URL and nothing else.

The channel list comes from Slack, so you pick rather than type. A private channel appears once the app has been invited to it; one it has not been invited to cannot be posted to, so it is not offered.

The button opens the public link where the dashboard has one, so anybody in the channel can open it without an account here. Where it has not been shared — or where public links are off for the whole instance — the button opens the dashboard’s own address, and people sign in. Turning the public link off later is how a button that has already been sent stops working.

The same one-page rule applies as for a schedule: up to twelve widgets, one page. A bigger dashboard is refused before anything is drawn.

Setting it up, once: create a Slack app in your workspace, give it chat:write, files:write, channels:read and groups:read, install it, and paste its bot token under Settings → Slack. The token is checked with Slack before it is stored, and kept encrypted with the same key as your data source credentials. If it is ever revoked, the settings page says so — from here a revoked token looks exactly like a working one until something is sent.

On a wall

A dashboard can be made live: the server refreshes it every 30 seconds to 5 minutes, once for everyone looking, and only while somebody has it open. /wall/dashboards/<token> gives a version with no chrome, for a screen nobody interacts with.