Dashview Docs - Dashboard Views

Views: de SQL-laag tussen datasource en widget overzicht.

1. Wanneer views de juiste keuze zijn

Gebruik een view als je

meerdere datasources wilt combineren in één widgetbron;
kolomnamen wilt normaliseren voordat meerdere widgets ze gebruiken;
één berekening of filterlogica centraal wilt vastleggen;
een pagina eenvoudiger wilt maken door widgets op één uniforme dataset te laten werken.

Gebruik liever geen view als

één widget een heel kleine, unieke berekening nodig heeft;
de datavorming al correct in de bronquery of een custom datasource zit;
de pagina geen herbruikbare SQL-laag nodig heeft.

2. Workflow in de editor

Open een dashboardpagina in bewerkmodus.
Zet eventueel Geavanceerd aan in de topbar zodat de knop Views zichtbaar wordt.
Open de views-dialog.
Maak een nieuwe view aan of dupliceer een bestaande.
Vul identifier, naam, beschrijving en query in.
Bepaal of page filters en globale search naar de viewbronnen worden doorgegeven.
Selecteer bij Benodigde databronnen welke datasources de view nodig heeft. Bij oude views vult Dashview deze selectie automatisch op basis van de bestaande SQL wanneer je de editor opent.
Stel eventueel brondata-vensters in wanneer de view data buiten de actieve filterperiode nodig heeft, bijvoorbeeld voor vorige-periodevergelijkingen.
Sla de views op en laat widgets daarna de view gebruiken als bron.

De dialog seedt opnieuw als je hem opent, zodat je met de actuele paginaconfiguratie werkt.
Views zijn onderdeel van de pagina zelf; ze bestaan niet tenantbreed als los object.
Je kunt een view dupliceren om veilig te experimenteren met een variant.

3. Velden in een view

Veld	Betekenis
`uid`	Verplichte unieke identifier binnen de pagina. Widgets en interne selectors verwijzen hiernaar.
`name`	Leesbare naam voor editors en beheerders.
`description`	Documentatie voor jezelf en collega-beheerders.
`applyPageFilters`	Stuurt actuele page filters direct door naar de brontabellen waar de view naar verwijst.
`applySearchToSources`	Stuurt widget- of globale zoektermen ook door naar de tabellen achter deze view.
`sourceUids`	Expliciete lijst met datasource-uid's die de view nodig heeft. Nieuwe en bewerkte views moeten dit invullen; oude opgeslagen views zonder dit veld gebruiken nog SQL-detectie als fallback.
`dateRangeFilterKey`	Key van de paginadatumfilter die het actieve datumvenster voor deze view vertegenwoordigt. Dit hoeft geen bronkolom te zijn; als de filter `applyFields` gebruikt, volgen tijdgrafieken op de view die toegepaste velden voor autoscale en minimum-datarangegedrag.
`sourceDataWindows`	Optionele datumveldkoppelingen en extra bronbereik voor gepartitioneerde bronnen. Koppel de geselecteerde periode aan een brondatumveld of laad een vorige periode zonder SQL-placeholders te wijzigen.
`query`	De SQL-definitie van de view. Dit is verplicht.

Belangrijke editorregels

Lege identifiers blokkeren opslaan.
Dubbele identifiers blokkeren opslaan.
Lege query’s blokkeren opslaan.
Afsluitende puntkomma’s worden opgeschoond voordat de view wordt opgeslagen.

Beschrijving slim gebruiken

Leg kort uit welke bron of berekening de view bevat.
Noteer verwachte outputkolommen als widgets daar gevoelig voor zijn.
Gebruik de beschrijving om collega’s te waarschuwen voor filters of aannames.

Technische referentie: brondata-vensters

Gebruik sourceDataWindows wanneer een view zelf rekent met een periode buiten de actieve dashboardfilter, zoals huidige periode versus vorige periode. Dashview past het bronvenster toe voor het laden van partities en, bij ingeschakelde applyPageFilters, het filteren van bronrijen. SQL-placeholders blijven de originele paginafilterwaarden gebruiken.

{
  "uid": "billing_previous_period",
  "applyPageFilters": true,
  "applySearchToSources": true,
  "sourceUids": ["dashview-gcp-billing"],
  "dateRangeFilterKey": "usage_start_time",
  "sourceDataWindows": [
    {
      "sourceUid": "dashview-gcp-billing",
      "extendBefore": "activeRange",
      "extendAfter": ""
    }
  ],
  "query": "SELECT ... FROM dashview_gcp_billing ..."
}

sourceUids: expliciete datasource-afhankelijkheden van de view. Dit voorkomt dat Dashview CTE's of SQL-functies uit de query hoeft te interpreteren als bronnen.
sourceUid: datasource-uid of leeg voor alle bronnen in de view.
dateRangeFilterKey: key van de paginadatumfilter die tijdgrafieken op de view gebruiken en die als standaard geldt voor brondata-vensters. De key mag logisch zijn, bijvoorbeeld date; wanneer de filter applyFields heeft, gebruikt Dashview die toegepaste velden om de actieve From/To-range te vinden.
filterKey: optionele override per venster. Leeg betekent: gebruik dateRangeFilterKey, daarna de parquetPartitionColumn van de bron.
extendBefore: vergroot <filterKey>From naar achteren. Gebruik een positieve ISO-periode zoals P1M, P7D, of activeRange voor dezelfde daglengte als de actieve From/To-range.
extendAfter: vergroot <filterKey>To naar voren. Gebruik dezelfde waarden als bij extendBefore.
Tijd- en timeseriesgrafieken die aan een view gekoppeld zijn gebruiken dateRangeFilterKey plus eventuele applyFields van die paginfilter voor automatische tijdseenheden en minimum-datarangevergroting. Grafieken die direct aan een datasource gekoppeld zijn blijven de datasourcefilter gebruiken zoals voorheen.
Wanneer meerdere views dezelfde bron met compatibele datumvensters gebruiken, laadt Dashview een keer de grootste benodigde range.

Koppel de geselecteerde periode aan een brondatumveld

Stel Datumveld in bron in de view-editor in, of gebruik targetFilterKey, wanneer de paginafilter en de partitiekolom anders heten. Dit voorbeeld koppelt detected_atFrom/To aan event_timeFrom/To voor de logbron.

{
  "uid": "log_volume",
  "sourceUids": [
    "gcp_cloud_run_logs"
  ],
  "dateRangeFilterKey": "detected_at",
  "applyPageFilters": true,
  "sourceDataWindows": [
    {
      "sourceUid": "gcp_cloud_run_logs",
      "filterKey": "detected_at",
      "targetFilterKey": "event_time"
    }
  ],
  "query": "SELECT * FROM gcp_cloud_run_logs"
}

De koppeling kopieert From, To, Preset en ExclusiveEnd naar het doelveld voor die bron. Periode-uitbreidingen zijn optioneel en worden na de koppeling toegepast. Zonder targetFilterKey blijft het bestaande gedrag gelijk. SQL-placeholders worden niet herschreven en ontbrekende grenzen worden niet ingevuld. Gebruikt de paginafilter applyFields, stel filterKey dan in op het toegepaste veld met de datumgrenzen.

Beperk koppelingen met sourceUid, zodat andere bronnen, zoals triagehistorie voor de laatste status, hun bestaande datumgedrag behouden. Alle views die een logbron delen moeten een begrensde periode opvragen om volledige historie te vermijden. Zowel de frontendkoppeling als backendondersteuning voor partitieselectie moet zijn uitgerold. Recente ongepartitioneerde Uplink-batches en onbekende partities kunnen voor correcte resultaten nog steeds worden geladen.

4. SQL-model en bronnamen

Views werken met de tabellen die Dashview in de dashboardcontext beschikbaar maakt. Gebruik de gewone datasource- of view-id als tabelnaam; Dashview normaliseert die waar nodig naar een SQL-veilige lokale DuckDB-tabel.

Bronnamen

Datasource orders kun je direct gebruiken als FROM orders.
Speciale tekens worden intern genormaliseerd zodat de lokale DuckDB-naam SQL-veilig blijft.
Gebruik altijd expliciete aliassen als de query complexer wordt.

Filters en placeholders

Gebruik placeholders zoals @filters.country.
Voor ranges gebruik je meestal From- en To-varianten.
Voeg zelf geen extra quotes toe om onverwachte SQL te voorkomen.

SELECT
  o.invoice_date::DATE AS datum,
  o.country,
  o.status,
  o.total,
  c.segment
FROM orders o
LEFT JOIN customers c
  ON c.customer_id = o.customer_id
WHERE o.country = @filters.country
  AND o.invoice_date >= @filters.invoiceDateFrom
  AND o.invoice_date < @filters.invoiceDateTo

5. Patronen die in de praktijk goed werken

Voor meerdere widgets

Normaliseer datums, statusvelden en dimensies één keer in de view.
Laat daarna tabel-, KPI- en chartwidgets allemaal op dezelfde definitie werken.
Gebruik de view als centrale businessdefinitie voor de pagina.

Voor geavanceerde logica

Bereken ratio’s en samengestelde metrics in de view.
Gebruik joins om lookupdata of segmentatie toe te voegen.
Gebruik windowfuncties voor ranking of trends als meerdere widgets die logica delen.

6. Validatie, fouten en debugging

Probleem	Wat meestal de oorzaak is
Identifier is required	De `uid` ontbreekt.
Identifier must be unique	Een andere view gebruikt dezelfde identifier.
Query is required	De SQL is leeg of alleen witruimte.
Bron niet gevonden	De query verwijst naar een niet-beschikbare datasource- of viewnaam.
Widgetfouten na opslaan	De widget verwacht kolommen die de view niet meer teruggeeft.

Test een nieuwe view eerst met een simpele tabelwidget om kolommen en filters te controleren.
Houd kolomnamen stabiel zodra meerdere widgets of rapporten op dezelfde view leunen.
Gebruik dupliceren voordat je een bestaande, veelgebruikte view grondig wijzigt.

Views: de SQL-laag tussen datasource en widget