Patroon A: standaard dashboardbron
Maak eerst een datasource, refresh het schema, stel kolommetadata in en gebruik die bron daarna direct in widgets en filters.
Keuzehulp
Wanneer gebruik je Datasources, Elements of allebei?
Deze pagina is de brug tussen de datasource-documentatie en de element-documentatie. Gebruik haar als snelle besliswijzer wanneer je weet dat je iets met data wilt doen, maar nog niet zeker weet of dat in een connector, custom SQL, een Element-widget of een automationstap thuishoort.
1. Snelle keuze
Het belangrijkste onderscheid is eenvoudig: een datasource haalt of modelleert data op tenantniveau; een Element voert Python-logica uit. In de praktijk combineer je ze vaak.
| Je doel | Beste startpunt | Waarom |
|---|---|---|
| Rijen ophalen uit een database, API of bestand | Datasource | Connectors zijn bedoeld voor stabiele data-ingang, schema-refresh en hergebruik in widgets, Dashbot en Autoflow. |
| Een gepubliceerde Python-bron direct in dashboards gebruiken | Element van type data of stream_data | Gepubliceerde data-Elements verschijnen direct als datasource in widgets, filters en query console. |
| Bestaande datasources joinen, mergen of omvormen met SQL | Custom datasource | Je publiceert één tenantbrede bron met een read-only SQL-query boven expliciet geselecteerde onderliggende datasources. |
| Data verrijken of opschonen met Python | Element met datasource helpers | Je leest expliciete bronnen via data-worker-agent en retourneert of bewaart het opgeschoonde resultaat bewust. |
| Een volledig nieuwe widget uit Python teruggeven | Element widget | Geschikt voor dynamische visualisatie of samengestelde output die niet goed past in standaard widgetopties. |
| Herbruikbare runtime-logica bouwen voor meerdere plekken | Element | Elements kun je publiceren, testen en later inzetten in datasources, widgets en automations. |
| Een terugkerende operationele flow bouwen | Autoflow | Autoflow orkestreert datasources, Elements, Dashbot en acties in één uitvoerbare workflow. |
2. Veelgebruikte patronen
Patroon A2: direct gepubliceerd data-Element
Publiceer een Element van type data of stream_data en gebruik het daarna direct als datasource in dashboards zonder extra datasource-doc.
Patroon A3: custom datasource
Maak een SQL-query boven geselecteerde dependency-datasources wanneer je vooral joins, filters, casts, unions of aggregaties nodig hebt en die als één herbruikbare bron wilt publiceren. Gebruik de inline query-preview tijdens het bewerken om de query met dezelfde geselecteerde bronnen via data-worker-agent uit te voeren.
Patroon B: Element met datasource helpers
Gebruik een Element wanneer Python nodig is voor businesslogica, mapping of verrijking. Lees expliciete datasources met de worker helpers en retourneer rows, schrijf een file of append naar een uplink/parquet-backed datasource.
Patroon C: Python-gestuurde widget
Laat een Element een complete widgetconfig retourneren wanneer de visualisatie zelf dynamisch of conditioneel is.
Patroon D: automation met data en Python
Autoflow haalt data uit een datasource, laat een Element of Dashbot die interpreteren en stuurt daarna notificaties of taken.
3. Aanbevolen werkvolgorde
- Bepaal eerst welk deel centraal herbruikbaar moet zijn voor de tenant. Dat hoort meestal in een datasource of Element, niet in een losse widget.
- Start met de data-ingang: connector, query, request of bestand.
- Kies bij pure Python-bronnen of je direct een gepubliceerd data-Element wilt gebruiken, of toch een expliciete datasource nodig hebt voor scheduling, parquet of extra connectorinstellingen.
- Kies een custom datasource wanneer de data al in andere datasources bestaat en je combinaties, joins, casts, filters of aggregaties met SQL wilt modelleren zonder eerst Python te schrijven.
- Selecteer altijd expliciet de onderliggende datasources. Die lijst stuurt zowel data-worker-agent source loading als de refresh-volgorde van parquet-refresh.
- Houd de query begrijpelijk: begin met een paar bronnen, test tussendoor en controleer daarna de output in een eenvoudige widget.
- Voeg pas daarna Python toe als je logica nodig hebt die met gewone SQL, widgetopties of filterregels niet netjes oplosbaar is.
- Test de output in een eenvoudige widget voordat je de bron inzet in Dashbot, Autoflow of een complex dashboard.
- Documenteer voor jezelf welke filters, runtime-variabelen en rechten de oplossing verwacht, zodat collega’s ze veilig kunnen hergebruiken.
4. Valkuilen om te vermijden
- Bouw geen tenantkritische businesslogica alleen in een losse dashboardwidget wanneer diezelfde logica later ook nodig is in Dashbot of Autoflow.
- Gebruik geen Element-widget als een normale chart, tabel of KPI al voldoende is. Houd de oplossing zo eenvoudig mogelijk.
- Gebruik geen custom datasource om tenantrechten, gebruikersrechten of forced filters te omzeilen. De onderliggende datasource-scope blijft altijd leidend.
- Bouw geen custom datasource wanneer een enkele connectorquery of een bestaande datasource al voldoende is. Houd de keten zo kort mogelijk.
- Zorg dat filters tenant- en gebruiksscope respecteren. Forced filters en datasource-whitelists mogen nooit omzeild worden.
- Stop secrets niet in widget-JSON of datasourcebeschrijvingen. Gebruik daarvoor de runtime store.
Vuistregel: zet connector- en schedulinggedrag in datasources, gebruik custom datasources voor herbruikbare SQL boven bestaande bronnen, zet herbruikbare Python in Elements, en gebruik gepubliceerde data-Elements direct als datasource wanneer je geen extra datasourceconfig nodig hebt.