Datasources: complete documentatiehub

Schema-organisatie

• Datasource-schema's zijn tenant-scoped categorieën met een schema-ID en omschrijving.
• Het overzicht groepeert datasources onder hun schema en toont ook een groep voor datasources zonder schema.
• Een datasource bewaart de koppeling als schemaId. In DuckDB en data-worker-agent SQL kun je zo'n datasource ook als schemaId.datasourceId queryen, bijvoorbeeld SELECT * FROM finance.orders.
• Dashview houdt bestaande SQL compatibel: als er geen root-datasource met dezelfde tabelnaam bestaat, blijft de ongespecificeerde naam zoals orders als view-alias beschikbaar.
• Schema-definities worden via Git sync opgeslagen onder datasource-schemas/<schema-id>/resource.yaml. De koppeling van een datasource naar een schema blijft in het datasource-bestand staan als schemaId.
• Lege schema's blijven zichtbaar, zodat admins bronnen later naar zo'n schema kunnen verplaatsen.

Semantic contexts voor datasourcebetekenis

• Gebruik Semantic contexts om tenant-scoped begrippen, KPI's, synoniemen en toegestane relaties bij datasources vast te leggen.
• Koppel contexts met datasourceIds aan de bronnen die ze beschrijven, zodat zoekresultaten en Dashbot-context binnen datasource-access blijven.
• Bewaar hier geen rows, previews, row IDs, rowsRef of andere datapayloads. Voorbeelden zijn alleen gebruiksvoorbeelden; valideer echte output via schema-refresh en querytools.

Data Studio als voorportaal

• Data Studio gebruikt dezelfde tenant- en user-scope als datasourcebeheer en vereist datasource-management toegang.
• SQL-cellen previewen geselecteerde bronnen via QueryPreviewService, browser DuckDB of data-worker-agent.
• Promotievoorbereiding naar een custom datasource bewaart expliciete brondatasources; de reviewed draft/spec wordt pas via datasourcebeheer opgeslagen, gevalideerd en eventueel refreshed.

Flowdiagnose

• Gebruik de overzichtsfilter Geïnitieerd door om de flowcharts en datasourcetabel te beperken tot alle bronnen, parquetrefresh, frontend, backend, LLM en andere runtime-services.
• Open daarna de statistiekenactie op een datasource om recente flow-runs, duur, status en geneste traces te bekijken.
• Tijdens een actieve parquetrefresh werkt het overzicht status, totale tijd en de huidige stap automatisch bij. Laat het statistiekendetail open om de live tijdlijn te volgen voor voorbereiding, data ophalen/parquet schrijven, cachepublicatie, zoekindex en een eventueel incremental checkpoint.
• De realtime melding bevat alleen tenant- en datasource-routingmetadata. De tijdlijn en tracegegevens worden daarna opnieuw opgehaald via dezelfde datasource-management API en rechtencontrole als bij handmatig openen.
• Het statistiekendetail gebruikt dezelfde overzichtsfilter automatisch, zodat de flowlijst van één datasource dezelfde initiatorcontext houdt.
• De filter verandert alleen de geselecteerde tenant-datasourceweergave; rechten en forced filters blijven bepaald door de onderliggende runtime en tracegegevens.

Parquetrefresh incremental merge

• Zet Incremental parquet refresh aan op Parquet-datasources wanneer de bron een betrouwbare timestampkolom heeft.
• Kies een checkpointkolom en optioneel een lookback overlap om late rows nog mee te nemen.
• writeMode: "replace" publiceert alleen de delta van de laatste refresh.
• writeMode: "merge" leest eerst de huidige parquet-cache en schrijft daarna oud + nieuw samen weg als nieuwe immutable revisie.
• Voeg optioneel mergeKeys toe om merge keyed upsert/deduping te laten doen. Dashview houdt dan per sleutel één rij over en kiest normaal de nieuwste op basis van de incremental timestampkolom.
• Zonder mergeKeys blijft merge append-style en worden oude en nieuwe rijen alleen samengevoegd.
• Gebruik Checkpoint resetten wanneer een incrementele datasource opnieuw vanaf de reset checkpointstatus moet opbouwen. Dit wist alleen parquetrefresh-checkpoints; bestaande parquet-cachebestanden blijven staan totdat je daarna handmatig of gepland een parquet-refresh start.

Geplande parquet-refresh

• Parquet-datasources in refreshMode=cached kunnen een eigen parquet-refreshschedule krijgen in de datasource-editor.
• Gebruik dit wanneer de parquet-cache op vaste tijden moet vernieuwen zonder dat iemand handmatig op Parquet refresh klikt.
• Zet Parquet-refreshbeleid op Alleen handmatig voor statische bronnen. Dan bewaart Dashview parquetRefreshMode="manual", verwijdert eventuele schedule en slaat geplande, volledige tenant- en dependency-refreshes deze datasource over.
• De scheduler gebruikt daarvoor dezelfde parquetrefresh-job als de handmatige datasource-actie.
• De schedule-sectie ondersteunt tijdzone, frequentie en een cron-preview; voor gevorderde gevallen kun je ook een aangepaste cron opgeven.
• Geplande parquetrefresh is tenant-system materialisatie: interne services mogen een kortlevende tenant-system on-behalf-of context gebruiken om caches en Element/Dashbot/tool-afhankelijkheden binnen de tenant op te bouwen.
• Gegenereerde cache-artifacts geven geen gebruikersrechten. Latere retrieval van rows, signed URLs, rowsRef of Dashbot/tool-resultaten vereist opnieuw een geldige user- of on-behalf-of context en past actuele forced filters toe.
• Schakel deze instelling alleen in op bronnen waarvan gecachede parquet-output echt de gewenste runtime-modus is; JSON- of realtime-datasources horen hier niet thuis.

Parquetrefresh uitvoering en kosten

• Volledige tenant-refreshes plannen nog steeds één work item per datasource.
• De gedeployde parquetrefresh-workerpool heeft normaal een cap, waardoor een grotere tenant-refresh alsnog met minder worker-tasks dan datasources kan draaien.
• Die cap beperkt herhaalde Cloud Run-startup overhead en verlaagt de druk op connectors, databases en BigQuery tijdens brede tenant-refreshes.
• Verhoog de worker-cap alleen wanneer kortere doorlooptijd belangrijker is dan de totale refresh-kosten.

File datasources

• Gebruik connector type file wanneer de bron letterlijk uit tenant-scoped GCS-bestanden moet bestaan in plaats van uit BigQuery, SQL of een API.
• Je kunt dezelfde single-file formaten ook met de paperclip in Dashbot uploaden. Met datasourcebeheer en Dashbot-bewerkrechten kan Dashbot het bestand als datasource opslaan, het schema en voorbeelddata inspecteren en daarna een dashboard met widgets maken.
• De editor toont een file browser voor dashview-cache/filestore/{tenantId}. Je kunt mappen openen of maken, bestanden uploaden, bestanden/mappen verwijderen, en één of meer bestanden als datasource-parts selecteren.
• De opgeslagen datasource geeft de selectie aan data-worker-agent door als uri of uris. files bevat alleen aanvullende UI-metadata zoals naam, gcsUri, httpUrl, rawHttpUrl, bucket, pad en grootte.
• Ondersteund zijn in ieder geval CSV, TSV, pipe-separated, JSON, NDJSON/JSONL, parquet, logfmt, Apache common/combined logs, Nginx access logs, syslog/RFC3164/RFC5424, CEF, LEEF, Windows Event XML, platte tekstregels, XLSX/XLSM, Avro, SQLite en gzip-varianten waar de parser die ondersteunt.
• Met fileFormat = auto gebruikt Dashview extensie + contentsniffing; zet een expliciete parser als de bestandsnaam misleidend is.
• In recordsPath kun je bij JSON aangeven waar de rij-array zit. Met includeFileMetadataColumns voeg je helperkolommen toe zoals __file_id, __file_name, __file_path en __file_format.
• Gebruik de query-editor in de file-sectie om de geselecteerde bestanden direct te testen. De preview laadt de geselecteerde uris via data-worker-agent als DuckDB-tabel files, bijvoorbeeld SELECT * FROM files LIMIT 100.
• Wanneer je meerdere bestanden selecteert, combineert Dashview alle rijen in één datasource-resultaat. Het gedrag is dus vergelijkbaar met UNION ALL, niet met aparte tabellen per bestand.
• Kolommen worden samengevoegd over die gecombineerde rijen. Bestanden hoeven dus niet exact dezelfde kolommen te hebben, maar het is wel verstandiger wanneer gedeelde velden ook echt dezelfde betekenis en parserinstellingen hebben.
• Praktisch voorbeeld: een eerste bestand met Locatie/Omzet en een tweede bestand met Klant/Omzet levert één datasource op waarin sommige rijen alleen locatievelden hebben en andere rijen alleen klantvelden.
• Gebruik Refresh schema opnieuw nadat je de geselecteerde bestanden wijzigt of onderliggende bestanden vervangt. De schemaweergave is gebaseerd op de actuele geselecteerde uris.
• Gebruik daarna Parquet refresh wanneer dashboards of query console op de parquet-cache moeten werken met de nieuwste geselecteerde bestanden.
• Deze datasource gedraagt zich verder als elke andere datasource: widgets, query console, parquetrefresh en forced filters blijven gewoon gelden.
• Let op bij CSV-achtige bestanden: auto-detect probeert delimiter en formaat te herkennen, maar een expliciete delimiter of parser is veiliger wanneer je mixen hebt zoals puntkomma-CSV naast komma-CSV.

Directe Element-datasources

• Gepubliceerde Elements met kind data of stream_data zijn direct bruikbaar in dashboards zonder eerst een aparte datasource aan te maken.
• Gebruik dit voor snelle herbruikbare dashboardbronnen uit Python.
• Maak alsnog een expliciete datasource aan wanneer je extra connectorconfig, scheduling, parquet-refresh of andere datasource-specifieke instellingen nodig hebt.

Virtual datasources

• Een virtual datasource is een datasource van type virtual met alleen SQL en expliciete afhankelijkheden.
• Gebruik dit voor herbruikbare SQL-views zoals active_orders, tenant_revenue of open_incidents_with_customer die in dashboards en page views als normale datasource gekozen moeten kunnen worden.
• De SQL moet een read-only SELECT of WITH-query zijn. Dashview bewaart die in virtualSql.
• Selecteer altijd Onderliggende datasources. Dashview gebruikt sourceDataSourceIds om te bepalen welke bronnen geladen worden voordat de virtual query draait.
• Afhankelijkheden mogen normale datasources of andere virtual datasources zijn. Recursieve/cyclische afhankelijkheden worden geweigerd.
• Virtual datasources hebben geen eigen connector, bestandsselectie, live stream of parquet-refreshschedule. Ze worden runtime als DuckDB-view boven hun bronnen uitgevoerd.
• Bronrechten en forced filters blijven gelden per onderliggende datasource; een virtual datasource mag geen tenant- of gebruikersscope omzeilen.

{
  "id": "active_orders",
  "name": "Active Orders",
  "type": "virtual",
  "dataFormat": "virtual",
  "refreshMode": "cached",
  "sourceDataSourceIds": ["orders"],
  "virtualSql": "SELECT * FROM orders WHERE status = 'active'"
}

Custom datasources

• Een custom datasource is een normale datasource-doc van type custom met een herbruikbare SQL-query boven andere datasources.
• Schrijf de DuckDB-SQL in de SQL-editor en gebruik Query uitvoeren om het resultaat via data-worker-agent te bekijken voordat je opslaat.
• Gebruik Onderliggende datasources om expliciet te selecteren welke bronnen de query gebruikt. Die lijst stuurt de editor-preview, data-worker-agent source loading en de refresh-volgorde van parquet-refresh.
• De queryconsole-actie in het datasource-overzicht gebruikt hetzelfde data-worker-agent previewpad met die datasource voorgeselecteerd.
• De normale handmatige parquet-refreshactie ververst bij custom datasources eerst de onderliggende refreshbare bronnen en daarna de custom datasource zelf.
• Onderliggende datasources met parquetRefreshMode="manual" worden daarbij niet opnieuw ververst; de custom datasource gebruikt dan de bestaande parquet-cache van die statische bron.
• Gebruik de aparte actie Alleen deze custom datasource refreshen wanneer de onderliggende parquet-caches al goed zijn en je alleen het custom-resultaat opnieuw wilt materialiseren.
• Custom datasources gedragen zich verder als gewone datasources in widgets, filters, query console en parquet-refresh.
• Runtime-uitvoering loopt via dezelfde backend-querylaag als andere datasource-calls. Je hoeft dus geen aparte publicatie- of deploymentstap te doen om een custom datasource bruikbaar te maken.
• Bronrechten blijven gelden per onderliggende datasource. Een custom datasource mag dus nooit tenantscope, gebruikersrechten of forced filters omzeilen.

Technische referentie custom datasource

Een custom datasource wordt opgeslagen als datasource-payload met type="custom", customSql en expliciete sourceDataSourceIds.

Voorbeeld

{
  "id": "sales_summary",
  "name": "Sales Summary",
  "type": "custom",
  "dataFormat": "parquet-remote",
  "refreshMode": "cached",
  "sourceDataSourceIds": ["orders"],
  "customSql": "SELECT country, SUM(amount) AS total_amount FROM orders GROUP BY country",
  "customSqlGenerated": "SELECT country, SUM(amount) AS total_amount FROM orders GROUP BY country"
}

• Gebruik datasource-id's als tabelnamen in customSql. Voor schema-datasources kun je ook schemaId.datasourceId gebruiken.
• Houd sourceDataSourceIds gelijk aan de bronnen die de query gebruikt.
• Veelvoorkomende ongeldige payloads zijn lege custom SQL, ontbrekende sourceDataSourceIds en dataFormat="parquet-snapshot" voor datasources die door parquetrefresh gecached moeten worden. SQL-syntax en ondersteunde SQL worden door de browser-preview, data-worker-agent preview en runtime-uitvoering gevalideerd.

Backend- en MCP-workflow

• Gebruik POST /data-sources of PUT /data-sources/{id} om de uiteindelijke datasource-payload op te slaan.
• Via Dashview MCP gebruik je eerst get_entity_contract("datasource"), daarna create_datasource of update_datasource, en vervolgens run_datasource_query om output te verifiëren.

Flow trace visualisatie

• In de datasource-admin statsdialoog kan iedere flow-run nu naast de platte eventtabel ook een visuele flow trace openen.
• Gebruik deze weergave wanneer je de volledige runtimeketen wilt begrijpen: trigger, backend-hop, connector/source-call, data-worker-agent querystap, Element-executie, parquetrefresh-werk en returntransport.
• De modus Runtime toont de echte geneste call-tree van één geselecteerde flow-run, inclusief retries, child-datasources, duur, status en transportlabels.
• De modus Afhankelijkheden reduceert diezelfde trace tot datasource-naar-datasource relaties zodat je snel ziet welke onderliggende bronnen meedraaiden.
• Deze view is flow-specifiek en geen tenantbreed overzicht. Begin dus altijd vanuit één datasource en één geselecteerde flow-run.
• Geneste calls blijven tenant-scoped en respecteren nog steeds datasource-rechten, user rights en forced filters; de chart is observability, geen omweg rond access control.
• Datasource-stats en flow-trace details worden in Firestore onder tenants/{tenantId}/runtimeLogs/{dataSourceId} bewaard en via Firestore TTL op expireAt opgeschoond; ze worden niet meer als losse GCS-detailbestanden geschreven.
• Gebruik de chart samen met de trace-tabel: de tabel is beter voor exacte timings en row counts, terwijl de visuele graph beter is om parent/child-structuur te begrijpen.