--- a/goa/doc/devmanual_fr/chap_rql.txt Fri Sep 24 18:20:57 2010 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,196 +0,0 @@
-Le langage RQL (Relation Query Language)
-========================================
-
-Présentation
-------------
-* 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 CubicWeb définissant l'application est nécessaire.
-
-
-Les différents types de requêtes
---------------------------------
-Recherche (`Any`)
- interroger l'entrepôt afin d'extraire des entités et/ou des attributs
- d'entités.
-
-Insertion (`INSERT`)
- insérer de nouvelles entités dans la base.
-
-Mise à jour d'entités, création de relations (`SET`)
- mettre à jours des entités existantes dans la base, ou de créer des
- relations entres des entités existantes.
-
-Suppression d'entités ou de relation (`DELETE`)
- supprimer des entités et relations existantes dans la base.
-
-
-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')
-
-Requête 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 selection : 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:
- Pour les requêtes groupées (i.e. avec une clause `GROUPBY`), toutes les
- variables sélectionnée doivent être soit groupée soit aggrégée.
-
-Exemples - recherche
-`````````````````````
-::
-
- Any X WHERE X eid 53
- Personne X
- Personne X WHERE X travaille_pour S, S nom "logilab"
- Any E,COUNT(X) GROUPBY E ORDERBY EN WHERE X is E, E name EN
- Any E,COUNT(X) GROUPBY E ORDERBY 2 WHERE X is E
-
-
-Fonctionnalités avancées
-````````````````````````
-* Fonctions d'aggrégat : `COUNT`, `MIN`, `MAX`, `SUM`.
-* Fonctions sur les chaines :`UPPER`, `LOWER`.
-* Relations optionnelles :
-
- * Elles permettent de sélectionner des entités liées ou non à une autre.
-
- * Il faut utiliser le `?` derrière la variable pour spécifier que la relation
- vers celle-ci est optionnelle :
-
- - Anomalies d'un projet attachées ou non à une version ::
-
- Any X,V WHERE X concerns P, P eid 42, X corrected_in V?
-
- - Toutes les fiches et le projet qu'elles documentent le cas échéant ::
-
- Any C,P WHERE C is Card, P? documented_by C
-
-Négation
-````````
-* Une requête du type `Document X WHERE NOT X owned_by U` revient à dire "les
- documents n'ayant pas de relation `owned_by`".
-* En revanche la requête `Document X WHERE NOT X owned_by U, U login "syt"`
- revient à dire "les documents n'ayant pas de relation `owned_by` avec
- l'utilisateur syt". Ils peuvent avoir une relation "owned_by" avec un autre
- utilisateur.
-
-
-Requête d'insertion
--------------------
- `INSERT` <type d'entité> V1(, <type d'entité> V2)\* `:` <assignements>
- [`WHERE` <restriction>]
-
-:assignements:
- liste des relations à assigner sous la forme `V1 relation V2|<valeur constante>`
-
-La restriction permet de définir des variables utilisées dans les assignements.
-
-Attention, si une restriction est spécifiée, l'insertion est effectuée *pour
-chaque ligne de résultat renvoyée par la restriction*.
-
-Exemples - insertion
-`````````````````````
-* Insertion d'une nouvelle personne nommée 'bidule'::
-
- INSERT Personne X: X nom 'bidule'
-
-* Insertion d'une nouvelle personne nommée 'bidule', d'une autre nommée
- 'chouette' et d'une relation 'ami' entre eux::
-
- INSERT Personne X, Personne Y: X nom 'bidule', Y nom 'chouette', X ami Y
-
-* Insertion d'une nouvelle personne nommée 'bidule' et d'une relation 'ami' avec
- une personne existante nommée 'chouette'::
-
- INSERT Personne X: X nom 'bidule', X ami Y WHERE Y nom 'chouette'
-
-
-Requête de mise à jour
-----------------------
- `SET` <assignements>
- [`WHERE` <restriction>]
-
-Attention, si une restriction est spécifiée, la mise à jour est effectuée *pour
-chaque ligne de résultat renvoyée par la restriction*.
-
-Exemples - mise à jour
-````````````````````````
-* Renommage de la personne nommée 'bidule' en 'toto', avec modification du
- prénom::
-
- SET X nom 'toto', X prenom 'original' WHERE X is 'Person', X nom 'bidule'
-
-* Insertion d'une relation de type 'connait' entre les objets reliés par la
- relation de type 'ami'::
-
- SET X know Y WHERE X ami Y
-
-Requête de suppression
-----------------------
- `DELETE` (<type d''entité> V) | (V1 relation v2),...
- [`WHERE` <restriction>]
-
-Attention, si une restriction est spécifiée, la suppression est effectuée *pour
-chaque ligne de résultat renvoyée par la restriction*.
-
-Exemples
-````````
-* Suppression de la personne nommé 'toto'::
-
- DELETE Person X WHERE X nom 'toto'
-
-* Suppression de toutes les relations de type 'ami' partant de la personne
- nommée 'toto'::
-
- DELETE X ami Y WHERE X is 'Person', X nom 'toto'