Datasets Handleiding

Configureren van databronnen voor API's en webhooks

Wat is een Dataset?

Een dataset is de basis van SQLio. Het bepaalt welke data uit je database beschikbaar wordt gesteld aan API endpoints en webhooks. Je definieert één keer welke tabellen, views of stored procedures je wilt gebruiken, welke velden je wilt tonen en hoe je de data wilt filteren. Daarna kun je diezelfde dataset hergebruiken bij meerdere API's en webhooks.

Een dataset levert altijd JSON op. De structuur van die JSON bepaal je zelf door middel van layers (lagen). Hiermee kun je eenvoudige platte lijsten maken, maar ook complexe geneste structuren met hoofd- en detailgegevens.

Dataset aanmaken

Stap 1: Navigeer naar Dataset Configuratie

Klik in het menu op Dataset Configuratie. Je ziet een overzicht van alle bestaande datasets.

Stap 2: Klik op "Nieuw"

Bovenaan verschijnt een formulier met de volgende velden:

Stap 3: Opslaan

Klik op Opslaan. De dataset is nu aangemaakt, maar bevat nog geen data-configuratie. Daarvoor moet je een layer toevoegen.

Bij elke keer opslaan vraagt SQLio om een versie en een korte notitie; zie Versioning.

Databronnen: één dataset, meerdere databases

In de kaart Geldig voor databronnen vink je aan op welke connectie-aliassen de dataset mag draaien. De ster markeert de databron waartegen je de dataset bouwt en test. Vink je een tweede alias aan, bijvoorbeeld de Belgische vestiging be, dan draait dezelfde definitie ook op die database, mits de tabellen en velden daar hetzelfde heten.

De koppeling ligt op de alias, niet op de database. Synchroniseer je de dataset naar productie, dan blijft de lijst gelden: nl wijst daar naar de productiedatabase van de Nederlandse vestiging. Zie de handleiding Omgevingen & aliassen.

Layers: de bouwstenen van je dataset

Wat is een layer?

Een layer is één databron binnen je dataset. Elke layer verwijst naar een tabel, view of stored procedure en bepaalt welke velden daaruit worden opgehaald. Layers kunnen hiërarchisch worden opgebouwd: een root layer (hoofdlaag) met daaronder één of meer child layers (sublagen).

Hiërarchie voorbeeld

Dataset: "Order overzicht"
├── Root Layer: Orders (tabel)
│   ├── Child Layer: Orderregels (tabel)
│   └── Child Layer: Klantgegevens (tabel)

Dit levert de volgende JSON structuur op:

{
  "orderId": 100,
  "orderDate": "2024-01-15",
  "orderregels": [
    { "artikelNr": "A001", "aantal": 5, "prijs": 12.50 },
    { "artikelNr": "A002", "aantal": 2, "prijs": 8.00 }
  ],
  "klant": {
    "naam": "ACME Corp",
    "stad": "Amsterdam"
  }
}

Root layer toevoegen

Klik op Root Layer Toevoegen in de "Layer Structuur" kaart. Er verschijnt een formulier.

Child layer toevoegen

Klik op het + icoon naast een bestaande layer. De child layer wordt automatisch gekoppeld aan de gekozen parent layer.

Layer configureren

Basisinstellingen

Bron Type: Table of View

Als je Table of View kiest, verschijnen extra velden:

Bron Type: Stored Procedure

Als je Stored Procedure kiest, verschijnt een tekstveld voor het Execution Statement:

EXEC dbo.sp_GetOrders
    @CustomerId = :CustomerId,
    @FromDate = :FromDate,
    @IncludeInactive = 0

Output Types

Het output type bepaalt hoe de data van een layer in de JSON verschijnt:

Object

De layer levert één record op als JSON object met een eigen sleutel.

{
  "klant": {
    "naam": "ACME Corp",
    "stad": "Amsterdam"
  }
}

Gebruik voor: detailgegevens, enkele opzoekwaarden.

Array

De layer levert meerdere records op als JSON array met een eigen sleutel.

{
  "orderregels": [
    { "artikelNr": "A001", "aantal": 5 },
    { "artikelNr": "A002", "aantal": 2 }
  ]
}

Gebruik voor: lijsten van gerelateerde items (orderregels, factuurregels, etc.).

Merge

De velden van de layer worden samengevoegd met de parent layer. Er komt geen aparte sleutel in de JSON.

{
  "orderId": 100,
  "orderDate": "2024-01-15",
  "telefoon": "020-1234567",
  "email": "info@acme.nl"
}

In dit voorbeeld komen telefoon en email uit een child layer met output type Merge. Ze verschijnen alsof ze bij de parent horen.

Gebruik voor: extra kolommen uit een andere tabel toevoegen aan de parent, zonder nesting.

Veld selectie

Na het kiezen van een tabel of view verschijnt de Veld Selectie kaart. Hier zie je alle beschikbare kolommen.

Kolommen in de veld selectie tabel

Velden hernoemen (aliassen)

Je kunt de Output Naam aanpassen om database-kolomnamen te vertalen naar leesbare JSON-veldnamen:

Filters en condities

WHERE-condities (root layers — Table/View)

Bij root layers op basis van een tabel of view kun je WHERE-condities toevoegen om de data te filteren. Klik op Conditie toevoegen.

Elke conditie-regel heeft de volgende opties:

Voorbeeld: filteren op klantnummer (dynamisch)

Als iemand de API aanroept met parameter klantnummer=K001, wordt de query:

SELECT ... FROM Customers WHERE CustId = 'K001'

Voorbeeld: vaste filter

Dit filter wordt altijd toegepast — de aanroeper kan het niet wijzigen.

JOIN-condities (child layers — Table/View)

Bij child layers op basis van een tabel of view definieer je hoe de child aan de parent gekoppeld wordt. Dit werkt als een JOIN in SQL.

Voorbeeld

Een child layer "Orderregels" gekoppeld aan parent layer "Orders":

SQLio voert dan voor elke order-rij een query uit op de orderregels waar Orderregels.OrderId = Orders.OrderId.

Stored Procedure parameters

Bij layers van het type Stored Procedure worden de parameters automatisch gedetecteerd uit het Execution Statement. Per parameter kun je instellen:

Opties

Testen van je dataset

Test JSON

Nadat je de dataset hebt opgeslagen, kun je deze testen met de knop Test JSON.

1. Klik op Test JSON (alleen beschikbaar als er geen onopgeslagen wijzigingen zijn)
2. Er opent een popup met de databron en invoervelden voor alle parameters
3. Kies de databron waarop je wilt testen (bij meerdere aangevinkte aliassen)
4. Vul testwaarden in (bijvoorbeeld een bestaand klantnummer)
5. Klik op Uitvoeren
6. Je ziet het JSON resultaat zoals een API of webhook het zou ontvangen

De test haalt maximaal 20 records op. Het JSON voorbeeld onder de layers toont de structuur al tijdens het bouwen, ook met niet-opgeslagen wijzigingen.

Wat je controleert

• Komen de juiste velden terug?
• Kloppen de veldnamen (aliassen)?
• Werkt de filtering correct?
• Zijn child layers correct genest?
• Is het aantal records realistisch?

Versioning

Elke dataset heeft een versie en optioneel versienotities:

Bij opslaan opent het venster Versie Beheer. Met Versie verhogen maak je een nieuw versienummer; de notitie is optioneel.

De versie wordt als badge getoond in het overzicht. Gebruik dit om bij te houden welke wijzigingen je hebt aangebracht, vooral als de dataset in productie wordt gebruikt.

Dataset overzicht

In het overzicht zie je alle datasets, gegroepeerd per groep. Met Alles open en Alles dicht klap je de groepen open of dicht. Met Importeer JSON laad je een eerder geëxporteerde dataset; SQLio vraagt dan op welke databron hij moet draaien.

Per dataset zie je:

Compleet voorbeeld: Order dataset met details

Stel je wilt een dataset maken die ordergegevens teruggeeft inclusief orderregels en klantinformatie.

Stap 1: Maak de dataset aan

• Naam: Order gegevens
• Omschrijving: Orderdata inclusief regels en klantinfo
• Status: Actief

Stap 2: Root layer — Orders

• Layer Naam: order
• Bron Type: Table
• Tabel: dbo.Orders
• Output Type: Object

Selecteer de velden:

Voeg een WHERE-conditie toe:

Stap 3: Child layer — Orderregels

Klik op + naast de Orders layer.

• Layer Naam: regels
• Bron Type: Table
• Tabel: dbo.OrderLines
• Output Type: Array
• JOIN Type: LEFT

Selecteer de velden:

Voeg een JOIN-conditie toe:

Stap 4: Child layer — Klantgegevens

Klik op + naast de Orders layer.

• Layer Naam: klant
• Bron Type: Table
• Tabel: dbo.Customers
• Output Type: Object
• JOIN Type: INNER

Selecteer de velden:

Voeg een JOIN-conditie toe:

Stap 5: Opslaan en testen

Klik op Opslaan en vervolgens op Test JSON. Vul een bestaand orderId in. Het resultaat:

{
  "orderId": 100,
  "besteldatum": "2024-01-15",
  "klantnummer": "K001",
  "totaalbedrag": 74.50,
  "status": "Verzonden",
  "regels": [
    {
      "regelId": 1,
      "artikelNr": "A001",
      "aantal": 5,
      "stuksprijs": 12.50,
      "omschrijving": "Bout M8x40"
    },
    {
      "regelId": 2,
      "artikelNr": "A002",
      "aantal": 2,
      "stuksprijs": 8.00,
      "omschrijving": "Moer M8"
    }
  ],
  "klant": {
    "naam": "ACME Corp",
    "stad": "Amsterdam",
    "telefoon": "020-1234567"
  }
}

Deze dataset kun je nu koppelen aan een API endpoint (GET) of gebruiken als JSON body voor een webhook.

Veelvoorkomende problemen