doc/book/en/C040-rql.en.txt
changeset 127 ae611743f5c6
parent 115 4b66ad23fbd1
child 209 38a9c240ac64
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/C040-rql.en.txt	Sat Nov 22 23:59:42 2008 +0100
@@ -0,0 +1,216 @@
+.. -*- coding: utf-8 -*-
+
+RQL language (Relation Query Language)
+======================================
+
+XXX see also RQL documentation in source rql/doc.
+
+
+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'
+
+