--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/08-rql.en.txt Fri Nov 14 11:05:32 2008 +0100
@@ -0,0 +1,211 @@
+.. -*- 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'