Help:Requêtes intégrées

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 :

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 :

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 '|</tt>' entre eux.
 * Des espaces et des retours à la ligne peuvent être utilisés dans la fonction #ask</tt>, 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</tt> est la suivante :

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

Fonction
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 :

pour afficher la population de Berlin (Résultat: ""). 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  si nécessaire.

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

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: ""). Sans cela, le résultat serait dans une table à deux colonnes et deux lignes:

Ainsi l'avantage d'utiliser  par rapport à   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</tt>:

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</tt> 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 :

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</tt> pour restreindre le nombre maximum de résultats à retourner. Par exemple, la requête:

affiche au plus 3 villes d'Allemagne. Même si vous ne donnez pas de valeur à limit</tt>, 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</tt>. 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:

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</tt>. Si la valeur de searchlabel</tt> 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</tt> a été spécifié.

Un application intéressante de limit</tt> et searchlabel</tt> 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:

displays:. 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

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:

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, &hellip;

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</tt>: 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:


 * ce qui fait que, si rien n'a été trouvé, l'article affichera

Conférences à venir: aucune


 * intro</tt>: 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


 * ce qui fait que, si rien n'a été trouvé, rien en sera imprimé du tout. Remarquez que nous utilisons "&amp;nbsp;" pour encoder le caractère espace final ("&amp;#32;" 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</tt>.

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  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 <tt>sort</tt>, et l'ordre peut être indiqué avec le paramètre <tt>order</tt>. La valeur de <tt>order</tt> devrait être <tt>«ascending»</tt>, <tt>«descending»</tt> ou <tt>«reverse»</tt>, ou une des formes raccourcies <tt>«asc»</tt> et <tt>«desc»</tt>. Vous pouvez aussi initialiser la valeur à <tt>«random»</tt> (ou <tt>«rand»</tt>) 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:

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 <tt>sort</tt> et <tt>order</tt> 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:

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 («<tt>descending</tt>»).

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:

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:

Cette requête rend:

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 <tt>headers</tt> peut être utilisié Trois valeurs sotn possibles :


 * <tt>show</tt>: affiche les étiquettes (défault)
 * <tt>plain</tt>: montre les étiquettes et les entêtes, sous un format de texte simple sans liens (disponible depuis SMW 1.4.3)
 * <tt>hide</tt>: 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 <tt>hide</tt> 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 <tt>mainlabel</tt>. Nomalement, le texte associé à ce paramètre sera simplement utlisé comme entête de la première colonne, par exemple dans la requête:

Cela produira la table:

Le paramètre <tt>mainlabel</tt> 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,

Ce qui produit la table suivante:

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 permettent l'exportation des données du wiki. En plus, d'autres formats définis par les extensions de Semantic Result Formats 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 <tt>searchlabel</tt>.)
 * 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

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

 * Pourquoi les données que je viens d'ajouter n'apparaissent pas dans les requêtes?

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

 * Exclure une page d'une requête intégrée