Wikidata Query Service/User Manual/fr

WDQS, le Service de requête Wikidata, est un progiciel et un service 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 le 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) - ou encore Triplet Sémantique
spo ou "subject, predicate, object" est connu comme un triple, 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:

Grace 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 autamatiquement 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
If you want to install an un-released snapshot version (usually this is necessary if released version has a bug which is fixed but new release is not available yet) and do not want to compile your own binaries, you can use either:
 * https://github.com/wikimedia/wikidata-query-deploy - deployment repo containing production binaries. Needs  working. Check it out and do " ".
 * Archiva snapshot deployments at https://archiva.wikimedia.org/#artifact/org.wikidata.query.rdf/service - choose the latest version, then Artifacts, and select the latest package for download.

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) Download recent RDF dump from https://dumps.wikimedia.org/wikidatawiki/entities/ (the RDF one is the one ending in  ).
 * 2) Pre-process data with the   script. This creates a set of TTL files with preprocessed data, with names like , etc. See options for the script below.
 * 3) Start Blazegraph service by running the   script.
 * 4) Load the data into the service by using  . Note that loading data is usually significantly slower than pre-processing, so you can start loading as soon as several preprocessed files are ready. Loading can be restarted from any file by using the options as described below.
 * 5) After all the data is loaded, start the Updater service by using.

Chargement des catégories
If you also want to load category data, please do the following:


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

Note that these scripts only load data from Wikimedia wikis according to Wikimedia settings. If you need to work with other wiki, you may need to change some variables in the 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
Load processed data into Blazegraph. Requires  to be installed.

Exemple:

runBlazegraph.sh
Run the Blazegraph service.

Exemple:

Inside the script, there are two variables that one may want to edit: Also, the following environment variables are checked by the script (all of them are optional):

runUpdate.sh
Run the Updater service.

It is recommended that the settings for the  and   options (or absence thereof) be the same for munge.sh and runUpdate.sh, otherwise data may not be updated properly.

Exemple :

Also, the following environment variables are checked by the script (all of them are optional):

Options du logiciel de mise à jour
The following options works with Updater app.

They should be given to the  script as additional options after , e.g.:.

Propriétés configurables
The following properties are configurable via adding them to the script run command in the scripts above:

Fonctionnalités absentes
Below are features which are currently not supported:


 * Redirects are only represented as owl:sameAs triple, but do not express any equivalence in the data and have no special support.

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

 * WDQ to SPARQL syntax translator
 * SPARQL Query examples
 * Discovery team
 * WDQS Implementation notes
 * An introduction to SPARQL query syntax