--- a/doc/book/en/20-08-rql.en.txt Thu Nov 20 20:36:03 2008 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,213 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-RQL language (Relation Query Language)
-======================================
-
-XXXFIXME MERGE WITH 16-rql.en.txt
-
-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'