Help:Requêtes intégrées

From semantic-mediawiki.org
Jump to: navigation, search
Manuel de l'utilisateur de SMW
Présentation
Interfaces de navigation
Spécial:Ask
Spécial:Browse
Recherche sémantique
Sélection des pages
Comparateurs stricts
Affichage de l'information
Formats des résultats
Requêtes intégrées
Concepts
Déduction
Édition
Propriétés et types
Unités configurables
Modèles sémantiques
Liens de service
Web sémantique
Export OWL/RDF
Outils externes
Importation de vocabulaire
Importation d'ontologie
Manuel admin SMW

Semantic MediaWiki comporte un langage de requêtes de recherche sémantique qui permet aux utilisateurs de rechercher directement certaines informations dans le wiki. Les lecteurs qui ne souhaitent pas apprendre la syntaxe des requêtes peuvent cependant en bénéficier : les requêtes intégrées insèrent directement à l'intérieur des pages, les résultats de la recherche. Ainsi, les requêtes créées par une poignée de rédacteurs peuvent être utiles à beaucoup de lecteurs.

Les requêtes intégrées sont similaires aux autres fonctions sémantiques et peuvent donc être désactivées sur certains sites pour garantir des performances satisfaisantes. Parce que les requêtes intégrées utilisent les méchanismes de cache déja existants dans MediaWiki, la plupart des requêtes de pages ayant ce type de contenu dynamique, peuvent être exécutées sans impacter sur les performances.

Fonction #ask

La manière d'écrire une requête intégrée de base est d'utiliser la fonction d'analyse #ask. La chaîne de recherche (voir la sélection des pages pour la syntaxe) ainsi que les instructions d'affichage des sorties sont directement passés en paramètre comme dans l'exemple suivant :

{{#ask:
 [[Category:City]]
 [[Located in::Germany]] 
 |?Population 
 |?Area#km² = Size in km²
}}

Ici nous demandons toutes les villes situées en Allemagne, avec deux instructions supplémentaires pour la sortie des résultats (l'une simple et l'autre avec des iniitalisations supplémentaires). Ceci fournit le résultat suivant sur une page :

 PopulationSize in km²
Berlin3,520,061891.85 km²
344.343 sqmi
Cologne
Frankfurt679,664248.31 km²
95.872 sqmi
Munich1,353,186310.43 km²
119.857 sqmi
Stuttgart606,588207.36 km²
80.062 sqmi
Würzburg

Il est d'usage de mettre la requête en tant que premier paramètre derrière #ask:. Tous les autres paramètres sont séparés par |, tout comme dans les autres fonctions d'analyse. Le format exact de la requête intégrée n'est pas essentiel, mais il est de bon goût d'utiliser des retours à la ligne pour la rendre plus lisible aux autres éditeurs. Comme pour tous les modèles, on met en pratique un paramètre par ligne, en commençant par | .

Remarques que tous les arguments de la fonction #ask: sont ignorés dans l'analyse de la page, de là l'exemple ci-dessus ne rajoute pas de catégorie ni d'annotation de propriété «located in» pour cette page. Les choses à noter en plus sont:

  • La barre verticale '|' est le symbole utilisé pour séparer les conditions de la propriété à afficher.
  • Les conditions d'affichage sont un argument unique de la fonction #ask, il n'y a donc pas de symbole '|' entre eux.
  • Des espaces et des retours à la ligne peuvent être utilisés dans la fonction #ask , SMW est très permissif là-dessus.
  • Le format d'affichage des résultats change si vous demandez l'affichage de propriétés supplémentaires. SMW choisit un format par défaut approprié pour les résultats de la requête, mais vous avez également le control détaillé de l'apparence des résultat de la requête.

Avec les connaissances de base sur la chaîne de recherche et les instructions d'affichage nous en avons assez pour rédiger différents types de requêtes. Mais il y a plétore de cas où la sortie des résultats dans un tableau standard ne serait pas le meilleur choix, ou si on voulait disposer de fonctions supplémentaires (comme le nombre maximum de résultats à afficher). Pour cette raison, les requêtes intégrées ont un nombre de paramètres possibles supplémentaires que l'on peut utiliser pour contrôler l'apparence en détails. Pour cela, la syntaxe générale de #ask est la suivante :

{{#ask: argument 1 | argument 2 | … }}

Cette page en majeure partie explique les différents arguments que l'on peut utiliser dans les requêtes intégrées.

Fonction #show

Un usage commun des requêtes est d'afficher la valeur d'une propriété seule pour une page donnée. Par exemple, on pourrait insérer la population de Berlin dans un article, et utiliser une requête au lieu de faire une recopie manuelle pour arriver au même résultat. SMW fournit un raccourci spécial pour rendre plus faciles de telles requêtes. On peut écrire par exemple :

{{#show: Berlin | ?population }}

pour afficher la population de Berlin (Résultat: "3,520,061"). Sinon, la fonction s'utilise comme une requête intégrée, et tous les paramètres disponibles pour les requêtes intégrées, le sont également pour #show: si nécessaire.

La requête ci-dessus écrite avec #ask devient :

{{#ask: [[Berlin]] | ?population= | mainlabel=- }}
Ici le signe "=" ajouté avec la propriété recherchée "?population" supprime l'affichage de nom de la propriété et le paramètre "mainlabel=" suivi du symbole "-" supprime la première colonne de résultats et le nom de la colonne (Résultat: "3,520,061"). Sans cela, le résultat serait dans une table à deux colonnes et deux lignes:
 Population
Berlin3,520,061

Ainsi l'avantage d'utiliser #show par rapport à #ask pour récupérer les valeurs d'une seule propriété devient visible.

Paramètres standards des requêtes intégrées

En général, une requête intégrée est une requête pour trouver un nombre de pages répondant à certaines conditions. Cette requête doit répondre à trois conditions :

  1. Quelles pages sont demandées ? (voir sélectionner des pages)
  2. Quelles informations sur ces pages doivent être affichées ? (voir instructions d'affichage)
  3. Comment doivent être formatés les résultats à l'intérieur de la page ? (voir formats de résultat)

Les deux premiers points sont expliqués dans les pages respectives du manuel Help:Recherche sémantique. Le troisième point est important afin de pouvoir commodément incorporer les résultats de requêtes dans les pages, bien qu'il soit largement indépendant des deux premiers. Sans définitions supplémentaires, les requêtes fournissent souvent des tables comme ci-dessus ou des simples listes (s'il n'y a pas d'instructions additionelles de mise en forme). Un exemple d'autre format possible est la liste avec puces que l'on peut créer avec le paramètre format=ul:

{{#ask:
 [[Category:City]]
 [[Located in::Germany]] 
 |?Population
 |format=ul
}}

Qui produira la sortie suivante :


SMW implémente une grande variété de formats de sortie pour les requêtes intégrées, et vous permet ensuite de contrôler l'affichage des résultats en utilisant un modèle Mediawiki. Le paramètre format est l'in de sparamètres les plus importants pour sélectionner l'apparence des résultats de la requête. Voir Formats des résultats.

La table suivante donne un aperçu des paramètres de base communs qui peuvent être utilisés dans toutes les requêtes :

Paramètre Valeurs possibles Description
format un nom de format format d'affichage choisi pour les résultats; certains formats autorisent des paramètres supplémentaires (voir Help:Result formats)
limit nombre non négatif nombre maximal de pages sélectionnées (dans le cas d'une table: nombre de lignes )
offset nombre à partir de où commencer
sort nom de propriété ou liste de noms de propriétés séparés par , noms des propriétés à utiliser pour trier les recherches, une valeur vide signifie la colonne principale de résultat (voir Help:Selecting pages)
order ascending/asc, descending/desc/reverse, random/rand
ou une liste de ceux-ci si plus d'une propriété est utilisée pour le classement
définit la manière selon laquelle les résultats seront classés, ascending par défaut, si le paramètre "sort" n'est pas mentionné l'ordre de classement des résultats est celui de la colonne principale (voir Help:Selecting pages)
align right, center, left définit la manière d'aligner les résultats, applicable simplement pour les formats de résultat table et broadtable (voir Help:Result formats)
headers show, plain, hide affiche les entêtes (avec les liens), affiche les entêtes (juste le texte) ou bien les masque. show par défaut
mainlabel texte simple titre de la première colonne (celle qui contient les titres des pages), par défaut pas de titre; mettre - pour empêcher l'impression des titres de pages
index nombre définit quelle valeur à l'intérieur d'un enregistrement doit être affichée, applicable uniquement aux propriétés de type Enregistrement
link none, subject, all définit les articles dont le noms est un hyperlien, all normalement par défaut. Voir aussi les exemples de pages.

NoteNote:  les liens peuvent aussi être controlés pour des affichages individuels en utilisant le format simple de sortie comme décrite dans Affichage des informations.

default texte simple c'est ce qui sera imprimé si, pour n'importe quelle raison, la requête ne revoie pas de résultat
intro texte simple texte initial qui précède ce qui sera affiché, si au moins un résultat existe
outro texte simple texte ajouté après ce qui doit être affiché, si au moins un résultat existe
searchlabel texte simple texte pour continuer la recherche (par défaut «… résultats suivants»)

En plus, cetains formats ont leurs propres paramètres qui controlent des aspects spécifiques du format. Ces initialisations spéciales sont décrites dans la documentation de chaque format.


Limitation des résultats et liens vers les résultats suivants

Vous pouvez initialiser le paramètre limit pour restreindre le nombre maximum de résultats à retourner. Par exemple, la requête:

{{#ask:
 [[Category:City]]
 [[Located in::Germany]]
 |limit=3
}}

affiche au plus 3 villes d'Allemagne. Même si vous ne donnez pas de valeur à limit, SMW applique toujours une limite sur le nombre de résultats retournés. Cela dépend du site, il devrait être possible d'augmenter le nombre de résultats affichés en spécifiant une plus grande valeur pour limit. Néanmoins, il existe habituellement une limite maximum qui ne peut être dépassée, initialisée par l'administrateur wiki et basée sur des considérations de performance. Pour les détails, voir Help:Configuration.

En lançant la requête ci-dessus nous obtenons: Berlin, Cologne, Frankfurt... further results

Ceci montre que si une requête n'affiche pas tous les résultats à cause d'une limitation, elle affichera normalement un lien vers «résultats suivants». Le texte de ce lien peut être modifié en initialisant le paramètre searchlabel. Si la valeur de searchlabel est vide, alors il n'y a pas de lien vers les résultats suivants. Certains formats de sortie (voir ci-après) n'affichent pas le lien de recherche, ou bien l'affichent seulement si un searchlabel a été spécifié.

Un application intéressante de limit et searchlabel est pour afficher seulement un lien vers les résultats d'une recherche, sans afficher aucun résultat en ligne. Vous provoquerez ceci en spécifiant une limite de «0» ou «-1». Par exemple, la requête:

{{#ask: [[Category:City]] | limit=0 | searchlabel=Cliquez pour afficher la liste des villes }}

displays: Cliquez pour afficher la liste des villes. Ce line n'apparaitra seulement que s'il existe des résultats. En d'autres termes, SMW va encore executer la requête pour voir s'il y a encore des résultats. Si cela l'est pas nécessaire, ou bien si dans tous les cas un lien est cassé, on peut utiliser la limite «-1». SMW imprimera alors seulement un lien vers les résultats suivants, même s'il n'y a pas de résultats. Cela économise un peu de temps d'exécution sur le serveur.

La requête

{{#ask: [[Category:City]] | limit=5 | searchlabel= }}

au contraire montrera une liste maximale de cinq villes, mais sans lien vers les résultats suivants, même s'il y en a. Ce qui donne:

2166320938 5cfc9ec72a z.jpg, 220px-Cherry Blossoms and Washington Monument.jpg, 3363305632 c136da22e7 z.jpg, 3430830083 00768b46a9 z.jpg, 4005745212 1e91b077cf z.jpg

Customiser le lien vers les résultats suivant

Depuis SMW 1.9.0 il est possible d'assigner une feuille de style CSS individuelle à chaque lien "résultats suivants" actif des formats de résultat. Voir la page d'aide sur mise en forme des résultats suivants pour plus d'informations sur ce sujet.

Introduction et texte par défaut

Si aucun article ne satisfait aux conditions d'une requête, rien d'est affiché. C'est quelquefois un comportement utile, mais souvent certains textes devraient être affichés ou pas selon que la requête ramène des résultats ou non. Par exemple, on peut vouloir que la requête affiche une sortie de la forme suivante:

Conférences à venir: SMWCon Spring 2013, SMWCon Fall 2013, …

où la liste des conférences est générée par une requête appripriée. Si la requête (pour quelque raison que ce soit) devait ne rien retourner, la page ressemblerait à

Conférences à venir: 

ce qui n'est pas souhaité. Deux paramètres existent pour empêcher cela.

  • default: ce paramètre peut être initialisé avec un texte par défaut qui sera retourné quend la requête n'a rien trouvé. Dans l'exemple ci-dessus, on aurait probablement quelque chose comme
Conférences à venir: {{#ask: ... | default=aucune}}
ce qui fait que, si rien n'a été trouvé, l'article affichera
Conférences à venir: aucune
  • intro: ce paramètre spécifie un texte qui devrait être inséré au début des résultats de la requête, mais seulement si un ou plusieurs résultats existent. Dans l'exemple ci-dessus, on aurait pu écrire
{{#ask: ... | intro=Conférences à venir: }}
ce qui fait que, si rien n'a été trouvé, rien en sera imprimé du tout. Remarquez que nous utilisons " " pour encoder le caractère espace final (" " aurait aussi convenu), et ceci parce que l'espace standard est supprimé au début et en fin des paramètres de chaîne de caractères pour les fonctions de l'analyseur.

Les deux solutions ci-dessus afficheront la sortie souhaitée si la requête ramène quelquechose. Il est également possible de combiner les deux paramètres si on le souhaite. Les paramètres peuvent aussi contenir des directives MediaWiki, comme des liens ou des modèles, tant que cela ne perturbe pas MediaWiki pour identifier les fonctions #ask .

Remarquez aussi que si l'ensemble des pages sélectionnées dans une requête est vide, on n'affichera rien (pas d'entête, pas de blancs). Cela peut être aussi utile pour «cacher» des requêtes qui n'ont pas de raison d'être. Néanmoins, il n'est pas recommandé d'avoir un trop grand nombre de requêtes par page, en se basant sur le fait que cela ne peut pas faire de mal car rien n'est affiché. Bien sûr, la réponse des requêtes nécessite beaucoup de ressources et devrait être faite seulement si le but est clairement défini.

L'utilisation des textes par défaut pour les requêtes est aussi une bonne habitude en général, car il peut arriver qu'une requête ne puisse plus rien trouver dans le futur, par exemple si le wiki change la manière d'organiser ses données. De telles requêtes qui ont marché correctement durant un temps peuvent avoir été oubliées à tel point que personne n'avait remarqué que la requête continuait à s'exécuter pour ne rien afficher.

Remarque que si vous voulez n'afficher qu'une suele valeur de propriété pour une seule page (voir #show), le paramètre default ne marche pas parce que dans ce cas vous n'interrogez pas plusieurs pages.

Classer les résultats

Nous avons expliqué dans Help:Selecting pages que les résultats d'une requête peuvent être rangés selon une ou plusieurs propriétés. Comme nous le disons ici, Special:Ask possède des champs supplémentaires en entrée pour spécifier les propriétés servant au tri et au classement. Dans les requêtes intégrées, les propriétés pour le tri sotn définies avec le paramètre sort, et l'ordre peut être indiqué avec le paramètre order. La valeur de order devrait être «ascending», «descending» ou «reverse», ou une des formes raccourcies «asc» et «desc». Vous pouvez aussi initialiser la valeur à «random» (ou «rand») pour classer les résultats d'une manière aléatoire (ce critère peut être désactivé par l'administrateur du site, voir Configuration). Un exemple est fourni par la requête suivante et consiste à trouver les trois plus grandes villes d'Allemagne:

{{#ask:
 [[Category:City]]
 [[Located in::Germany]]
 |?Population
 |sort=Population
 |order=descending
 |limit=3
}}

Comme nous le voyons dans Help:Selecting pages, les conditions de tri peuvent imposer des restrictions sur l'ensemble des valeurs des résultats de la requête. Dans le cas ci-dessus, seules les villes allemandes pour lesquelles la population est définie sont prises en compte. Si plus d'une proriété est utilisée pour le tri, les paramètres sort et order peuvent être positionnés pour respectivement les listes des noms de propriétés et les ordres, et séparés par des virgules. Exemple:

{{#ask:
 [[Category:City]]
 [[Located in::Germany]]
 |?State
 |?Population
 |sort=State,Population
 |order=ascending,descending
}}

Cette requête est sensée retourner toutes les villes allemandes pour lesquelles un état et une population ont été définis. Ces résultats seront classés selon le nom de l'état dans lequel elles se trouvent (classés alphabétiquement). Les villes qui se trouvent dans le même état seront classées par population, la plus grande d'abord («descending»).

Il est aussi possible de définir explicitement la colonne principale du résultat qui sera utilisée pour le tri quand plus d'une condition de tri devrait être utilisée. Ceci est fait soit en préfixant ou en postfixant par un point, une directive vide. Exemple:

{{#ask:
 [[Category:City]]
 [[Located in::Germany]]
 |?State
 |?Population
 |sort=State,
 |order=ascending,descending
}}

Cette requête retournera toutesd les ville allemandes pour lesquelles un été a été spécifié. Ces résultats seront ordonnés selon le nom de l'état où elles se trouvent (trié alphabétiquement). Les villes qui sont situées dans le même état seront classées alphabétiquement (descending) par leur nom.

Configuration du texte des étiquettes et des tables

Les requêtes qui retournent plus que juste les articles sélectionnés (par exemple; la population de l'exmple ci-dessus) afficheront des étiquettes qui décrivent les différents champs de sortie. Par défaut, l'étiquette affiche simplement le nom de la propriété demandée, ou le text «Category» si des catégories sont affichées. Les étiquettes pour les propriétés s'affichent normalement sous la forme d'un lien vers les pages respectives dans l'espace de noms de la propriété "Property:" .

Dans le format table , les étiquettes apparaissent comme les entêtes des colonnes. Dans les autres formats, les étiquettes peuvent apparaitre juste avant les champs de sortie. Les textes utilisés pour ces étiquettes peut être controlé comme expliqué dans Help:Displaying information, en utilisant le symbole égal après les valeurs à afficher. Exemple:

{{#ask:
 [[Category:City]]
 [[Population::+]]
 [[Area::+]] 
 |?Population=
 |?Area#km²=Size in km²
 |?Category=Category memberships
 |format=table
 |default=nothing found in Category:City
}}

Cette requête rend:

  Size in km²Category memberships
Amsterdam783,364219 km²
84.556 sqmi
City
Sample pages
Europe
Belleville43,76560 km²
23.166 sqmi
City
Sample pages
Berlin3,520,061891.85 km²
344.343 sqmi
City
Sample pages
Frankfurt679,664248.31 km²
95.872 sqmi
City
Sample pages
Karlsruhe294,761173.46 km²
66.973 sqmi
City
Sample pages
London7,825,2001,706.8 km²
658.995 sqmi
City
Sample pages
Munich1,353,186310.43 km²
119.857 sqmi
City
Sample pages
Paris2,234,105105.4 km²
40.695 sqmi
City
Sample pages
Porto237.58441.66 km²
16.085 sqmi
City
Sample pages
Rome2,761,4771,285.31 km²
496.258 sqmi
City
Sample pages
San Diego1,307,402963.6 km²
372.046 sqmi
City
Sample pages
Stuttgart606,588207.36 km²
80.062 sqmi
City
Sample pages
Sydney4,575,5322,058 km²
794.594 sqmi
City
Sample pages
Warsaw1,720,398516.9 km²
199.575 sqmi
City
Sample pages

Il est possible d'utiliser des étiquettes vides ou de ne pas définir d'étiquettes pour l'affichage de sortie dans une colonne de résultats. Dans les tables, néanmoins, l'entête des tableaux sera encore montrée même si tous les affichages utilisent des étiquettes vides. Pour enlever complètement l'entête d'une table, le paramètre headers peut être utilisié Trois valeurs sotn possibles :

  • show: affiche les étiquettes (défault)
  • plain: montre les étiquettes et les entêtes, sous un format de texte simple sans liens (disponible depuis SMW 1.4.3)
  • hide: masque toutes les étiquettes et les entêtesd de tales

Cette initialisation marche pour les tables et pour les autres types de sorties. Dans ce dernier cas, la valeur hide va masquer toutes les étiquettes, même s'elles ont un texte non vide initialisé dans la requête.

Modifier la première colonne de résultats

La plupart des requêtes affichent par défaut les pages actuelles de résultat à la première position du résultat, par exemple dans la première colonne d'un tableau. L'ent^tet de cette colonne est habituellement vide. Pour modifer son contenu, ou pour cacher complètement la première colonne, on peut utiliser le paramètre mainlabel. Nomalement, le texte associé à ce paramètre sera simplement utlisé comme entête de la première colonne, par exemple dans la requête:

{{#ask:
 [[Category:City]]
 [[Located in::Germany]]
 |mainlabel=City
 |?Population=Nombre d'habitants
 |limit=3
}}

Cela produira la table:

CityNombre d'habitants
Berlin3,520,061
Cologne
Frankfurt679,664
... further results

Le paramètre mainlabel peut également être utilisé pour masquer complètrement la première colonne. Cela se produit si al valeur de ce paramètre est mise à «-» (signe moins). Pour insérer la liste des résultats principaux à une autre position, l'instruction d'impression «?», c'est à dire le point d'interrogation tout seul, peut être utilisé. Par exemple, en modifiant l'exemple ci-dessus pour afficher la ville après Population,

{{#ask:
 [[Category:City]]
 [[Located in::Germany]]
 |?Population=Nombre d'habitants
 |?=City
 |mainlabel=-
 |limit=3
}}

Ce qui produit la table suivante:

Nombre d'habitantsCity
3,520,061Berlin
Cologne
679,664Frankfurt
... further results

Format des résultats

Le paramètre format détermine la manière dont les résultats d'une requête sont affichés à l'intérieur d'un l'article. Pour plus d'informations voir la page Result formats.

Exporter les résultats d'une requête

Certains formats de résultats de SMW (csv, csv, dsv, dsv, feed, json, json, rdf, rdf) permettent l'exportation des données du wiki. En plus, d'autres formats définis par les extensions de Semantic Result Formats (bibtex, excel, icalendar, vcard) autorisent également l'exportation de données. Ces formats diffèrent des autres formats pour deux raisons:

  1. au lieu d'afficher des données sur la page, ils produisent seulement un lien vers Special:Ask, qui a son tour va afficher les données sous une forme téléchargeable. (Ce lien est similaire au lien «résultats suivants», bien qu'il utilise un texte par défaut différrent, comme «RSS»; il est possible de changer le texte du lien à l'aide du paramètre searchlabel.)
  2. Ils utilisent les formats fixes standards pour l'exportation (non fixe et format libre). C'est pourquoi, pour les formats différents de CSV et DSV, il faut expliquer à quelles parties du format d'exportation des données, les propriétés du wiki appartiennent.

Le second point nécessite de faire le lien entre les instructions d'affichage (propriétés) avec les champs de données disponibles dans le format d'exportation.La vCard est un format de données qui encode plusieurs types de données de contact sur une personne, mais il ne peut représenter des données arbitraires. Pour spécifier quelle propriété wiki appartient à quel champ de données, l'étiquette de la propriété affichée est utilisée. Par exemple, vCard supporte (parmi plein d'autres) les champs de données «firstname», «lastname» et «homepage». Une requête pourrait contenir

{{#ask:
 [[Category:Person]]
 |?Firstname
 |?Lastname
 |?Url = homepage
 |format=vcard 
}}

Ici le wiki aurait des propriétés appelées «firstname» et «lastname», mais la page principale d'une personne est rangée dans une propriété appelée «url». L'étiquette «homepage» est données à cette dernière si bien que vCard reconnait la signification spéciale de cette propriété. Avec cette méthode, les wikis peuvent utiliser des noms de propriété arbitraires (dans n'importe quelle langue) ou encore exporter sous le format standard. Pour les détails concernant les champs de données, voir les pages des formats ci-dessus.

Mise à jour des requêtes intégrées

Eviter l'auto-référencement

Voir Help:Self-Referencing pour des informations sur la manière dont l'utilisation des requêtes intégrées concernant une propriété définie sur la même page peut provoquer un comportement inattendu.

Aide supplémentaire


Cette page de documentation concerne toutes les versions de SMW depuis la 1.7.0 jusqu'à la version la plus récente.
      Autres langues : deenruzh-hans

Help:Inline queries fr 1.7.0