diff -r 058bb3dc685f -r 0b59724cb3f2 cubicweb/web/wdoc/tut_rql_fr.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/cubicweb/web/wdoc/tut_rql_fr.rst Sat Jan 16 13:48:51 2016 +0100 @@ -0,0 +1,268 @@ +.. -*- coding: utf-8 -*- + +Apprenons RQL par la pratique... + +.. contents:: + + +Introduction +------------ + +RQL est assez proche par sa syntaxe et ses principes du langage de requête des +bases de données relationnelles SQL. Il est cependant plus intuitif et mieux +adapté pour faire des recherches avancées sur des bases de données structurées +par un schéma de données. On retiendra les points suivants : + +* RQL est un langage mettant l'accent sur le parcours de relations. +* Les attributs sont considérés comme des cas particuliers de relations. +* RQL s'inspire de SQL mais se veut plus haut niveau. +* Une connaissance du schéma définissant l'application est nécessaire. + +Pour s'en servir, il convient de connaître les règles de base du langage RQL, +mais surtout d'avoir une bonne vision du schéma de données de l'application. Ce +schéma est toujours disponible dans l'application par le lien `schéma`, dans la +boîte affichée en cliquant sur le lien de l'utilisateur connectée (en haut à droite). +Vous pouvez également le voir en cliquant ici_. + +.. _ici: ../schema + + +Un peu de théorie +----------------- + +Variables et typage +~~~~~~~~~~~~~~~~~~~ +Les entités et valeurs à parcourir et / ou séléctionner sont représentées dans +la requête par des *variables* qui doivent être écrites en majuscule + +Les types possibles pour chaque variable sont déduits à partir du schéma en +fonction des contraintes présentes dans la requête. + +On peut contraindre les types possibles pour une variable à l'aide de la +relation spéciale `is`. + +Types de bases +~~~~~~~~~~~~~~ +* `String` (litéral: entre doubles ou simples quotes) +* `Int`, `Float` (le séparateur étant le '.') +* `Date`, `Datetime`, `Time` (litéral: chaîne YYYY/MM/DD[ hh:mm] ou mots-clés + `TODAY` et `NOW`) +* `Boolean` (mots-clés `TRUE` et `FALSE`) +* mot-clé `NULL` + +Opérateurs +~~~~~~~~~~ +* Opérateurs logiques : `AND`, `OR`, `,` +* Opérateurs mathématiques: `+`, `-`, `*`, `/` +* Operateur de comparaisons: `=`, `<`, `<=`, `>=`, `>`, `~=`, `LIKE`, `IN` + + * L'opérateur `=` est l'opérateur par défaut + + * L'opérateur `LIKE` / `~=` permet d'utiliser le caractère `%` dans une chaine + de caractère pour indiquer que la chaîne doit commencer ou terminer par un + préfix/suffixe :: + + Any X WHERE X nom ~= 'Th%' + Any X WHERE X nom LIKE '%lt' + + * L'opérateur `IN` permet de donner une liste de valeurs possibles :: + + Any X WHERE X nom IN ('chauvat', 'fayolle', 'di mascio', 'thenault') + +Grammaire des requêtes de recherche +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:: + + [DISTINCT] V1(, V2)* + [GROUPBY V1(, V2)*] [ORDERBY ] + [WHERE ] + [LIMIT ] [OFFSET ] + +:type d'entité: + Type de la ou des variables séléctionnées. + Le type spécial `Any`, revient à ne pas spécifier de type. +:restriction: + liste des relations à parcourir sous la forme + `V1 relation V2|` +:orderterms: + Définition de l'ordre de sélection : variable ou n° de colonne suivie de la + méthode de tri (`ASC`, `DESC`), ASC étant la valeur par défaut + +note pour les requêtes groupées (i.e. avec une clause `GROUPBY`) : +toutes les variables sélectionnées doivent être soit groupée soit +aggrégée + + +Schéma +------ + +Nous supposerons dans la suite de ce document que le schéma de l'application est +le suivant. Les différentes entités disponibles sont : + +:Personne: + :: + + nom (String, obligatoire) + datenaiss (Date) + + +:Societe: + :: + + nom (String) + + +:Note: + :: + + diem (Date) + type (String) + + +Et les relations entre elles : :: + + Person travaille_pour Societe + Person evaluee_par Note + Societe evaluee_par Note + + +Méta-données +~~~~~~~~~~~~ +Tous les types d'entités ont les métadonnées suivantes : + +* `eid (Int)`, permettant d'identifier chaque instance de manière unique +* `creation_date (Datetime)`, date de création de l'entité +* `modification_date (Datetime)`, date de dernière modification de l'entité + +* `created_by (CWUser)`, relation vers l'utilisateur ayant créé l'entité + +* `owned_by (CWUser)`, relation vers le où les utilisateurs considérés comme + propriétaire de l'entité, par défaut le créateur de l'entité + +* `is (Eetype)`, relation spéciale permettant de spécifier le + type d'une variable. + +Enfin, le schéma standard d'un utilisateur est le suivant : + +:CWUser: + :: + + login (String, obligatoire) + password (Password) + firstname (String) + surname (String) + + +L'essentiel +----------- +0. *Toutes les personnes* :: + + Personne X + + ou :: + + Any X WHERE X is Personne + + +1. *La societé nommé Logilab* :: + + Societe S WHERE S nom 'Logilab' + + +2. *Toutes les entités ayant un attribut nom commençant par 'Log'* :: + + Any S WHERE S nom LIKE 'Log%' + + ou :: + + Any S WHERE S nom ~= 'Log%' + + Cette requête peut renvoyer des entités de type personne et de type + société. + + +3. *Toutes les personnes travaillant pour la société nommé Logilab* :: + + Personne P WHERE P travaille_pour S, S nom "Logilab" + + ou :: + + Personne P WHERE P travaille_pour S AND S nom "Logilab" + + +4. *Les societés nommées Caesium ou Logilab* :: + + Societe S WHERE S nom IN ('Logilab','Caesium') + + ou :: + + Societe S WHERE S nom 'Logilab' OR S nom 'Caesium' + + +5. *Toutes les societés sauf celles nommées Caesium ou Logilab* :: + + Societe S WHERE NOT S nom IN ('Logilab','Caesium') + + ou :: + + Societe S WHERE NOT S nom 'Logilab' AND NOT S nom 'Caesium' + + +6. *Les entités évalués par la note d'identifiant 43* :: + + Any X WHERE X evaluee_par N, N eid 43 + + +7. *Toutes les personnes triés par date de naissance dans l'ordre antechronologique* :: + + Personne X ORDERBY D DESC WHERE X datenaiss D + + On note qu'il faut définir une variable et la séléctionner pour s'en + servir pour le tri. + + +8. *Nombre de personne travaillant pour chaque société* :: + + Any S, COUNT(X) GROUPBY S WHERE X travaille_pour S + + On note qu'il faut définir une variable pour s'en servir pour le + groupage. De plus les variables séléctionnée doivent être groupée + (mais les variables groupées ne doivent pas forcément être sélectionnées). + + + +Exemples avancés +---------------- +0. *Toutes les personnes dont le champ nom n'est pas spécifié (i.e NULL)* :: + + Personne P WHERE P nom NULL + + +1. *Toutes les personnes ne travaillant pour aucune société* :: + + Personne P WHERE NOT p travaille_pour S + + +2. *Toutes les sociétés où la personne nommée toto ne travaille pas* :: + + Societe S WHERE NOT P travaille_pour S , P nom 'toto' + + +3. *Toutes les entités ayant été modifiées entre aujourd'hui et hier* :: + + Any X WHERE X modification_date <= TODAY, X modification_date >= TODAY - 1 + + +4. *Toutes les notes n'ayant pas de type et à effectuer dans les 7 jours, triées par date* :: + + Any N, D where N is Note, N type NULL, N diem D, N diem >= TODAY, + N diem < today + 7 ORDERBY D + + +5. *Les personnes ayant un homonyme (sans doublons)* :: + + DISTINCT Personne X,Y where X nom NX, Y nom NX + + ou mieux (sans avoir (Xeid, Yeid) et (Yeid, Xeid) dans les résultats) :: + + Personne X,Y where X nom NX, Y nom NX, X eid XE, Y eid > XE