Wikidata Query Service/User Manual/fr

WDQS, le service de requêtes Wikidata, est un progiciel et un service publiquement accessible conçus pour fournir un point d'accès SPARQL vous permettant d'interroger le jeu de données Wikidata.

Cette page et d'autres pages de documentation pertinentes seront mises à jour en conséquence ; il est recommandé de les suivre si vous utilisez ce service.

Vous pouvez consulter des exemples de requêtes SPARQL sur la page d'exemples SPARQL.

Jeu de données
Le service de requête Wikidata fonctionne sur un jeu de données de Wikidata.org, représenté en RDF comme décrit dans la documentation du format d'export RDF.

Le jeu de données du service ne correspond pas exactement au jeu de données produit par les exports RDF, principalement pour des raisons de performances ; la documentation décrit un petit nombre de ces différences.

Vous pouvez télécharger un export hebdomadaire des mêmes données à l'adresse :

https://dumps.wikimedia.org/wikidatawiki/entities/

Notions de base - Comprendre le triplet sémantique SPO : sujet, prédicat, objet
SPO pour « subject, predicate, object » est connu comme un triplet, ou communément appelé dans Wikidata, une déclaration sur les données.

La déclaration "La capitale des États-Unis est Washington DC" se compose du sujet "États-Unis" (Q30), du prédicat "La capitale est" (P36), et d'un objet "Washington DC" (Q61). Cette déclaration peut être représentée par trois URIs:

Grâce aux préfixes (voir ci-dessous), la même déclaration peut être écrite sous une forme plus concise. Notez le point à la fin pour représenter la fin de la déclaration.

Le /entity/ (wd:) représente l'entité Wikidata (valeurs de l'identifiant-Q). Le /prop/direct/ (wdt:) est une propriété véridique, c'est-à-dire une valeur à laquelle on s'attend le plus souvent en regardant la déclaration. Les propriétés véridiques sont nécessaires parce que certaines déclarations pourraient être « plus-vraies » que d'autres. Par exemple, la déclaration « La capitale des États-Unis est New York » est vraie - mais seulement dans le contexte historique de l'année 1790. WDQS utilise des rangs pour déterminer quelles déclarations doivent être utilisées comme véridiques.

En plus des déclarations véridiques, WDQS stocke toutes les déclarations (véridiques et non véridiques), mais n'utilise pas le même préfixe wdt:. U.S. capital a trois valeurs: DC, Philadelphie et New York. Et chacune de ces valeurs a des "qualificatifs" - c'est à dire des informations supplémentaires, telles que les dates de début et de fin, qui affinent l'étendue de chaque déclaration. Pour stocker cette information dans la base de données RDF (triplestore), WDQS introduit un sujet "déclaration" auto-magique, qui est essentiellement un nombre aléatoire :

Voir Tutoriel SPARQL - qualificateurs pour plus d'informations.

Sujet, prédicat, objet (spo) est également utilisé comme une forme de structure syntaxique de base pour interroger les structures de données RDF ou toute base de données graphique ou de base de triplets (triplestore), comme le WDQS (Wikidata Query Service), géré par Blazegraph, une base de données graphique haute performance.

Utilisations avancées des triplets SPO pouvant inclure d'autres triplets comme objets, ou être les sujets d'autres triplets !

Notions de base - Comprendre les préfixes
Les sujets et les prédicats (première et seconde valeurs du triplet) doivent toujours être stockés sous la forme URI. Par exemple, si le sujet est Universe (Q1), il sera stocké sous   . Les préfixes nous permettent d'écrire ce long URI sous une forme plus courte: wd:Q1. Contrairement aux sujets et aux prédicats, l'objet (la troisième valeur du triplet) peut être un URI ou un littéral, par exemple un nombre ou une chaîne.

WDQS comprend de nombreuses abréviations de raccourcis, connues sous le nom de préfixes. Certains sont internes à Wikidata, par ex. wd, wdt, p, ps, bd, et beaucoup d'autres sont des préfixes externes couramment utilisés, comme rdf, skos, owl, schema.

Dans la requête suivante, nous demandons des éléments où il y a une déclaration de "P279 = Q7725634" ou en termes plus complets, en sélectionnant les sujets qui ont un prédicat de "sous-classe de" avec un objet de = "travail littéraire".

Les variables sorties :

Les extensions
Le service prend en charge les extensions suivantes aux fonctionnalités SPARQL standards :

Service d'étiquette
Vous pouvez récupérer l'étiquette, l'alias ou la description des entités que vous interrogez, avec la langue de repli, en utilisant le service spécialisé avec l'URI . Ce service est très utile lorsque vous souhaitez récupérer des étiquettes, car il réduit la complexité des requêtes SPARQL dont vous auriez autrement besoin pour obtenir le même résultat.

Le service peut être utilisé dans l'un des deux modes: manuel ou automatique.

En mode automatique, il vous suffit de spécifier le modèle de service, par exemple:

et WDQS va automatiquement générer les libellés comme suit:


 * Si une variable non positionnée dans $code1 est nommée $code2, WDQS produit le libellé ($code3) pour l'entité de la variable $code4.
 * Si une variable non positionnée dans $code5 est nommée $code6, WDQS produit l'alias ($code7) pour l'entité de la variable $code8.
 * Si une variable non positionnée dans $code9 est nommée $code10, WDQS produit la description ($code11) pour l'entité de la variable $code12.
 * If an unbound variable in  is named , then WDQS produces the alias  for the entity in variable.
 * If an unbound variable in  is named , then WDQS produces the description  for the entity in variable.

Dans chaque cas, la variable de  doit être positionnée, sinon le service échoue.

Le mode automatique ne fait qu'inspecter la projection de la requête – par exemple, dans, seule la première étiquette est reconnue et dans ce mode,   n'est pas pris en charge du tout. Dans ces cas, vous devrez utiliser le mode manuel (voir ci-après).

Vous spécifiez votre/vos langue(s) préférée(s) pour l'étiquetage avec un ou plusieurs triplets de. Chaque chaîne peut contenir un ou plusieurs codes de langue, séparés par des virgules. WDQS envisage les langues dans l'ordre où vous les avez spécifiées. S'il n'existe pas de libellé dans aucune des langues mentionnées, l'identifiant-Q de l'entité (sans aucun préfixe) est utilisé pour le libellé.

Le site web du service de requête remplace auto-magiquement  par le code de langue actuel de l'interface utilisateur. Par exemple, si l'interface utilisateur est en français, le code SPARQL  sera converti en   avant d'être envoyé au service de requête.

Exemple, montrant la liste des présidents des États-Unis avec leurs épouses :

Dans cet exemple WDQS crée automatiquement les libellés  et   pour les propriétés.

En mode manuel, vous associez explicitement les variables des libellés à l'intérieur du code appelant le service, mais WDQS fournit encore la résolution de la langue ainsi que la langue de repli. Exemple :

Cette syntaxe entrainera la recherche des libellés et descriptions en français, en allemand et en anglais, puis si rien ne convient l'identifiant Q sera utilisé en guise de libellé.

Recherche géospatiale
Le service permet de rechercher des éléments avec des coordonnées situées dans un certain rayon à partir d'un centre et à l'intérieur d'un rectangle défini.

Recherche autour d'un point
Exemple:

La première ligne de l'appel du service  doit avoir le format     , où le résultat de recherche liera   aux éléments avec les endroits spécifiés et   à leur coordonnées. Les paramètres supportés sont :

Recherche à l'intérieur d'une région rectangulaire
Exemple de recherche dans une boîte géographique :

ou :

Les coordonnées peuvent être spécifiées directement :

La première ligne de l'appel au service  doit avoir le format     , et le résultat de la recherche va affecter   aux éléments à l'intérieur de la zone  spécifiée et   à leurs coordonnées. Les paramètres possibles sont:

et  doivent être spécifiés ensemble, ainsi que   et , et ne peuvent pas être mélangés. Si les prédicats  et   sont utilisés, les points sont supposés être les coordonnées de la diagonale de la boîte, les coins sont déduits en conséquence.

Fonction de distance
La fonction  retourne la distance entre deux points sur la terre, en kilomètres. Exemple d'utilisation :

Fonctions éléments de coordonnées
Les fonctions,   et   retournent des parties de coordonnées : respectivement l'URI du globe, la latitude et la longitude.

Fonctions de décodage d'URLs
Le fonction  décodes une chaîne URI donnée (c'est à dire inverse l'encodage des pourcents). Cela peut être nécessaire lorsque vous convertissez des titres Wikipedia (qui sont encodés), vers des chaînes actuelles. Cette fonction est l'opposée de la fonction SPARQL encode_for_uri.

Préfixes automatiques
La plupart des préfixes utilisés dans les requêtes usuelles sont pris en charge par le moteur sans avoir besoin de les spécifier explicitement.

Dates étendues
Le service prend en charge les valeurs de dates du type  dans un intervalle d'environ 290 billions d'années dans le passé et dans le futur, avec une résolution d'une seconde. WDQS enregistre les dates sous forme de nombres de secondes à 64 bits depuis l'époque Unix.

Extensions Blazegraph
La plateforme Blazegraph sur laquelle WDQS est implémenté possède son propre ensemble d'extensions SPARQL. Parmi elles, plusieurs algorithmes de graphes transverses sont documentés sur le wiki Blazegraph, comprenant BFS, le plus court chemin, ainsi que les implémentations de CC et de PageRank.

Consultez également la documentation sur les requêtes de Blazegraph pour les informations concernant la manière de contrôler l'exécution des requêtes et les différents aspects du moteur.

Il n'y a pas de documentation dans le wiki BlazeGraph à propos de l'extension bd:sample. Elle n'est documentée que dans un commentaire du code.

Fédération
Nous permettons que les requêtes fédérées SPARQL appellent un nombre choisi de bases de données externes. Voir la liste complète des points de terminaison fédérés sur la page dédiée.

Exemple de requête fédérée :

Veuillez noter que les bases de données servies par les points de terminaison fédérés, utilisent des ontologies qui peuvent être très différentes de celles de Wikidata. Voir les liens vers la documentation du propriétaire pour en connaître plus sur les ontologies et l'accès aux données de ces bases.

API MediaWiki
Veuillez lire la description complète sur la page de documentation de l'API Service de MediaWiki.

L'API Service de MediaWiki autorise d'appeler l'API MediaWiki à partir de SPARQL, et de recevoir les résultats de l'intérieur de la reqête de SPARQL. Exemple (pour trouver les membres d'une catégorie) :

Service Wikimedia
Wikimedia exécute l'instance de service public de WDQS, qui est disponible pour utilisation sur http://query.wikidata.org/.

Le temps d'exécution de la requête sur le point d'accès public est limité à 60 secondes. C'est vrai à la fois pour l'IHM et pout le point d'accès SPARQL public.

Interface graphique (IHM)
L’interface de la page d’accueil du service de requêtes http://query.wikidata.org/ vous permet de créer et de soumettre des requêtes SPARQL au moteur de requête. Les résultats sont affichés par défaut sous forme de tableau HTML. Notez que chaque requête dispose d’une URL unique qui peut-être ajoutée à vos marque-pages ou sauvegardée pour une réutilisation future. Aller à cette URL va afficher la requête dans la fenêtre d’édition, mais ne la lancera pas - vous devrez cliquer sur « Lancer la requête » pour cela.

Il est également possible d’obtenir une URL courte pour cette requête via un raccourcisseur d’URL en cliquant sur le lien « Générer une URL courte » à droite — cela produira une URL raccourcie pour la requête actuelle.

Le bouton Ajoutez les préfixes génère une entête contenant les préfixes de requête SPARQL standards. La liste complète des préfixes utilisables est listée dans la documentation du format RDF. Notez que les préfixes les plus courants n’ont pas besoin d’être précisés dans la requête, car WDQS les ajoute automatiquement lui-même.

L’interface fournit également un explorateur simple d’entités dans les résultats, qui peut être activé en cliquant sur le symbole « 🔍 » situé à côté du résultat de l’entité. Cliquer directement sur le numéro-Q de l’entité vous amènera sur la page de l'entité de wikidata.org.

Visualisations par défaut

 * Article principal: Visionner les résultats (sur Wikidata)

Si vous lancez la requête dans l’interface WDQS, vous pouvez choisir un type de visualisation pour vos résultats en ajoutant un commentaire  au début de la requête.

Afficher un titre
Si vous exécutez la requête dans l'interface utilisateur WDQS, vous pourrez afficher un titre précédant les résultats en plaçant un commentaire :  au début de la requête.

Point d'accès SPARQL
Les requêtes SPARQL peuvent être soumises directement au point de terminaison SPARQL avec par l'intermédiaire de GET ou de POST à.

Les requêtes GET comportent l'action spécifiée dans l'URL même, dans le format, par exemple.

Les requêtes POST peuvent alternativement accepter la commande à l'intérieur de la requête, au lieu de l'URL, ce qui permet d'exécuter des commandes plus longues sans être limité par la longueur maximale de l'URL. (Notez que le corps du POST doit encore inclure le préfixe  (c'est à dire, qu'il doit être   plutôt que simplement  ), et la commande SPARQL doit encore être échappée dans l'URL.)

Le résultat est retourné au format XML par défaut, ou alors en JSON dans le cas où soit le paramètre  est présent dans l’url, soit quand l’entête   est fournie avec la requête HTTP.

Le format JSON est standard SPARQL 1.1 Query Results JSON Format.

Il est recommandé d'utiliser GET pour les petites requêtes et POST pour les plus longues, parce que les requêtes POST ne sont pas mises dans le cache.

Formats suppoprtés
Les formats de sortie suivants sont pris en charge à l’heure actuelle par le point d’accès SPARQL :

Limites des requêtes
Il existe une limite maximale codée en dur pour le temps d’exécution d'une requête et configurée à 60 secondes. Les limites suivantes s'appliquent aussi :


 * Un client (agent utilisateur + IP) est autorisé à avoir 60 secondes de temps de traitement toutes les 60 secondes
 * Un client a droit à 30 requêtes en erreur par minute

Les clients qui dépassent les limites ci-dessus sont restreints avec le code retour HTTP. Utilisez l'en-tête pour voir quand la requête peut être répétée. Si le client ignore les erreurs 429 et continue de produire des demandes au-delà des limites, il peut être temporairement banni du service. Les clients qui ne respectent pas la politique User-Agent pourraient être complètement bloqués - assurez-vous d'envoyer un bon en-tête.

Toute requête va échouer si le temps nécessaire à son exécution dépasse cette limite configurée. Vous pouvez optimiser la requête ou rapporter une commande qui pose problème, ici.

Notez aussi que l'accès actuel au service est limité à 5 requêtes simultanées par IP. Les limites ci-dessus sont sensées changer en fonction des ressources et des modèles d'utilisation.

Explication du Query
Blazegraph permet d'afficher l'analyse de la commande qui explique comment la requête a été analysée syntaxiquement et quelles optimisations lui ont été appliquées. Pour voir cette information, ajoutez le paramètre  à la chaîne de la requête, par exemple :

Les espaces de noms
Les données du service de requêtes Wikidata contiennent l'espace de noms principal,, vers lequel sont dirigées les requêtes à destination du point de terminaison SPARQL principal, et d'autres espaces de noms auxilliaires listés ci-dessous. Pour demander les données d'un espace de noms différent, utilisez l'URL du point de terminaison https://query.wikidata.org/bigdata/namespace/NAMESPACENAME/sparql.

Les catégories
Voir la description complète sur la page de documentation des catégories.

Le service de requête Wikidata fournit également l'accès au graphe des catégories des wikis sélectionnés. La liste des wikis couverts peut être consultée ici : https://noc.wikimedia.org/conf/dblists/categories-rdf.dblist

L'espace de noms des catégories est. Le point de terminaison SPARQL pour y accéder est https://query.wikidata.org/bigdata/namespace/categories/sparql.

Veuillez consulter la page des catégories pour les informations détaillées.

DCAT-AP
Les données DCAT-AP pour Wikidata sont disponibles comme SPARQL sur le point d'entrée https://query.wikidata.org/bigdata/namespace/dcatap/sparql.

La source des données est: https://dumps.wikimedia.org/wikidatawiki/entities/dcatap.rdf

Exemple de requête pour récupérer des données :

Point d'accès Linked Data Fragments
Nous permettons aussi les requête à la base en utilisant une interface « Triple Pattern Fragments ». Cela permet de naviguer efficacement et économiquement dans des triplets de données lorsque qu’au moins un des composants du triplet est connu à l’avance et que vous devez récupérer tous les triplets qui correspondent à ce schéma. Plus d’information sur le site « Linked Data Fragments ».

L'interface peut être accédée par l'URL:. Ce service est implémenté par dessus la base de données Blazegraph, il aura donc la même latence que le service de requête. Exemple de requêtes :


 * https://query.wikidata.org/bigdata/ldf?subject=http%3A%2F%2Fwww.wikidata.org%2Fentity%2FQ146 - tous les triplets avec le sujet
 * https://query.wikidata.org/bigdata/ldf?subject=&predicate=http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23label&object=%22London%22%40en - tous les triplets qui ont l'étiquette anglaise « London »

Notez que seulement les URLs complètes sont actuellement prises en charge pour les paramètres,   et.

Par défaut, l'interface HTML est affichée, néanmoins plusieurs formats de données sont disponibles, définis par l'entête HTTP.

Les données sont retournées par pages de 100 triplets. Les pages sont numérotées en commençant à 1, et le numéro de page est défini par le paramètre.

Service autonome externe
Comme le service est du logiciel libre, il est également possible d'exécuter ce service sur n'importe quel serveur de l'utilisateur en utilisant les instructions fournies ci-dessous.

Les recommendations concernant le matériel peuvent être trouvées dans la documentation Blazegraph.

Si vous envisagez d'exécuter le service sur une instance Wikibase non-Wikidata, veuillez voir les instructions suivantes.

Installation
Pour installer le service, il est recommandé de télécharger le paquet du service complet en un fichier ZIP, par exemple de Maven Central, avec l'ID de groupe  et l'ID d'artifact «   », ou de copier la distribution des sources de https://github.com/wikimedia/wikidata-query-rdf/ et de la compiler avec « mvn package ». Le paquet ZIP sera dans le répertoire  sous.

Le paquet contient le serveur Blazegraph en tant qu'application, avec les bibliothèques nécessaires à l'exécution du service de mise à jour pour récupérer les données récentes du site wikidata, ainsi que les scripts pour faciliter différentes tâches, et l'interface utilisateur dans le sous-répertoire. Si vous voulez utiliser l'IHM, vous devrez configurer votre serveur HTTP pour la mettre en ligne.

Par défaut, uniquement le point de terminaison SPARQL sur http://localhost:9999/bigdata/namespace/wdq/sparql est configuré, et l'IHM par défaut de Blazegraph est disponible sur http://localhost:9999/bigdata/. Notez que dans la configuration par défaut, les deux sont accessibles uniquement à partir de localhost. Vous devrez fournir des points de terminaison externes et un contrôle d'accès approprié si vous avez l'intention d'y accéder de l'extérieur.

Utiliser des versions instantanées
Si vous voulez installer une version encore en cours de développement (ce qui est habituellement nécessaire si la version diffusée contient des bogues corrigés dans la nouvelle version qui n'est pas encore disponible) et si vous ne voulez pas compiler vos propres binaires, vous pouvez utiliser soit :
 * https://github.com/wikimedia/wikidata-query-deploy - dépôt de déploiement contenant les binaires de production. Nécessite  opérationnel. Copiez-le et faites «   ».
 * les déploiements de versions Archiva sur https://archiva.wikimedia.org/#artifact/org.wikidata.query.rdf/service - choisissez la dernière version, puis Artifacts, et sélectionnez le dernier paquet à télécharger.

Chargement des données
La suite de la procédure d'installation est décrite en détails dans le document Getting Started qui fait partie de la distribution, et qui implique les étapes suivantes :


 * 1) Téléchargez la dernière sauvegarde RDF de https://dumps.wikimedia.org/wikidatawiki/entities/ (elle se termine par  ).
 * 2) Prétraitez les données avec le script   script. Ceci crée un ensemble de fichiers TTL contenant les données prétraitées, avec des noms comme , etc. Voir les options pour le script ci-dessous.
 * 3) Activez le service Blazegraph en exécutant le script.
 * 4) Chargez les données dans le service en utilisant  . Notez que le fait de charger les données est habituellement légèrement plus lent que le prétraitement, donc vous pouvez commencer à charger dès que les premiers fichiers prétraités sont prêts. Le chargement peut être redémarré à partir de n'importe quel fichier en utilisant les options décrites ci-dessous.
 * 5) Après avoir chargé toutes les données, activez le service Updater en utilisant.

Chargement des catégories
Si vous voulez aussi charger les données des catégories, veuillez suivre les étapes suivantes :


 * 1) Créez un espace de noms, par exemple :  :
 * 2) Chargez-y des données :

Notez que ces scripts ne chargent que les données des wikis Wikimedia en fonction de la configuration de Wikimedia. Si vous devez travailler avec d'autres wikis, vous pouvez modifier certaines variables à l'intérieur des scripts.

Scripts
Les scripts utiles suivants font partie de la distribution :

munge.sh
Pré-traiter les données de sauvegarde RDF pour le chargement.

Exemple :

loadData.sh
Charger dans Blazegraph les données traitées. Nécessite d'avoir installé.

Exemple:

runBlazegraph.sh
Activez le service Blazegraph.

Exemple:

Dans le script, il y a deux variables que l'on peut vouloir modifier : Egalement, les variables d'environnement suivantes sont contrôlées par le script (toutes sont optionnelles) :

runUpdate.sh
Exécuter le service Updater.

Il est recommandé que les paramètres des options  et   (ou leur absence) soient les mêmes pour munge.sh et runUpdate.sh, sinon les données pourraient ne pas être mises à jour correctement.

Exemple :

Egalement, les variables d'environnement suivantes sont contrôlées par le script (toutes sont optionnelles) :

Options de Updater
Les options suivantes fonctionnent avec l'application Updater.

Elles doivent être passées au script  comme des options supplémentaires après , par exemple :.

Propriétés configurables
Les propriétés suivantes sont configurables en les ajoutant dans l'exécution des scripts ci-dessus :

Fonctionnalités absentes
Les fonctionnalités ci-dessous ne sont actuellement pas prises en charge :


 * Les redirections ne sont uniquement représentées que par un triplet owl:sameAs, mais n'expriment pas d'autre équivalence dans les données et n'ont pas de prise en charge particulière.

Contacts
Si vous remarquez quelque chose d'anormal avec le service, vous pouvez contacter l'équipe Discovery par courriel sur la liste  ou sur le canal IRC.

Les bogues peuvent aussi être rapportés dans et suivis sur le tableau Discovery Phabricator.

Voir aussi

 * traducteur de syntaxe WDQ vers SPARQL
 * exemples de commande SPARQL
 * l'équipe Discovery
 * notes d'implémentation WDQS
 * introduction à la syntaxe des commandes SPARQL