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'