Wikidata Query Service/User Manual/fr

WDQS, le Service de requête Wikidata, est un progiciel et un service public conçu pour fournir un point d'accès SPARQL qui vous permet 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 surveiller si vous utilisez le service.

Vous pouvez consulter des exemples de requêtes SPARQL sur la page 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 les petites 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 SPO (sujet, prédicat, objet) - dénommé Triplet Sémantique
SPO ou "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), le prédicat "La capitale est" ( P36), et un objet "Washington DC" ( Q61). Cette déclaration peut être représentée comme 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" - 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 City» est vrai - mais seulement dans le contexte historique de l'année 1790. WDQS utilise des "rangs" pour déterminer quelles déclarations devraient ê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 ont trois valeurs: DC, Philadelphie et New York. Et chacune de ces valeurs a des "qualificatifs" - des informations supplémentaires, telles que les dates de début et de fin, qui affine 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.

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 d'un triple (spo) même en utilisant des triples comme objets ou sujets d'autres triples!

Notions de base - Comprendre les préfixes
Les sujets et les prédicats (première et seconde valeurs du triple) 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 triple) peut être un URI ou un littéral, par ex. 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 de sortie:

Extensions
Le service prend en charge les extensions suivantes aux fonctionnalités SPARQL standard:

Service d'étiquette
Vous pouvez récupérer l'étiquette, l'alias ou la description des entités que vous interrogez, avec le langage de secours, 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 et automatique.

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

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


 * Si une variable non positionnée dans  est nommée , WDQS produit le libellé  pour l'entité de la variable.
 * Si une variable non positionnée dans   est nommée , WDQS produit l'alias  pour l'entité de la variable.
 * Si une variable non positionnée dans   est nommée , then WDQS WDQS produit la description  pour l'entité de la variable.

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

Vous spécifiez vos ou votre langue(s) préféré(s), séparés par des virgules. WDQS envisage les langues dans l'ordre que vous avez spécifié. Si il n'existe un libellé dans aucune des langues mentionnées, l'identifiant-Q de l'entité (sans préfixe) est positionné en tant que 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, qui montre la liste des président(e)s des États-Unis et leurs époux(ses)

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

En mode manuel, vous associez explicitement les libellés des variables à l'intérieur du code d'appel au service de libellisation, néamoins WDQS fournit la résolution de langues et les replis de langues.

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 du centre de certaines zones limites.

Recherche autour du point
Exemple:

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

Recherche à l'intérieur d'une région (boîte)
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 ensembles, 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 diagonales de la boîte, les coins en sont déduits en conséquences.

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

Fonctions relatives aux fragments de coordonnées
Les fonctions,   et   décomposent les coordonnées et retournent 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 pourcent). Cela peut être nécessaire lorsque vous convertissez des titres Wikipedia (qui sont encodés), vers des chaiês actuelles. Cette fonction est l'opposé 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 de les spécifier explicitement.

Dates étendues
Le service prend en charge les valeurs de dates du type  dans un intervalle d'environ 290B 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 de 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 qui sont documentés sur le wiki Blazegraph, comprenant BFS, le plus court chemin, les implémentations de CC et 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 différents aspects du moteur.

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 que les points de terminaison fédérés servent, utilise des ontologies qui peuvent être très différentes de celles de Wikidata. Veuillez vous référer aux 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 de terminaison public est limité à 60 secondes. C'est vrai à la fois pour l'IHM et pout le point de terminaison SPARQL public. Si vous avez besoin de requêtes qui durent plus longtemps, veuillez contacter l'équipe Discovery.

Interface graphique (GUI)
L’interface de la page d’accueil du 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 URI unique qui peut-être ajoutée à vos marque-pages ou sauvegardée pour une réutilisation future. Aller à ce marque page va afficher la requête dans la fenêtre d’édition de requête, mais ne lancera pas le calcul des résultats — vous aurez encore à cliquer sur « lancer la requête » pour ça.

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

Le bouton Ajoutez les préfixes génère une en-tête contenant les préfixes de requête SPARQL standards. La liste complète des préfixes utilisable 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 de lui-même.

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

Visualisations par défaut

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

Si vous lancez la requête dans l’interface de WDQS GUI, vous pouvez choisir un type de visualisation pour vos résultat en ajoutant 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 le le coprs 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é en format XML par défaut, ou alors en JSON dans le cas ou soit le paramètre  est présent dans l’url, soit si l’en-tête   est fournie avec la requête HTTP.

Je 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 retour suivant sont disponibles à l’heure actuelle par le point d’accès SPARQL :

Limites des requêtes
Il existe une limite dure de temps d’exécution pour les requêtes, qui est 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 dont le nombre excède les limites ci-dessus sont restreints avec le code HTTP. Utilisez  header pour voir quand la requête pourra être répétée. Si le client ignore les codes 429 et continue à produire des requêtes au dela de la limite, il peut être bloqué temporairement du service. Les clients qui ne respectent pas la politique de l'agent utilisateur peuvent être bloqués complètement – assurez-vous d'envoyer une bonne entê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 :

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.

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/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 dans l'espace de noms.

Le point de terminaison SPARQL pour y accéder est : https://query.wikidata.org/bigdata/namespace/dcatap/sparql

La source des donnée 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:. Exemples 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é, néanmoins plusieurs formats de données sont disponibles, définis par l'entête HTTP.

Les données sont retournées dans des pages, dont la taille pages est 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 le 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 .war, les bibliothèques nécessaires à l'exécution le service de mise à jour pour récupérer les données récentes du site wikidata, les scripts pour faciliter différentes tâches, et l'IHM dans le sous-répertoire. Si vous voulez utiliser l'IHM, vous devrez configurer votre serveur HTTP et le 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 les versions snapshot
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 dan le nouvelle version mais 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 du vidage 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 du logiciel de mise à jour
Les options suivantes fonctionnent avec l'application Updater.

Ils doivent être passés 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 fonctionalités ci-dessous sont actuellement non prises en charge :


 * Les redirections ne sont uniquement représentées que par un triplet owl:sameAs, mais n'exprime 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