Wanneer gebruik je Datasources, Elements of allebei?

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.

2. Veelgebruikte patronen

3. Catalogus-Elements: veel tabellen, één integratie

Gebruik kind="catalog" wanneer één externe verbinding, bijvoorbeeld MySQL, meerdere schema's en tabellen moet aanbieden. Publiceer het Element één keer. Kies daarna bij een datasource van type catalog het Element, de versie, het ontdekte schema en de ontdekte tabel. Je hoeft dus geen apart Element per tabel te onderhouden; meerdere datasourcebindings kunnen hetzelfde Element hergebruiken.

@entrypoint
def getSchemas(params=None):
    return [{"name": "sales"}]

@entrypoint
def getTables(params=None):
    return [{"name": "orders", "schema": params["schema"]}]

@entrypoint
def getColumns(params=None):
    return [{"name": "order_id", "type": "BIGINT", "nullable": False}]

@entrypoint
def runQuery(params=None):
    # Valideer schema/table tegen provider-metadata en voer een begrensde read-only query uit.
    return [{"order_id": 42, "tenant_id": "tenant-a"}]

4. Aanbevolen werkvolgorde

1. Bepaal eerst welk deel centraal herbruikbaar moet zijn voor de tenant. Dat hoort meestal in een datasource of Element, niet in een losse widget.
2. Start met de data-ingang: connector, query, request of bestand.
3. Kies bij eindige Python-bronnen of een direct gepubliceerd data-Element volstaat, of dat je een expliciete datasource nodig hebt voor scheduling, parquet of extra connectorinstellingen. Gebruik voor meerdere externe tabellen één catalog-Element met afzonderlijke schema/tabel-bindings. Een stream_data-Element heeft altijd een expliciete livestream-datasource nodig.
4. 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.
5. Selecteer altijd expliciet de onderliggende datasources. Die lijst stuurt zowel data-worker-agent source loading als de refresh-volgorde van parquet-refresh.
6. Houd de query begrijpelijk: begin met een paar bronnen, test tussendoor en controleer daarna de output in een eenvoudige widget.
7. Voeg pas daarna Python toe als je logica nodig hebt die met gewone SQL, widgetopties of filterregels niet netjes oplosbaar is.
8. Test de output in een eenvoudige widget voordat je de bron inzet in Dashbot, Autoflow of een complex dashboard.
9. Documenteer voor jezelf welke filters, runtime-variabelen en rechten de oplossing verwacht, zodat collega’s ze veilig kunnen hergebruiken.

5. 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.