Het basis‑notebook bestaat uit vier cellen, die elk een eigen taak uitvoeren. Je kunt een cel afzonderlijk uitvoeren via de knop Run cell vóór de cel, of alle cellen achter elkaar uitvoeren met Run all bovenaan het notebook.
Voordat we de cellen kunnen uitvoeren, moeten ze eerst worden aangepast aan jouw eigen configuratie.
1. Installeren Fabric Connector
In de eerste cel wordt de Fabric Connector geïnstalleerd in de actieve Spark‑sessie met het commando %pip install. Vervolgens wordt de connector geïmporteerd zodat deze in de daaropvolgende cellen gebruikt kan worden.
Het %pip install‑commando wordt in Fabric alleen ondersteund wanneer het notebook handmatig wordt uitgevoerd. Als je het notebook gepland (scheduled) wilt laten draaien, moet je hiervoor een Environment aanmaken waarin de benodigde packages zijn opgenomen. Zie hiervoor de uitleg in hoofdstuk 2.5 Instellen refresh.
2. Initialiseren nieuwe run
In de tweede cel initialiseren we een nieuwe run. Vul in deze cel eerst de connectorkey in die je gekopieerd hebt vanuit PowerBIConnector.nl (zie hoofdstuk 1.2 Account)
In een run kun je één of meerdere tabellen uit Twinfield inlezen. Elke tabel kan maar 1 keer per run worden ingelezen. Als je dezelfde tabel opnieuw wilt inlezen, dan moet deze tweede cel eerst opnieuw uitgevoerd worden om een nieuwe run te initialiseren.
Advies: laat de connectorkey niet rechtstreeks in de code staan, maar gebruik Azure Keyvault voor het veilig opslaan van keys. Zie 2.6 Tips Fabric voor meer uitleg hierover.
3. Importeren data
In de derde cel wordt de data ingelezen vanuit Twinfield en opgeslagen in het Fabric Lakehouse.
Parameters
Er zijn 2 verplichte parameters:
- administratiecode: vul hier de administratiecodes (zie hoofdstuk Bedrijven) in van de bedrijven die je wilt inlezen. Bijvoorbeeld “40000” voor 1 bedrijf of “40000,40001,40002” voor meerdere bedrijven. In plaats van de specifieke administratiecodes kun je ook “all” gebruiken voor alle bedrijven en “tag:klantgroep1” of “tag:klantgroep1,klantgroep2” voor alle bedrijven met deze tag(s).
- aantaljaren: vul hier het aantal jaren in dat je wilt inlezen. Bijvoorbeeld in 2026 betekent 3 jaar dat je de jaren 2024 t/m 2026 inleest.) De default waarde als je dit veld leeg laat is 1 jaar.
De parameter ‘aantaljaren’ werkt verschillend per ‘refresh type’ van een tabel.
Bij de incrementele tabellen (zie overzicht):
- Eerste refresh: vul het aantal jaren in waarvan je de historie wilt inlezen. De data wordt geladen op basis van de wijzigingsdatum van een record. Als er in Exact Online data wordt toegevoegd met een datum ver in de toekomst, dan kan het verstandig zijn om hier een extra jaar in te lezen zodat deze records worden meegenomen.
- Volgende refresh: alleen wijzigingen sinds de vorige refresh worden opgehaald. De parameter ‘aantaljaren’ heeft dan geen functie meer.
Bij de full-refresh tabellen (zie overzicht):
- Eerste refresh: vul het aantal jaren in waarvan je de historie wilt inlezen. De data wordt altijd geladen op basis van de transactiedatum van een record (niet afhankelijk van de wijzigingsdatum).
- Volgende refresh: meestal volstaat 1 jaar, zodat alleen nieuwe en gewijzigde records van dit jaar worden opgehaald. Oudere jaren blijven beschikbaar in het lakehouse. Als data van het vorige jaar nog kan wijzigen, kies tijdelijk voor 2 jaar totdat het vorige jaar is afgesloten.
Belangrijk: zorg ervoor dat je alleen bij de eerste refresh het aantal jaren invult waarvan je de historie wilt inlezen.
Bij volgende refreshes zet je het aantal jaren altijd op 1 of 2, zodat niet elke keer de volledige historie opnieuw wordt ingelezen!
Tabellen
Vervolgens kun je de tabellen invullen die je met deze notebook wilt inlezen. De waarden voor de parameters worden opgehaald uit de definitie boven in deze cel, zodat je die maar 1 keer hoeft in te vullen. In het basis-notebook zijn enkele tabellen als voorbeeld opgenomen:
Twinfield.Administraties(administratiecode=administratiecode,aantaljaren=aantaljaren)
Twinfield.Kalender(administratiecode=administratiecode,aantaljaren=aantaljaren)
Twinfield.Grootboek(administratiecode=administratiecode,aantaljaren=aantaljaren)
Twinfield.GrootboekMutaties(administratiecode=administratiecode,aantaljaren=aantaljaren)
- Maak een eerste notebook voor de full‑refresh tabellen en ververs deze 1× per dag.
- Maak een tweede notebook voor de incrementele tabellen, die je meerdere keren per dag kunt verversen.
- Maak een derde notebook voor weinig veranderende data, die je 1× per week of maand ververst.
Alle notebooks kunnen worden gekoppeld aan hetzelfde Lakehouse. Op deze manier blijft je data actueel, met de kortste refreshtijden en de laagste Fabric kosten.
Schema’s
Nadat de data is ingelezen verschijnen de tabellen in het lakehouse. Meestal moet je de tabellen even refreshen om de nieuw toegevoegde tabellen te zien.
In het lakehouse worden 2 schema’s gebruikt, het default-schema ‘dbo’ en een tweede schema ‘staging’. In Power BI gebruik je alleen de tabellen in het schema ‘dbo’. De tabellen in het schema ‘staging’ heeft de Fabric Connector nodig om de tabellen in het schema ‘dbo’ samen te stellen.
Optionele parameters
Verder zijn er nog 5 optionele parameters, deze zijn alleen nodig voor specifieke situaties:
- table=”aangepaste_tabelnaam”. De tabellen worden door de connector zelf aangemaakt. Als je bijvoorbeeld de tabel Grootboek inleest, dan maakt de connector in het lakehouse een tabel aan met de naam “Grootboek”. Met deze parameter kun je een aangepaste tabelnaam gebruiken in het lakehouse.
- regime=”Fiscaal”. In Twinfield wordt gewerkt met de regimes Generiek, Fiscaal, Commercieel of Economisch. In de tabel GrootboekMutaties worden standaard de mutaties van het regime Generiek ingelezen. Wil je een andere regime inlezen dan gebruik je bijvoorbeeld:
Twinfield.GrootboekMutaties(administratiecode=administratiecode,aantaljaren=aantaljaren,regime="Fiscaal") - importmode=”batch” of importmode=”percompany”:
- importmode=”batch” (default). De standaard werkwijze bij de import van meerdere bedrijven is dat eerst alle data wordt opgehaald en dit vervolgens in 1 batch in het lakehouse wordt opgeslagen. Dit is de meest kosten-efficiënte werkwijze voor Fabric.
- importmode=”percompany”. Bij erg grote tabellen (meer dan 1 miljoen regels) kan dit meer geheugen vragen dan in de Fabric SKU beschikbaar is. Meestal alleen bij de eerste run als alle data wordt ingelezen, want bij de volgende runs worden alleen de wijzigingen incrementeel geladen. Als je bij de eerste import tegen een geheugenlimiet aanloopt kun je importmode=”percompany” gebruiken. De data wordt dan per bedrijf opgeslagen in het lakehouse. Het advies is om na de eerste import deze parameter weer weg te halen, om te besparen op Fabric kosten.
- forcefullrefresh=True. Bij de incrementele tabellen wordt bij elke run alleen de nieuwe, gewijzigde en verwijderde data ingelezen. Soms kan er een reden zijn dat je een volledige refresh wilt forceren. Daarvoor kun je forcefullrefresh=True gebruiken. Let op dat je deze parameter daarna weer weghaalt om overmatig dataverbruik te voorkomen!
- forcehistory=”2023-2024″. Bij de incrementele tabellen wordt bij elke run alleen de data ingelezen die na de laatste refresh zijn toegevoegd, gewijzigd of verwijderd. Soms kan er een reden zijn dat je voor een bepaald jaar een volledige refresh wilt forceren. Of je hebt in eerste instantie alleen 2025 en 2026 ingelezen, maar wilt nu 2023 en 2024 nog toevoegen. Daarvoor kun je forcehistory=”2023-2024″ gebruiken. Let op dat je deze parameter daarna weer weghaalt om overmatig dataverbruik te voorkomen!
4. Stoppen sessie
In de vierde cel wordt het SQL Endpoint van het Fabric Lakehouse bijgewerkt, zodat de data direct via het SQL Endpoint in Power BI beschikbaar is. Zonder deze actie kan dat een paar minuten duren.
Tot slot wordt de Spark sessie gestopt, zodat de Fabric kosten niet doorlopen.