--- /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] <type d'entité> V1(, V2)*
+ [GROUPBY V1(, V2)*] [ORDERBY <orderterms>]
+ [WHERE <restriction>]
+ [LIMIT <value>] [OFFSET <value>]
+
+: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|<valeur constante>`
+: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