Tutoriel SPARQL

1/ Introduction à SPARQL

Utiliser SPARQL, c’est comme être un⸱e enquêteur⸱rice dans un vaste fonds d’archives. Ici, plutôt que de fouiller chaque document un par un, vous disposez d’un langage qui vous permet, en une requête précise, de retrouver instantanément les informations correspondant à vos critères.

Dans le cadre de Resistance in Belgium, SPARQL facilite l’accès aux données sur les résistant⸱e⸱s : lieu de naissance, domicile, statuts de reconnaissance officiels ou appartenance à une organisation de résistance.

Avec SPARQL, vous pouvez :

• Filtrer et croiser des informations ;
• Personnaliser vos recherches avec des critères spécifiques ;
• Extraire des données précises sans parcourir des milliers de fiches manuellement ;
• Générer des visualisations pour mieux interpréter vos résultats.

Cette approche vous offre une autonomie précieuse dans l’analyse des données de Resistance in Belgium. Vous pouvez non seulement extraire des listes de noms, mais aussi identifier des liens complexes, comme des résistant⸱e⸱s affilié⸱e⸱s à plusieurs organisations ou ayant obtenu différents statuts de reconnaissance.

SPARQL vous donne le superpouvoir convoité par tous les chercheurs et chercheuses : poser une question ultra-précise et voir les réponses surgir en quelques millisecondes. Bien sûr, comme tout superpouvoir, il demande un peu d’entraînement pour être maîtrisé. Mais pas de panique ! Ce tutoriel est là pour vous guider et transformer les obstacles en opportunités… Qui a dit que la recherche dans les archives devait être poussiéreuse ?

Prêt⸱e à maîtriser la force de SPARQL ? Allons-y !

2/ Stratégie pour vos premières requêtes

Maintenant que vous avez une idée générale de ce qu’est SPARQL, voici une stratégie pour bien démarrer vos recherches.

Il existe des outils d’aide à la rédaction de requêtes SPARQL, mais pour gagner en autonomie et en flexibilité, il est souvent plus efficace de partir d’une requête existante et de l’adapter à vos besoins spécifiques.

Cette approche vous permet de :

• Consulter nos exemples de requêtes SPARQL ;
• Utiliser des outils d’intelligence artificielle capables de générer des requêtes selon vos besoins.

Ce tutoriel vous guidera dans la compréhension des bases de SPARQL et vous apprendra à identifier les éléments clés pour adapter une requête existante avec succès.

3/ Les bases d’une requête SPARQL

Une requête SPARQL repose sur quelques éléments essentiels. Voici les deux principaux :

• SELECT : cette clause permet de choisir quelles informations afficher dans les résultats. Vous spécifiez ici les éléments que vous souhaitez voir apparaître.
• WHERE : cette clause permet de filtrer les données en définissant des critères précis. C’est ici que vous décrivez les conditions que les données doivent respecter.

📝 Exemple simple

Voici une requête qui extrait les noms et prénoms des personnes présentes dans la base de données. Les lignes qui commencent par # sont des commentaires pour expliquer chaque partie de la requête.

SELECT ?nom ?prenom
WHERE {
  ?personne wdt:P1 wd:Q2 ;      # Sélectionne des personnes
            wdt:P3 ?nom ;      # Récupère le nom de famille
            wdt:P2 ?prenom .   # Récupère le prénom
}

Explication de l’exemple :

1. SELECT ?nom ?prenom :
   Indique que l’on souhaite voir apparaître les valeurs des variables ?nom et ?prenom dans les résultats.
2. WHERE { ... } :
   Décrit la structure et les conditions de la requête :
   • ?personne wdt:P1 wd:Q2 : sélectionne les éléments qui sont des êtres humains (P1 = nature de l’élément, Q2 = personne).
   • wdt:P3 ?nom : associe à ?nom le nom de famille de la personne (P3).
   • wdt:P2 ?prenom : associe à ?prenom le prénom de la personne (P2).

Vous connaissez maintenant les bases de toutes les requêtes SPARQL. Vous allez pouvoir les adapter à vos besoins en sélectionnant facilement les variables à utiliser et en ajoutant des filtres, des colonnes supplémentaires ou des options avancées.

4/ L’astuce qui fait toute la différence

Lorsque vous rédigez une requête SPARQL, il peut être fastidieux de se souvenir des identifiants numériques pour les communes, statuts de reconnaissance ou organisations de résistance. Heureusement, une fonctionnalité d’auto-complétion est disponible pour vous simplifier la tâche.

• Astuce pratique : appuyez sur Ctrl + Espace lorsque vous êtes en train de taper une propriété ou une valeur. Cela vous permet de rechercher des termes dans votre langue plutôt que d’utiliser des identifiants numériques.

Exemple :
Si vous cherchez une commune comme Anderlecht, au lieu de retenir son identifiant (par exemple wd:Q102), utilisez Ctrl + Espace et commencez à taper "Anderlecht" pour que l’éditeur propose automatiquement l’identifiant correspondant.

Cette méthode vous permet de gagner du temps et d’éviter les erreurs liées à la saisie des identifiants.

5/ Afficher les labels dans la langue de son choix

When querying a Wikibase dataset with SPARQL, the results may sometimes display identifiers (e.g. Q102) instead of explicit text (e.g. Anderlecht). To make the results more readable, you can retrieve the labels (i.e., names) in the language of your choice (French, Dutch, German, or English). Simply use SERVICE wikibase:label at the end of your query to display values in your preferred language.

How to do it?
Add the wikibase:label service to your query. Here is a simple example that retrieves people’s names along with their place of residence, with labels displayed in French:

SELECT ?person ?personLabel ?residence ?residenceLabel
WHERE {
  ?person wdt:P1 wd:Q2 .              # Select human entities
  ?person wdt:P7 wd:Q102 .            # Residence (P7) = Anderlecht (Q102)
  SERVICE wikibase:label {           # Service to retrieve labels
    bd:serviceParam wikibase:language "fr" . # Language preference: French
  }
}

Quick explanation

• SERVICE wikibase:label: activates the label retrieval service.
• bd:serviceParam wikibase:language "fr": sets the label language (replace "fr" with "en", "nl", "de", etc. as needed).

Using AUTO_LANGUAGE
To automatically show labels in the language set by your browser or user preferences, use AUTO_LANGUAGE:

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

Tips

• To automatically display labels in your browser or user’s preferred language, use: bd:serviceParam wikibase:language "[AUTO_LANGUAGE],fr,en"

You can also prioritize multiple languages. For example, to display labels in French and fall back to English if unavailable: bd:serviceParam wikibase:language "fr,en,[AUTO_LANGUAGE]"

6. Adding Additional Information

To enrich your results, you can add multiple columns containing additional information, such as residence, date of birth, or other relevant details. To get inspired: check out the list of properties or see how data is modeled using an example, like Andrée De Jongh.

Adding simple columns
Just include the properties that correspond to the information you want to extract.

Example: Add the residence and date of birth of individuals.

SELECT ?person ?personLabel ?residenceLabel ?birthDate
WHERE {
  ?person wdt:P7 ?residence .        # P7: Residence
  ?person wdt:P67 ?birthDate .       # P67: Date of birth
</div>

  <div lang="en" dir="ltr" class="mw-content-ltr">
SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],fr" }
}

Making a column optional with OPTIONAL
If some information might be missing, use OPTIONAL to avoid limiting the results. Adding OPTIONAL lets you retrieve results even if a column is empty.

Example: Add date of birth only if the information is available.

SELECT ?person ?personLabel ?residenceLabel ?birthDate
WHERE {
  ?person wdt:P7 ?residence .        # P7: Residence
</div>

  <div lang="en" dir="ltr" class="mw-content-ltr">
OPTIONAL { ?person wdt:P67 ?birthDate . }  # P67: Optional date of birth
</div>

  <div lang="en" dir="ltr" class="mw-content-ltr">
SERVICE wikibase:label { bd:serviceParam wikibase:language "[AUTO_LANGUAGE],fr" }
}

Tip: To combine multiple values into a single column (for example, to “concatenate” membership in multiple resistance organizations), use CONCAT. This allows grouping the data into a single cell while keeping one result row per person. To explore this function and its variants, refer to the SPARQL documentation available online.

7. Limiting the Number of Results

To reduce the number of results displayed (especially if you’re testing a query with many columns), add the LIMIT clause to your query.

Example: Show only the first 10 results.

SELECT ?person ?personLabel ?birthDate
WHERE {
  ?person wdt:P67 ?birthDate .
</div>

  <div lang="en" dir="ltr" class="mw-content-ltr">
SERVICE wikibase:label {
    bd:serviceParam wikibase:language "[AUTO_LANGUAGE],fr"
  }
}
LIMIT 10

8. Sorting the Results

To sort results by a specific column, use the ORDER BY clause. By default, the sorting is ascending (ASC), but you can also specify descending order using DESC.

Example: Sort results by birth date in ascending order.

SELECT ?person ?personLabel ?birthDate
WHERE {
  ?person wdt:P67 ?birthDate .
</div>

  <div lang="en" dir="ltr" class="mw-content-ltr">
SERVICE wikibase:label {
    bd:serviceParam wikibase:language "[AUTO_LANGUAGE],fr"
  }
}
ORDER BY ASC(?birthDate)

9. Adding Filters

Filters allow you to refine your results by adding specific criteria to your query. They are useful for combining multiple conditions or excluding certain values.

📝 Simple example without filter

To select individuals matching a basic criterion—like “residing in Anderlecht”—you can write:

?person wdt:P4 wd:Q102 .  # Selects individuals residing in Anderlecht

Using FILTER for specific conditions
If you want to narrow your results even more, use FILTER. This allows you to combine multiple conditions. For example: select individuals living in Anderlecht and born after January 1st, 1920 (Link to test the query).

SELECT ?person ?personLabel ?residenceLabel ?birthDate
WHERE {
  # Select residence and birth date of the person
  ?person wdt:P7 ?residence .        # P7: Residence
  ?person wdt:P67 ?birthDate .       # P67: Date of birth
</div>

  <div lang="en" dir="ltr" class="mw-content-ltr">
# Filter for people living in Anderlecht (wd:Q102) and born after Jan 1, 1920
  FILTER(?residence = wd:Q102 && ?birthDate >= "1920-01-01T00:00:00Z"^^xsd:dateTime)
</div>

  <div lang="en" dir="ltr" class="mw-content-ltr">
# Use the label service for readable output
  SERVICE wikibase:label {
    bd:serviceParam wikibase:language "[AUTO_LANGUAGE],fr"
  }
}

Advanced usage: It’s also possible to use FILTER NOT EXISTS for more complex exclusions. This allows you to filter out results that meet a specific condition. You can explore this functionality further in advanced SPARQL resources.

10. Visualizing Your Results

To create charts from your SPARQL queries, you have two options:

• Use the features of the Query Service: visualize the data in the form of tables, maps, bar charts, and timelines. For more details, see the Wikidata documentation.
• Export the data and use other tools: you can export your results in CSV or TSV format, and then process them with data visualization tools.

11. Federated Queries

Advanced feature: If you want to query multiple databases at once to enrich your results, you can use federated queries. For an example, see this sample query, which extracts information from Resistance in Belgium and combines it with data from external sources (e.g., Wikidata).

12. Saving and Sharing Your Queries

After running a SPARQL query, you can save and share its link. Click the “Link” tab above the results to generate a Tiny URL (a short link) that’s easy to copy and share. This allows others to run the same query directly, with no extra effort.

13. Downloading the Results

After executing a query, use the “Download” tab (located on the right above the results) to export the data in different formats: CSV (compatible with LibreOffice Calc or Excel), TSV, or JSON.

Best practice: Save the file with a clear name that reflects your search criteria to make it easier to reuse later.

14. Additional Resources

To deepen your knowledge and create more advanced queries, here are some useful resources:

• List of properties used to describe resistance members:
  https://data.arch.be/wiki/Special:ListProperties

Example profile of an individual (e.g. Andrée De Jongh):
https://data.arch.be/wiki/Item:Q6793

Sample of nine SPARQL queries organized by complexity level:
https://data.arch.be/wiki/In-depth_search/fr

FAQ to understand the context and content of the available data:
https://data.arch.be/wiki/FAQ/en

External Resources
We also encourage you to consult external resources, such as Wikidata tutorials, which offer excellent introductions to SPARQL queries. Although these examples use the same software (Wikibase) as this project, note that the data and query structure are specific to Wikidata and do not apply directly to the content of Resistance in Belgium.

• Wikidata Query Service Tutorial (interactive): An interactive tutorial for beginners to explore SPARQL queries practically. (Resource in English).
• A gentle introduction to the Wikidata Query Service: A simple step-by-step guide to understand the interface and write queries.
• Wikidata:SPARQL Tutorial: A detailed and structured SPARQL guide for those who want to deepen their query writing.
• AI-powered tools that can assist you in writing queries.