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'