# Dashboards: grafieken over je data

> Bouw Grafana-achtige dashboards over je site- en warehouse-databases, met tijdmacro's, variabelen en automatisch verversen.

Source: https://veldhost.eu/nl/docs/dashboards

Last verified: 2026-11-13

**Dashboards** maakt van de tabellen in je sitedatabases en je warehouse grafieken, kerncijfers en tabellen die iedereen op je account kan openen. Het werkt als Grafana, met een tijdkiezer, automatisch verversen en variabelen, maar er is niets te installeren. Je opent het via de zijbalk: **Data → Dashboards**. Dashboards zitten bij elk abonnement, en een dashboard openen of verversen wordt nooit gemeten. Alleen [jobruns](https://veldhost.eu/docs/pipelines-and-jobs) worden gemeten, boven de inbegrepen minuten van je warehouse-niveau.

## Wat een dashboard is

Een dashboard is een raster van 24 kolommen met **panels**. Elk panel is één alleen-lezen SQL-query op een van je databases (de MariaDB- of PostgreSQL-database van een site, of een warehouse-database die een job of een import vult) en één manier om het resultaat te tonen:

- **Time series**: lijnen, vlakken of staven in de tijd, eventueel gestapeld; meerdere reeksen uit meerdere numerieke kolommen, of uit een groepskolom;
- **Bar**: categorieën vergeleken, horizontaal of verticaal;
- **Stat**: één getal, met een optionele sparkline en drempelkleuren;
- **Gauge**: één getal afgezet tegen een bereik, op een boog met drempelbanden;
- **Table**: rijen zoals ze terugkomen, met sorteerbare kolomkoppen en eenheden per kolom;
- **Pie chart**: aandelen van een totaal, als taart of donut.

Druk op **e** om te bewerken en panels te verslepen, **v** om terug te gaan naar bekijken, **t** voor de tijdkiezer, **f** om het panel onder je muisaanwijzer schermvullend te tonen, **r** om elk panel te verversen, en **Esc** om de paneleditor te sluiten. Tijdens het bewerken kun je een panel ook verplaatsen en van grootte veranderen zonder te slepen: het actiemenu ervan heeft **Move left**, **Move right**, **Move up** en **Move down**, en **Wider**, **Narrower**, **Taller** en **Shorter**, één rasterstap per klik; met de pijltjestoetsen verplaats je een panel dat de focus heeft, en met **Shift** + pijltjes verander je de grootte. Op een smal scherm kun je de indeling niet wijzigen. Elk dashboard bewaart zijn recente opgeslagen versies onder **Versions**, en kan een ster krijgen, gedupliceerd worden (**Duplicate**) en geëxporteerd worden als JSON-bestand (**Export JSON**, schema `veldhost.dashboard/v1`) dat **Import a dashboard** in elk account inlaadt.

## Tijd en verversen

De tijdkiezer biedt voorinstellingen van **Last 5 minutes** tot **Last 90 days**, een absoluut bereik, en de `now-…`-notatie: `now-24h`, `now-7d`, `now/d` (sinds middernacht), `now-1d/d` (gisteren, de hele dag), met de eenheden `s m h d w M y`. Het bereik staat in de URL (`?from=now-7d&to=now`), dus een link opent precies wat jij zag. Automatisch verversen staat op **Off**, **30s**, **1m**, **5m** of **15m**, en pauzeert zolang het browsertabblad verborgen is. **Dashboards werken in UTC**: elke panelquery draait met de tijdzone van de sessie op UTC, en de tijdmacro's werken met epochtijd, zodat dezelfde query op MariaDB en PostgreSQL dezelfde buckets geeft.

## Macro's

De SQL van een panel mag deze macro's gebruiken. Ze worden op de server ingevuld voor het huidige tijdbereik, voordat de alleen-lezencontrole de query nakijkt, dus de database-engine ziet altijd gewone SQL. *F* en *T* zijn het begin en einde van het bereik in epochseconden. *N* is de automatische bucketbreedte in seconden: de kleinste stap op een vaste ladder die een reeks onder de *max points* van het panel houdt, en nooit onder zijn *min interval*.

| Macro | MariaDB | PostgreSQL |
| --- | --- | --- |
| `$__timeFilter(col)` | `(col >= FROM_UNIXTIME(F) AND col < FROM_UNIXTIME(T))` | `(col >= to_timestamp(F) AND col < to_timestamp(T))` |
| `$__timeFrom()` / `$__timeTo()` | `FROM_UNIXTIME(F)` / `FROM_UNIXTIME(T)` | `to_timestamp(F)` / `to_timestamp(T)` |
| `$__unixEpochFilter(col)` | `(col >= F AND col < T)` | hetzelfde |
| `$__unixEpochFrom()` / `$__unixEpochTo()` | `F` / `T` | hetzelfde |
| `$__interval` | `INTERVAL N SECOND` | `INTERVAL 'N seconds'` |
| `$__interval_s`, `$__range_s` | de bucketbreedte / de lengte van het bereik, in seconden | hetzelfde |
| `$__timeGroup(col[, iv])` | `FROM_UNIXTIME(FLOOR(UNIX_TIMESTAMP(col) / N) * N)` | `to_timestamp(floor(extract(epoch from col) / N) * N)` |
| `$__timeGroupAlias(col[, iv])` | ``… AS `time` `` | `… AS "time"` |

`iv` is `$__interval` (de standaard) of een duur zoals `30s`, `5m`, `1h`, `1d` of `1w`; een bucket die smaller is dan het min interval van het panel, wordt daarnaar verbreed. De kolom moet een gewone of tussen aanhalingstekens geplaatste kolomnaam zijn; een expressie wordt geweigerd. Een time-series-panel verwacht een eerste kolom met de naam `time`:

```
-- events per bucket (MariaDB or PostgreSQL alike)
SELECT $__timeGroupAlias(created_at, $__interval), count(*) AS events
FROM analytics_events
WHERE $__timeFilter(created_at)
GROUP BY 1 ORDER BY 1
```

```
-- top pages in the range, for a bar panel
SELECT path, count(*) AS hits
FROM analytics_events
WHERE $__timeFilter(created_at)
GROUP BY 1 ORDER BY 2 DESC LIMIT 10
```

## Variabelen

Een variabele is een keuzelijst (of een tekstvak) onder de bovenbalk. De waarde ervan gaat naar elk panel dat ernaar verwijst, en naar de URL (`?var-site=shop`). Er zijn drie soorten:

- **custom**: een vaste lijst van paren waarde/label;
- **query**: de eerste kolom van een query is de waarde, de tweede (als die er is) het label; de query mag de macro's en andere variabelen gebruiken;
- **textbox**: vrije tekst; met *validate: number* wordt alleen een getal geaccepteerd.

Verwijs naar een variabele als `${site}` of `$site`. De waarde wordt **altijd ingevoegd als complete stringliteral**, met aanhalingstekens voor de engine: schrijf `WHERE site = ${site}`, nooit `WHERE site = '${site}'`. Een meervoudige keuze wordt een kommagescheiden lijst van literals (`WHERE site IN (${site})`), "All" wordt elke optie, een lege keuze wordt `NULL`, en een tekstvak voor getallen voegt kale cijfers in. Er is geen ruwe modus: een waarde kan nooit de vorm van de query veranderen. Een variabele tussen aanhalingstekens, binnen een naam tussen aanhalingstekens of in commentaar wordt daarom bij het opslaan geweigerd, en een `custom`-variabele accepteert alleen de opties die jij opgaf. Om op een deel van een string te zoeken, bouw je die in SQL op: `CONCAT('%', ${q}, '%')` op MariaDB, `'%' || ${q} || '%'` op PostgreSQL.

## Wie wat ziet

Iedereen op het account ziet elk dashboard, ook kijkers en facturatiecontacten, want een panel draait met de rechten van degene die *zijn SQL het laatst bewerkte*, nooit met die van de kijker. Wie de database van het panel zelf niet zou kunnen bevragen, ziet de grafiek en de rijen, maar niet de SQL en niet de fouttekst van de engine, alleen "This panel's query failed". Eigenaren, beheerders en ontwikkelaars maken en bewerken dashboards (de maker kan zijn eigen dashboard altijd bewerken); de maker, of een eigenaar of beheerder, verwijdert er een. Kan degene die een panel het laatst bewerkte zijn database niet meer bevragen (bijvoorbeeld omdat hij het account heeft verlaten), dan stopt dat panel tot iemand met toegang het opnieuw bewerkt en opslaat.

## Cache en limieten

Elke panelquery wordt beantwoord uit de meest recente identieke run zolang die vers is: vijf mensen die naar hetzelfde dashboard kijken, of twee tabbladen van jou, delen één query per panel per verversing. De cache blijft geldig voor het interval van automatisch verversen of, als dat uitstaat, een paar minuten; handmatig verversen draait de query opnieuw. Relatieve bereiken worden afgerond op het verversinterval (op de minuut als automatisch verversen uitstaat), zodat identieke verzoeken ook echt identiek zijn.

Elk account heeft een maximum voor het aantal dashboards, voor panels en variabelen per dashboard, voor rijen per panel en punten per reeks (de automatische bucket houdt een reeks daaronder), en voor dashboardquery's die tegelijk draaien en per dag. Dashboardquery's worden apart van die van de SQL-editor geteld, zodat een druk dashboard de editor nooit blokkeert. Is het grootste deel van het dagbudget op, dan vertraagt de pagina het automatisch verversen tot er weer budget vrij is, en zegt hij hoe vaak hij nog ververst.

**Meer nodig?** De add-on **Data limits** verhoogt deze limieten: **Data limits Plus** (€5 per maand) geeft elk 2 keer zoveel, **Data limits Max** (€12 per maand) 5 keer, met een paar limieten begrensd zodat de gedeelde database snel blijft. Eigenaren en facturatiecontacten kiezen hem op [Settings → Plans](https://manage.veldhost.eu/portal/plans) onder **Data limits**, waar elke keuze alle limieten toont. De nieuwe limieten gelden meteen; kies je weer **Standard**, dan stopt de afschrijving en wordt niets weggehaald wat je al hebt. Houdt een limiet je tegen, dan zegt de melding dat en brengt **Raise limit** je daarheen. De add-on geldt voor dashboards, panels en variabelen per dashboard, en dashboardquery's tegelijk en per dag.

## Vanuit een script of je AI-assistent

Dashboards zitten in de [API](https://veldhost.eu/docs/api-reference) en de [MCP-server](https://veldhost.eu/docs/connect-ai-assistant), achter dezelfde opt-in-scope **`data`** als [Databases](https://veldhost.eu/docs/databases):

- `GET /api/v1/dashboards`, `POST /api/v1/dashboards`: opvragen en aanmaken (met panels en variabelen in één keer);
- `GET` / `PUT` / `DELETE /api/v1/dashboards/{uid}`: het volledige model (stuur de `version` terug die je las; een verouderde geeft een `409`);
- `POST /api/v1/dashboards/{uid}/panels`, `PUT` / `DELETE …/panels/{key}`: één panel tegelijk;
- `POST /api/v1/dashboards/{uid}/panels/{key}/data`: de rijen achter een panel voor een tijdbereik, uit dezelfde cache.

Een assistent krijgt `list_dashboards`, `get_dashboard`, `create_dashboard`, `update_dashboard`, `delete_dashboard`, `add_panel`, `update_panel`, `delete_panel` en `render_panel_data`. `update_dashboard` vervangt het hele dashboard, dus de assistent leest het eerst met `get_dashboard`; `update_panel` wijzigt maar één panel. Een token dat beperkt is tot bepaalde sites, ziet de SQL van een panel alleen als de database van het panel bij een van die sites hoort.

## Gerelateerd

- [Databases](https://veldhost.eu/docs/databases)
- [Warehouse](https://veldhost.eu/docs/warehouse)
- [Jobs & Pipelines](https://veldhost.eu/docs/pipelines-and-jobs)