.. -*- coding: utf-8 -*-

RQL language (Relation Query Language)
========================================

Introduction
------------
* RQL language focuses on browsing relations.
* Attributes are considered as particular relations.
* RQL is inspired from SQL but is a high level language.
* A good knowledge of Erudi's schemas defining the application is required.


Types of requests
-----------------

Search (`Any`)
  query the repository to extract entities and/or attributes.

Insertion (`INSERT`)
  insert new entities in the database.

Updates of entities, creation of relations (`SET`)
  update existing entities in the database, or create relations between existing
  entities

Deletion of entities or relations (`DELETE`)
  delete existing entities and relations from the database.


Variables and typing
--------------------

Entities and values to browse and/or select are set in the query through *variables*
which should be written in capital letters.

The possible types for each variable can be deducted from the schema depending on
the conditions expressed in the query.

You can force the possible types for a variable thanks to the special relation `is`.



Built-in types
--------------
* `String` (literal: between double or single quotes).
* `Int`, `Float` (separator is '.').
* `Date`, `Datetime`, `Time` (literal: pattern YYYY/MM/DD[ hh:mm] or keywords
  `TODAY` and `NOW`).
* `Boolean` (keywords `TRUE` et `FALSE`).
* keyword `NULL`.

Operators
----------
* Logical operators: `AND`, `OR`, `,`.
* Mathematical operators: `+`, `-`, `*`, `/`.
* Comparison operators: `=`, `<`, `<=`, `>=`, `>`, `~=`, `LIKE`, `IN`.

  * The operator `=` is the default operator.

  * The operator `LIKE` / `~=` allows the use of the character `%` in a string
    to indicate that the string should start/end with a prefix/suffix::
    
      Any X WHERE X nom ~= 'Th%'
      Any X WHERE X nom LIKE '%lt'

  * The operator `IN` allows to provide a list of possible values::

      Any X WHERE X nom IN ('chauvat', 'fayolle', 'di mascio', 'thenault')

Search query
------------

  [`DISTINCT`] <entity type> V1(, V2)\*
  [`GROUPBY` V1(, V2)\*]  [`ORDERBY` <orderterms>]
  [`WHERE` <condition>] 
  [`LIMIT` <value>] [`OFFSET` <value>]

:entity type:
  Type of the selected variable
  Special type `Any` is equivalent to not specify a type
:condition:
  list of relations to browse following the pattern 
    `V1 relation V2|<static value>`
:orderterms:
  Setting of the selection order : variable or column number followed by the
  sorting method (`ASC`, `DESC`), ASC being the default value.
:note  for grouped queries:
  For grouped queries (e.g. using function `GROUPBY`), all the selected 
  variables must be grouped or aggregated.

Examples - search
`````````````````
::

      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 


Advanced features
`````````````````
* Aggregate functions : `COUNT`, `MIN`, `MAX`, `SUM`.
* String functions :`UPPER`, `LOWER`.
* Optional relations :

  * They allow to select entities related to others or not.

  * You should use `?` behind the variable to specify the relation to itself is
    optional.

    - Project anomalies related to a version or not ::

        Any X,V WHERE X concerns P, P eid 42, X corrected_in V?

    - All the cards and the project they document otherwise ::

        Any C,P WHERE C is Card, P? documented_by C

Negation
````````
* A query such as `Document X WHERE NOT X owned_by U` is equivalent to 
  "the documents which do not have relation `owned_by`".
* Whereas the query `Document X WHERE NOT X owned_by U, U login "syt"`
  is equivalent to "the documents which do not have relation `owned_by`
  with the user syt". They could have a relation with other users.


Identity
````````

We could use the special relation `identity` in a query in order to add a
condition of identity between two variables. This is equivalent to ``is``
in Python.

  Any A WHERE A comments B, A identity B

returns the set of objects which comment themselves. The relation `identity`
is very usefull while defining security rules with `RQLExpressions`.

Insertion queries
-----------------
   `INSERT` <entity type> V1(, <entity type> V2)\* `:` <assignments>
   [`WHERE` <condition>] 

:assignments:
  list of relations to assign such as `V1 relation V2|<static value>`

The condition allow to define the variables we would use in assignments.

Be careful, if a condition is specified, the insertion is done *for each result
returned by the condition*.
 
Examples - insertion
`````````````````````
* Insertion of a new person named 'bidule'::

       INSERT Person X: X name 'bidule'

* Insertion of a new person named 'bidule', another named
  'chouette' and a relation 'friend' between them::

       INSERT Person X, Person Y: X name 'bidule', Y name 'chouette', X friend Y

* Insertion of a new person named 'bidule' and a relation 'friend'with an 
  existing person 'chouette'::

       INSERT Person X: X name 'bidule', X friend Y WHERE Y name 'chouette'


Update queries
--------------
   `SET` <assignments>
   [`WHERE` <condition>] 

Be careful, if a condition is specified, the update is done *for each result
returned by the condition*.

Examples - update 
`````````````````
* Renaming of the person named 'bidule' to 'toto', with change on the first name::

       SET X name 'toto', X firstname 'original' WHERE X is 'Person', X name 'bidule'

* Insertion of a relation of type 'know' between two objects linked with the relation
  of type 'friend' ::

       SET X know Y WHERE X friend Y

Deletion queries
----------------
   `DELETE` (<entity type> V) | (V1 relation v2),...
   [`WHERE` <condition>] 


Be careful, if a condition is specified, the deletion is done *for each result
returned by the condition*.


Examples
````````
* Deletion of the person named 'toto'::

       DELETE Person X WHERE X name 'toto'

* Deletion of all the relations of type 'friend' linked to the person named 
  'toto'::

       DELETE X friend Y WHERE X is 'Person', X name 'toto'