SPARQL-tutorial

    From Resistance in Belgium
    This page is a translated version of the page Tutorial and the translation is 100% complete.
    1. Inleiding tot SPARQL

    SPARQL gebruiken is alsof je een onderzoeker bent in een gigantisch archief. In plaats van elk document één voor één door te nemen, beschik je over een taal waarmee je met één gerichte zoekopdracht onmiddellijk de informatie kunt vinden die aan je criteria voldoet.

    Binnen het project Resistance in Belgium maakt SPARQL het eenvoudiger om toegang te krijgen tot gegevens over verzetsleden: geboorteplaats, woonplaats, officiële erkenningsstatussen of lidmaatschap van een verzetsorganisatie.

    Met SPARQL kun je:

    • Informatie filteren en combineren;
    • Je zoekopdrachten personaliseren met specifieke criteria;
    • Precieze gegevens ophalen zonder duizenden fiches handmatig te doorlopen;
    • Visualisaties genereren om je resultaten beter te interpreteren.

    Deze aanpak geeft je waardevolle autonomie bij het analyseren van de gegevens uit Resistance in Belgium. Je kunt niet alleen namenlijsten opvragen, maar ook complexe verbanden ontdekken, zoals leden die betrokken waren bij meerdere organisaties of verschillende erkenningsstatussen kregen.

    SPARQL geeft je de superkracht waar elke onderzoeker van droomt: stel een ultra-precieze vraag en zie het antwoord binnen milliseconden verschijnen. Natuurlijk vraagt dat enige oefening om onder de knie te krijgen. Geen zorgen! Deze handleiding is er om je te begeleiden en obstakels om te zetten in kansen… Wie zegt dat archiefonderzoek saai moet zijn?

    Klaar om de kracht van SPARQL te beheersen? Aan de slag!

    2. Strategie voor je eerste zoekopdrachten

    Nu je een algemeen idee hebt van wat SPARQL is, volgt hier een strategie om je onderzoek goed te starten.

    Er bestaan hulpmiddelen om SPARQL-query’s op te stellen, maar om meer autonomie en flexibiliteit te verwerven, is het vaak effectiever om te vertrekken van een bestaande query en die aan te passen aan je specifieke noden.

    Deze aanpak stelt je in staat om:

    Deze handleiding zal je begeleiden bij het begrijpen van de basisprincipes van SPARQL en je leren hoe je de essentiële elementen kunt herkennen om een bestaande query succesvol aan te passen.

    3. De basis van een SPARQL-query

    Een SPARQL-query bestaat uit enkele essentiële onderdelen. Hier zijn de twee belangrijkste:

    • SELECT: met deze clausule kies je welke informatie wordt weergegeven in de resultaten.
    • WHERE: met deze clausule kun je de gegevens filteren door specifieke criteria te definiëren. Hier beschrijf je aan welke voorwaarden de gegevens moeten voldoen.

    📝 Eenvoudig voorbeeld

    Hier is een query die de voor- en achternaam van personen in de databank ophaalt. Regels die beginnen met # zijn commentaarregels om elk onderdeel van de query uit te leggen. 

    SELECT ?naam ?voornaam
WHERE {
  ?persoon wdt:P1 wd:Q2 ;      # Selecteert personen
            wdt:P3 ?naam ;     # Haalt de achternaam op
            wdt:P2 ?voornaam . # Haalt de voornaam op
}

    Uitleg bij het voorbeeld:

    1. SELECT ?naam ?voornaam :
      Geeft aan dat we de waarden van de variabelen ?naam en ?voornaam willen weergeven in de resultaten.
    2. WHERE { ... } :
      Geeft de structuur en voorwaarden van de query:
        • ?persoon wdt:P1 wd:Q2 : selecteert elementen die menselijke wezens zijn (P1 = type item, Q2 = persoon).
        • wdt:P3 ?naam : koppelt de familienaam aan de variabele ?naam (P3).
        • wdt:P2 ?voornaam : koppelt de voornaam aan de variabele ?voornaam (P2).

    Je kent nu de basis van alle SPARQL-query’s. Je zult ze kunnen aanpassen aan je behoeften door eenvoudigweg de juiste variabelen te selecteren en filters, extra kolommen of geavanceerde opties toe te voegen.

    4. De truc die het verschil maakt

    Wanneer je een SPARQL-query opstelt, kan het lastig zijn om numerieke identificatiecodes voor gemeenten, erkenningsstatussen of verzetsorganisaties te onthouden. Gelukkig is er een auto-aanvulfunctie beschikbaar om je te helpen.

    • Praktische tip: druk op Ctrl + Spatie terwijl je een eigenschap of waarde typt. Hierdoor kun je termen in je eigen taal zoeken in plaats van te vertrouwen op numerieke identificatiecodes.

    Voorbeeld:
    Als je een gemeente zoals Anderlecht zoekt, hoef je het identificatienummer (bijvoorbeeld wd:Q102) niet uit het hoofd te kennen. Gebruik Ctrl + Spatie en begin "Anderlecht" te typen — de editor stelt automatisch het juiste identificatienummer voor.

    Deze methode helpt je tijd te besparen en fouten te vermijden bij het invoeren van identificaties.

    SPARQL automatisch aanvullen animatie
    Automatisch aanvullen in actie — Druk op Ctrl + Spatie om de juiste eigenschap of waarde te vinden.
    5. Labels tonen in de gewenste taal

    Wanneer je een Wikibase-database ondervraagt met SPARQL, worden in de resultaten soms identificaties weergegeven (zoals Q102) in plaats van duidelijke tekst (zoals "Anderlecht"). Om de resultaten leesbaarder te maken, kun je labels (benamingen) ophalen in de taal van jouw voorkeur (Nederlands, Frans, Duits of Engels). Gebruik simpelweg SERVICE wikibase:label aan het einde van je query om labels in de juiste taal op te halen.

    Hoe werkt het?
    Voeg de service wikibase:label toe aan je query. Hier is een eenvoudig voorbeeld dat de naam van personen en hun woonplaats ophaalt, met labels in het Frans: 

    SELECT ?persoon ?persoonLabel ?woonplaats ?woonplaatsLabel
WHERE {
  ?persoon wdt:P1 wd:Q2.         # Selecteer personen
  ?persoon wdt:P7 wd:Q102.       # Woonplaats (P7) = Anderlecht (Q102)
  SERVICE wikibase:label {       # Service om labels op te halen
    bd:serviceParam wikibase:language "fr". # Gekozen taal: Frans
  }
}

    Korte uitleg

    • SERVICE wikibase:label: activeert de service om labels op te halen.
    • bd:serviceParam wikibase:language "fr": bepaalt de taal van de labels (vervang "fr" door "nl", "en", "de" afhankelijk van je voorkeur).

    AUTO_LANGUAGE gebruiken
    Om labels automatisch weer te geven in de taal van je browser of gebruikersvoorkeur, gebruik AUTO_LANGUAGE: 

    bd:serviceParam wikibase:language "[AUTO_LANGUAGE],fr,en".

    Tips

    • Gebruik bd:serviceParam wikibase:language "[AUTO_LANGUAGE],fr,en" om labels automatisch in de voorkeurstaal van je browser te tonen.
    • Je kunt meerdere voorkeurstalen instellen. Bijvoorbeeld, om eerst Nederlands te tonen en anders Engels: bd:serviceParam wikibase:language "nl,en,[AUTO_LANGUAGE]"
    6. Extra informatie toevoegen

    Om je resultaten te verrijken, kun je meerdere kolommen toevoegen met extra informatie, zoals woonplaats, geboortedatum of andere relevante gegevens. Laat je inspireren door de lijst van eigenschappen of bekijk hoe gegevens zijn gemodelleerd aan de hand van een voorbeeld zoals Andrée De Jongh.

    Eenvoudige kolommen toevoegen
    Voeg simpelweg de eigenschappen toe die overeenkomen met de informatie die je wilt ophalen.

    Voorbeeld: voeg de woonplaats en geboortedatum van personen toe. 

    SELECT ?persoon ?persoonLabel ?woonplaatsLabel ?geboortedatum
WHERE {
  ?persoon wdt:P7 ?woonplaats .         # P7: Woonplaats
  ?persoon wdt:P67 ?geboortedatum .     # P67: Geboortedatum

    SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],nl" }
}

    Een kolom optioneel maken met OPTIONAL
    Als bepaalde informatie mogelijk ontbreekt, gebruik dan OPTIONAL zodat je toch resultaten krijgt. Met OPTIONAL kun je gegevens ophalen zelfs als een kolom leeg is.

    Voorbeeld: voeg geboortedatum alleen toe als die beschikbaar is. 

    SELECT ?persoon ?persoonLabel ?woonplaatsLabel ?geboortedatum
WHERE {
  ?persoon wdt:P7 ?woonplaats .                         # P7: Woonplaats

    OPTIONAL { ?persoon wdt:P67 ?geboortedatum . }        # P67: Optionele geboortedatum

  
  SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],nl" }
}

    Tip: om meerdere waarden in één kolom te combineren (bijvoorbeeld lidmaatschap van verschillende verzetsorganisaties), gebruik CONCAT. Zo groepeer je de informatie in één cel, terwijl je per persoon slechts één rij behoudt. Bekijk de SPARQL-documentatie online om meer te leren over deze functie en haar variaties.

    7. Het aantal resultaten beperken

    Om het aantal weergegeven resultaten te beperken (bijvoorbeeld als je een query test met veel kolommen), voeg je de clausule LIMIT toe aan je query.

    Voorbeeld: toon enkel de eerste 10 resultaten. 

    SELECT ?persoon ?persoonLabel ?geboortedatum
WHERE {
  ?persoon wdt:P67 ?geboortedatum .

    SERVICE wikibase:label {
    bd:serviceParam wikibase:language "[AUTO_LANGUAGE],nl"
  }
}
LIMIT 10
    8. Resultaten sorteren

    Om resultaten te sorteren op een bepaalde kolom, gebruik je de clausule ORDER BY. Standaard is de sortering oplopend (ASC), maar je kunt ook een aflopende sortering toepassen met DESC.

    Voorbeeld: Sorteer op geboortedatum in oplopende volgorde. 

    SELECT ?persoon ?persoonLabel ?geboortedatum
WHERE {
  ?persoon wdt:P67 ?geboortedatum .

    SERVICE wikibase:label {
    bd:serviceParam wikibase:language "[AUTO_LANGUAGE],nl"
  }
}
ORDER BY ASC(?geboortedatum)
    9. Filters toevoegen

    Met filters kun je je resultaten verfijnen door specifieke voorwaarden toe te voegen aan je query. Ze zijn handig om meerdere criteria te combineren of bepaalde waarden uit te sluiten.

    📝 Eenvoudig voorbeeld zonder filter

    Om personen te selecteren die aan een bepaald criterium voldoen, zoals bijvoorbeeld “woonachtig in Anderlecht”, kun je gewoon schrijven: 

    ?persoon wdt:P4 wd:Q102 .  # Selecteer personen die in Anderlecht wonen

    FILTER gebruiken voor specifieke voorwaarden
    Als je de resultaten verder wilt verfijnen, gebruik dan FILTER. Zo kun je meerdere voorwaarden combineren. Bijvoorbeeld: selecteer personen die in Anderlecht wonen en geboren zijn na 1 januari 1920 (Link om de query te testen). 

    SELECT ?persoon ?persoonLabel ?woonplaatsLabel ?geboortedatum
WHERE {
  # Selecteer woonplaats en geboortedatum van de persoon
  ?persoon wdt:P7 ?woonplaats .        # P7: Woonplaats
  ?persoon wdt:P67 ?geboortedatum .    # P67: Geboortedatum

    # Filter op personen die in Anderlecht wonen (wd:Q102) en geboren zijn na 1 januari 1920
  FILTER(?woonplaats = wd:Q102 && ?geboortedatum >= "1920-01-01T00:00:00Z"^^xsd:dateTime)

    # Gebruik de label-service voor leesbare resultaten
  SERVICE wikibase:label {
    bd:serviceParam wikibase:language "[AUTO_LANGUAGE],nl"
  }
}

    Geavanceerd gebruik : Je kunt ook FILTER NOT EXISTS gebruiken voor complexere uitsluitingen. Hiermee kun je resultaten uitsluiten die aan een bepaalde voorwaarde voldoen. Je kunt deze functie verder ontdekken in geavanceerde SPARQL-documentatie.

    10. Resultaten visualiseren

    Om grafieken te maken op basis van je SPARQL-query’s heb je twee opties:

    • Gebruik de functies van de Query Service: je kunt gegevens weergeven als tabellen, kaarten, staafdiagrammen en tijdlijnen. Meer info vind je in de documentatie van Wikidata.
    • Exporteer de gegevens en gebruik andere tools: je kunt de resultaten exporteren als CSV of TSV en deze vervolgens verwerken met datavisualisatietools.
    11. Federatieve zoekopdrachten

    Geavanceerde functie: Als je meerdere databanken tegelijk wil bevragen om je resultaten te verrijken, kun je federatieve zoekopdrachten gebruiken. Bekijk dit voorbeeld waarin informatie uit Resistance in Belgium wordt gecombineerd met gegevens uit externe bronnen (zoals Wikidata).

    12. Je zoekopdrachten opslaan en delen

    Na het uitvoeren van een SPARQL-query kun je de link opslaan en delen. Klik op het tabblad “Link” boven de resultaten om een Tiny URL (verkorte link) te genereren. Zo kunnen anderen de query gemakkelijk openen en uitvoeren.

    13. Resultaten downloaden

    Nadat je een query hebt uitgevoerd, gebruik je het tabblad “Download” (rechts boven de resultaten) om de gegevens te exporteren in verschillende formaten: CSV (compatibel met LibreOffice Calc of Excel), TSV of JSON.

    Best practice: sla het bestand op met een duidelijke naam die je zoekcriteria weergeeft, zodat je het later makkelijk kunt terugvinden en hergebruiken.

    14. Extra bronnen

    Wil je je kennis verdiepen en complexere zoekopdrachten opstellen? Bekijk dan deze nuttige bronnen:

    Externe bronnen
    We raden ook aan om externe bronnen te bekijken, zoals de Wikidata-tutorials, die een uitstekende introductie tot SPARQL-query’s bieden. Deze voorbeelden gebruiken dezelfde software (Wikibase) als ons project, maar houd er rekening mee dat de gegevens en de structuur van de query’s specifiek zijn voor Wikidata en niet rechtstreeks toepasbaar zijn op Resistance in Belgium.

    Retrieved from "https://data.arch.be/w/index.php?title=Tutorial/nl&oldid=218081"