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 query-engine 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 query-engine.
• 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.
• 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.

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.
• 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.
• 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 geuploade bestanden moet bestaan in plaats van uit BigQuery, SQL of een API.
• De uploadsectie slaat tenant-scoped bestanden op in GCS bucket dashview-datafiles en bewaart alleen metadata in de datasource-doc.
• Ondersteund zijn in ieder geval CSV, TSV, pipe-separated, JSON, NDJSON/JSONL, parquet, logfmt, Apache common/combined logs, platte tekstregels en gzip-varianten daarvan.
• 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.
• Wanneer je meerdere bestanden uploadt, 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 bestanden toevoegt, vervangt of verwijdert. De schemaweergave is gebaseerd op de actuele uploadset.
• Gebruik daarna Parquet refresh wanneer dashboards of query console op de parquet-cache moeten werken met de nieuwste uploadset.
• 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, uploadset, 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",
  "requestParamsMode": "none",
  "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 te bekijken voordat je opslaat. De preview kan draaien in de browser-DuckDB-worker of via query-engine.
• Gebruik Onderliggende datasources om expliciet te selecteren welke bronnen de query gebruikt. Die lijst stuurt de editor-preview, query-engine en de refresh-volgorde van parquet-refresh.
• De dashboard Query Console gebruikt hetzelfde principe: selecteer de datasources die geladen moeten worden en kies daarna of de query lokaal in frontend DuckDB of via query-engine draait.
• De normale handmatige parquet-refreshactie ververst bij custom datasources eerst de onderliggende refreshbare bronnen en daarna de custom datasource zelf.
• 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": "realtime",
  "requestParamsMode": "filters",
  "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, query-engine-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-call, query-engine stap, 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.
• 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.